دليل دمج تسجيل الدخول الاجتماعي الآمن

دليل مطوري الموبايل لربط مصادقة OAuth مع السيرفر لضمان التحقق من الحسابات بصورة آمنة.

تم استبدال طريقة تسجيل الدخول القديمة (التي كانت ترسل provider_id بشكل مباشر) بطريقة آمنة تتطلب إرسال رمز التحقق (Token) الصادر من مزود الخدمة مباشرة، ليقوم السيرفر بالتحقق من صحته بشكل موثوق.

1. نقطة الاتصال الجديدة (API Endpoint)

يستخدم هذا الرابط لإرسال رمز التحقق وإتمام عملية المصادقة:

POST /api/v1/auth/oauth/secure

الترويسات المطلوبة (Headers)

الترويسة (Header) القيمة (Value) الوصف
Content-Type application/json تحديد صيغة جسم الطلب كـ JSON.
User-Agent Dart يجب أن يحتوي على كلمة Dart (كما هو معتاد في تطبيقات Flutter).

2. بيانات الطلب (Request Parameters)

يجب إرسال مصفوفة JSON تحتوي على الحقول التالية في جسم الطلب (Request Body):

الحقل النوع الحالة الوصف
provider_name String مطلوب اسم مزود الخدمة، ويجب أن يكون أحد القيم التالية: google, facebook, apple, firebase
provider_token String مطلوب التوكن الأصلي الذي تم الحصول عليه من مزود الخدمة بعد نجاح المصادقة في الموبايل.
device_id String مطلوب المعرف الفريد للجهاز (Device ID).
device_token String مطلوب توكن الإشعارات الخاص بـ Firebase للجهاز.
name String اختياري اسم المستخدم (يُسخدم في حالة التسجيل الجديد لأول مرة).
email String اختياري البريد الإلكتروني (يُسخدم في حالة التسجيل الجديد لأول مرة).
profile_image String اختياري رابط الصورة الشخصية (يُسخدم في حالة التسجيل الجديد لأول مرة).

3. كيفية الحصول على التوكن (provider_token) في الموبايل

طريقة الحصول على التوكن الصحيح لإرساله للسيرفر باستخدام Flutter/Dart لكل مزود:

🤖

جوجل (Google Sign-In)

عند تسجيل الدخول باستخدام حزمة google_sign_in:

  • المطلوب إرساله: الـ idToken (وليس الـ accessToken أو الـ id).
final GoogleSignInAccount? googleUser = await GoogleSignIn().signIn();
final GoogleSignInAuthentication? googleAuth = await googleUser?.authentication;

final String? idToken = googleAuth?.idToken; // 👈 هذا هو التوكن المطلوب إرساله
👥

فيسبوك (Facebook Login)

عند تسجيل الدخول باستخدام حزمة flutter_facebook_auth:

  • المطلوب إرساله: الـ token الخاص بالـ AccessToken.
final LoginResult result = await FacebookAuth.instance.login();
if (result.status == LoginStatus.success) {
  final String? accessToken = result.accessToken?.token; // 👈 هذا هو التوكن المطلوب إرساله
}
🍏

آبل (Apple Sign-In)

عند تسجيل الدخول باستخدام حزمة sign_in_with_apple:

  • المطلوب إرساله: الـ identityToken (يتم تحويله إلى String).
final credential = await SignInWithApple.getAppleIDCredential(
  scopes: [
    AppleIDAuthorizationScopes.email,
    AppleIDAuthorizationScopes.fullName,
  ],
);

final String? identityToken = credential.identityToken; // 👈 هذا هو التوكن المطلوب إرساله
🔥

فايربيس (Firebase Authentication)

إذا كان التطبيق يستخدم Firebase كمصادقة موحدة لجميع المنصات:

  • المطلوب إرساله: الـ idToken الخاص بالمستخدم الحالي في Firebase.
final String? idToken = await FirebaseAuth.instance.currentUser?.getIdToken(); // 👈 هذا هو التوكن المطلوب إرساله

4. أمثلة على الطلب والاستجابة (Request / Response Samples)

نماذج توضيحية للطلبات والردود لتسهيل عملية الدمج والتحقق:

أمثلة الطلب (Google Example)

{
    "provider_name": "google",
    "provider_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjY4YTRm... [توكن جوجل الطويل للغاية]",
    "device_id": "8c459f3e-82d2-4bbf-a292-ef284920c812",
    "device_token": "f3g9sh1j4kl...",
    "name": "أحمد محمد",
    "email": "ahmed@gmail.com"
}

استجابة ناجحة (200 OK)

عند نجاح التحقق، يعيد السيرفر بيانات حساب المستخدم مصحوبة بتوكن السيرفر api_token لاستخدامه في الطلبات القادمة:

{
    "data": {
        "id": 125,
        "name": "أحمد محمد",
        "email": "ahmed@gmail.com",
        "current_profile_image_url": "...",
        "api_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." // 👈 توكن السيرفر لتصفح التطبيق
    },
    "meta": {
        "message": "auth.signed_in",
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "signed_in": true
    }
}

استجابة فاشلة (403 Forbidden)

تحدث عند إرسال توكن مزيف أو منتهي الصلاحية:

{
    "error": {
        "message": "فشل التحقق من حساب Google: رمز التحقق غير صالح أو منتهي الصلاحية"
    }
}

5. أكواد الحالة (Status Codes)

أكواد الاستجابة الأكثر شيوعاً التي يعود بها الـ API:

200 OK: تمت العملية والتحقق بنجاح.
401 Unauthorized: ترويسة الطلب مفقودة أو غير صحيحة، أو الـ User-Agent ليس Dart.
403 Forbidden: رمز التحقق (provider_token) غير صالح أو منتهي الصلاحية.
422 Unprocessable Entity: بعض المعاملات المطلوبة مفقودة.