إنشاء دفق تسجيل الدخول يدويًا

بالنسبة لتسجيل الدخول المستند إلى المتصفح لتطبيق الويب أو أجهزة الكمبيوتر دون استخدام مجموعات SDK التي نوفرها، مثل طريقة عرض الويب لتطبيق أجهزة الكمبيوتر الأصلي (على سبيل المثال Windows 8)، أو دفق تسجيل الدخول باستخدام رمز من جانب الخادم بالكامل، يمكنك إنشاء دفق تسجيل دخول لنفسك باستخدام عمليات إعادة توجيه المتصفح. وسيُعرفك هذا الدليل على كل خطوة من خطوات دفق تسجيل الدخول ويعرض لك كيفية تنفيذ كل خطوة بدون استخدام مجموعات SDK:

• التحقق من حالة تسجيل الدخول
• تسجيل دخول الأشخاص
• تأكيد الهوية
• تخزين رموز الوصول وحالة تسجيل الدخول
• تسجيل خروج الأشخاص
• اكتشاف عندما يحاول الأشخاص إلغاء تثبيت التطبيقات
• الرد على طلبات حذف بيانات المستخدم

التحقق من حالة تسجيل الدخول

يمكن للتطبيقات التي تستخدم مجموعات SDK أن تتحقق مما إذا كان شخص ما قد سجل الدخول بالفعل باستخدام الوظائف المدمجة. ويجب على كل التطبيقات الأخرى إنشاء طريقتها الخاصة في تخزين موعد تسجيل دخول أي شخص وعندما لا يكون ذلك المؤشر متوفرًا، تابع على افتراض أنه تم تسجيل خروج الشخص. في حالة تسجيل خروج الشخص، ينبغي على تطبيقك إعادة توجيهه إلى مربع حوار تسجيل الدخول في وقت مناسب، على سبيل المثال عند النقر على زر تسجيل الدخول.

تسجيل دخول الأشخاص

وسواء لم يسجل الشخص دخوله إلى تطبيقك أو لم يسجل دخوله إلى Facebook، فيمكنك استخدام مربع الحوار تسجيل الدخول لمطالبته بتسجيل الدخول إلى كليهما. وإذا لم يتم تسجيل دخول هذا الشخص إلى Facebook، فستتم مطالبته بتسجيل الدخول ثم الانتقال إلى تسجيل الدخول إلى تطبيقك. ويتم اكتشاف هذا تلقائيًا، بحيث لا تحتاج إلى فعل أي شيء آخر لتمكين هذا السلوك.

إلغاء مربع الحوار تسجيل الدخول وإعداد عنوان URL لإعادة التوجيه

يجب على تطبيقك بدء إعادة التوجيه إلى نقطة نهاية تعرض مربع الحوار تسجيل الدخول:

https://www.facebook.com/v21.0/dialog/oauth?
  client_id={app-id}
  &redirect_uri={redirect-uri}
  &state={state-param}

تحتوي نقطة النهاية هذه على المعلمات المطلوبة التالية:

• client_id. يمثل معرف التطبيق الموجود في لوحة معلومات تطبيقك.
• redirect_uri. يمثل عنوان URL الذي تريد إعادة توجيه الشخص الذي يسجل الدخول إليه مجددًا. وسيسجل عنوان URL هذا الاستجابة من مربع الحوار تسجيل الدخول. إذا كنت تستخدم هذا في عرض الويب داخل تطبيق أجهزة كمبيوتر، فيجب تعيين هذا إلى https://www.facebook.com/connect/login_success.html. ويمكنك التأكيد على أنه تم تعيين عنوان URL هذا لتطبيقك في "لوحة معلومات التطبيق". ضمن المنتجات في قائمة التنقل بالجانب الأيمن في لوحة معلومات التطبيق، انقر على تسجيل دخول فيسبوك، ثم انقر على الإعدادات. تحقق من صحة محددات URI الصالحة لإعادة توجيه OAuth في القسم إعدادات OAuth للعميل.
• state. تمثل قيمة سلسلة منشأة بواسطة تطبيقك للحفاظ على الحالة بين الطلب والاستدعاء. يجب استخدام هذه المعلمة لمنع تزوير الطلب عبر الموقع وسيتم إعادة إرسالها إليك، بدون تغيير، في محدد URI لإعادة التوجيه.

على سبيل المثال، إذا كان طلب تسجيل الدخول لديك يبدو كما يلي:

https://www.facebook.com/v21.0/dialog/oauth?
  client_id={app-id}
  &redirect_uri={"https://www.domain.com/login"}
  &state={"{st=state123abc,ds=123456789}"}

فعندئذ يمكن استدعاء محدد URI لإعادة التوجيه باستخدام ما يلي:

https://www.domain.com/login?state="{st=state123abc,ds=123456789}"
    

كما يتضمن هذا المعلمات الاختيارية التالية:

• response_type. يحدد ما إذا كانت بيانات الاستجابة مُضمنة عند حدوث إعادة التوجيه مجددًا إلى التطبيق في أجزاء أو معلمات عنوان URL أم لا. راجع القسم تأكيد الهوية لاختيار النوع الذي يجب أن يستخدمه تطبيقك. يمكن أن يكون هذا واحدًا مما يلي:

  • code. يتم تضمين بيانات الاستجابة كمعلمات عنوان URL وتحتوي على المعلمة code (سلسلة مشفّرة فريدة لكل طلب تسجيل دخول). وهذا هو السلوك الافتراضي إذا لم يتم تحديد هذه المعلمة. يكون الأمر مفيدًا للغاية عندما يعالج الخادم الرمز.
  • token. يتم تضمين بيانات الاستجابة باعتبارها جزءًا من عنوان URL وتحتوي على رمز وصول. ويجب على تطبيقات أجهزة الكمبيوتر استخدام هذا الإعداد من أجل response_type. يكون هذا الأمر مفيدًا للغاية عندما يعالج العميل الرمز.
  • code%20token. يتم تضمين بيانات الاستجابة باعتبارها جزءًا من عنوان URL وتحتوي على كل من رمز وصول والمعلمة code.
  • granted_scopes. يُرجع قائمة مفصولة بفواصل تضم كل الأذونات الممنوحة للتطبيق بواسطة المستخدم في وقت تسجيل الدخول. ويمكن دمجها مع قيم response_type الأخرى. عند الدمج مع token، يتم تضمين بيانات الاستجابة باعتبارها جزءًا من عنوان URL وبخلاف ذلك يتم تضمينها باعتبارها معلمة عنوان URL.
• scope. قائمة مفصولة بفاصلة أو مسافة تضم الأذونات التي تحتاج إلى أن تطلبها من الشخص الذي يستخدم تطبيقك.

بالنسبة لتطبيقات نظام Windows 8

إذا كنت تنشئ تسجيل دخول لتطبيق في نظام Windows، فيمكنك استخدام معرف أمان الحزمة باعتباره معرف redirect_uri الخاص بك. يمكنك تشغيل مربع الحوار تسجيل الدخول عن طريق استدعاء WebAuthenticationBroker.AuthenticateAsync واستخدام نقطة نهاية مربع الحوار تسجيل الدخول باعتبارها requestUri. فيما يلي مثال بلغة JavaScript:

var requestUri = new Windows.Foundation.Uri(
  "https://www.facebook.com/v21.0/dialog/oauth?
    client_id={app-id}
    &display=popup
    &response_type=token
    &redirect_uri=ms-app://{package-security-identifier}");

Windows.Security.Authentication.Web.WebAuthenticationBroker.authenticateAsync(
  options,
  requestUri)
  .done(function (result) {
    // Handle the response from the Login Dialog
  }
);

سيؤدي هذا إلى إرجاع تدفق التحكم مجددًا إلى تطبيقك من خلال رمز وصول عند النجاح أو خطأ عند الفشل.

معالجة استجابة مربع حوار تسجيل الدخول

عند هذه المرحلة في تدفق تسجيل الدخول، سيرى الشخص مربع الحوار تسجيل الدخول وسيكون لديه خيار إلغاء وصول التطبيق إلى بياناته أو السماح له.

إذا اختار الشخص الذي يستخدم التطبيق "موافق" في مربع الحوار تسجيل الدخول، فإنه يمنح الوصول إلى ملفه الشخصي العام وقائمة الأصدقاء وأي أذونات إضافية قد طلبها تطبيقك.

في كل الحالات، يعود المتصفح إلى التطبيق ويتم تضمين بيانات الاستجابة التي توضح ما إذا كان الشخص متصلاً أو تم إلغاء اتصاله. عندما يستخدم تطبيقك طريقة إعادة التوجيه كما هو مذكور أعلاه، سيتم إلحاق redirect_uri الذي يرجعه تطبيقك بأجزاء أو معلمات عنوان URL (وفقًا لـ response_type المحدد)، الذي يجب تسجيله.

نظرًا للتركيبات المختلفة للغات الرموز البرمجية التي يمكن استخدامها في تطبيقات الويب، لا يعرض الدليل أمثلة محددة. ومع ذلك، يمكن لمعظم اللغات الحديثة تحليل عنوان URL، كما يلي:

يمكن للغة JavaScript من جانب العميل الحصول على أجزاء عنوان URL (على سبيل المثال jQuery BBQ)، بينما يمكن الحصول على معلمات عنوان URL بواسطة كل من الرمز من جانب العميل والرمز من جانب الخادم (على سبيل المثال بلغة $_GET PHP أو jQuery.deparam jQuery BBQ أو querystring.parse Node.js أو urlparse Python). توفر Microsoft دليلاً وعينة من الرمز لتطبيقات نظام Windows 8 المتصلة بـ "بموفر خدمة عبر الإنترنت"، والذي يكون في هذه الحالة، فيسبوك.

https://www.facebook.com/connect/login_success.html#
    access_token=ACCESS_TOKEN...

تسجيل الدخول المُلغى

إذا لم يقبل الأشخاص الذين يستخدمون تطبيقك مربع الحوار تسجيل الدخول ونقروا على "إلغاء"، فستتم إعادة توجيههم إلى ما يلي:

YOUR_REDIRECT_URI?
 error_reason=user_denied
 &error=access_denied
 &error_description=Permissions+error.

راجع معالجة الأذونات المفقودةلمعرفة المزيد حول ما يجب أن تفعله التطبيقات عندما يرفض الأشخاص تسجيل الدخول.

تأكيد الهوية

ونظرًا لأن تدفق إعادة التوجيه هذا يتضمن المتصفحات التي تتم إعادة توجيهها إلى عناوين URL في تطبيقك من مربع الحوار تسجيل الدخول، يمكن للزيارات الوصول مباشرةً إلى عنوان URL هذا باستخدام معلمات أو أجزاء مركبة. إذا افترض تطبيقك أن هذه المعلمات صالحة، فسيستخدم تطبيقك البيانات المركبة لأغراض يحتمل أن تكون ضارة. ونتيجة لذلك، يجب على تطبيقك التأكيد على أن الشخص الذي يستخدم التطبيق هو الشخص نفسه الذي تمتلك بيانات استجابة له قبل إنشاء رمز وصول من أجله. يتم تأكيد الهوية بطرق مختلفة بناءً على response_type الذي تم تلقيه أعلاه:

• عندما يتم تلقي code، يجب استبداله مع رمز وصول باستخدام نقطة نهاية. ويجب أن يكون الاستدعاء من خادم إلى خادم، لأنه يتضمن المفتاح السري لتطبيقك. (يجب عدم إظهار المفتاح السري لتطبيقك في الرمز البرمجي للعميل.)
• عند تلقي token، يجب التحقق من صحته. ويجب إجراء استدعاء واجهة API لنقطة نهاية الفحص التي ستوضح لمن تم إنشاء الرمز المميز وبواسطة أي تطبيق. ونظرًا لأن استدعاء واجهة API هذا يتطلب استخدام رمز وصول التطبيق، فلا تقم أبدًا بإجراء هذا الاستدعاء من جانب العميل. وبدلاً من ذلك يمكنك إجراء هذا الاستدعاء من جانب الخادم، حيث يمكنك تخزين المفتاح السري لتطبيقك بأمان.
• عند تلقي كل من code وtoken، يجب تنفيذ كلتا الخطوتين.

لاحظ أنه يمكنك أيضًا إنشاء المعلمة state الخاصة بك واستخدامها مع طلب تسجيل الدخول لديك لتوفير حماية CSRF.

استبدال الرمز بواسطة رمز وصول

للحصول على رمز وصول، يمكنك إجراء طلب HTTP GET إلى نقطة نهاية OAuth التالية:

GET https://graph.facebook.com/v21.0/oauth/access_token?
   client_id={app-id}
   &redirect_uri={redirect-uri}
   &client_secret={app-secret}
   &code={code-parameter}

تحتوي نقطة النهاية هذه على بعض المعلمات المطلوبة:

• client_id. يمثل معرفات تطبيقك
• redirect_uri. هذه الوسيطة مطلوبة ويجب أن تكون مماثلة لمحدد request_uri الأصلي الذي استخدمته عند بدء عملية تسجيل دخول OAuth.
• client_secret. يمثل المفتاح السري لتطبيقك، المعروض في لوحة معلومات التطبيق. وتجنَّب تمامًا تضمين هذا المفتاح السري للتطبيق في أي رمز برمجي من جانب العميل أو في الملفات الثنائية التي يمكن تحويلها برمجيًا. ومن المهم للغاية أن يظل هذا سريًا تمامًا لأنه أساس أمان تطبيقك وكل الأشخاص الذين يستخدمونه.
• code. يمثل المعلمة المستلمة من إعادة توجيه مربع الحوار تسجيل الدخول أعلاه.

ملاحظة: بدءًا من الإصدار 2.3 وما بعده، ستُرجع نقطة النهاية هذه استجابة JSON مناسبة. وإذا لم يحدد استدعاؤك إصدارًا بعينه، فسيتم تعيينه افتراضيًا على أقدم إصدار متوفر.

الاستجابة

سيتم إرجاع الاستجابة التي ستتلقاها من نقطة النهاية هذه بتنسيق JSON، وفي حالة نجاح العملية، ستكون:

{
  "access_token": {access-token}, 
  "token_type": {type},
  "expires_in":  {seconds-til-expiration}
}

إذا لم تنجح، فستتلقى رسالة خطأ توضيحية.

فحص رموز الوصول

سواء كان تطبيقك يستخدم code أو token باعتبارهما response_type الخاص بك من مربع الحوار تسجيل الدخول أم لا، فسيتلقى رمز وصول. ويمكنك تنفيذ فحوصات مؤتمتة على هذه الرموز باستخدام نقطة نهاية واجهة Graph API:

GET graph.facebook.com/debug_token?
     input_token={token-to-inspect}
     &access_token={app-token-or-admin-token}

تتطلب نقطة النهاية هذه المعلمات التالية:

• input_token. يمثل الرمز الذي تحتاج إلى فحصه.
• يمثل access_tokenرمز وصول التطبيق أو رمز وصول لمطوّر التطبيق.

تمثل استجابة استدعاء واجهة API مصفوفة JSON تحتوي على بيانات عن الرمز الذي تم فحصه. على سبيل المثال:

{
    "data": {
        "app_id": 138483919580948, 
        "type": "USER",
        "application": "Social Cafe", 
        "expires_at": 1352419328, 
        "is_valid": true, 
        "issued_at": 1347235328, 
        "metadata": {
            "sso": "iphone-safari"
        }, 
        "scopes": [
            "email", 
            "publish_actions"
        ], 
        "user_id": "1207059"
    }
}

يساعد الحقلان app_id وuser_id تطبيقك على التحقق من صلاحية رمز الوصول للشخص ولتطبيقك. وللاطّلاع على وصف كامل للحقول الأخرى، راجع دليل الحصول على معلومات عن رموز الوصول.

فحص الأذونات

يمكن استدعاء عنصر الربط /me/permissions لاسترداد قائمة الأذونات التي تم منحها أو رفضها بواسطة مستخدم معين. ويمكن لتطبيقك استخدام هذا للتحقق من الأذونات المطلوبة التي لا يمكن أن يستخدمها التطبيق لأي مستخدم معين.

إعادة طلب الأذونات المرفوضة

يتيح تسجيل دخول فيسبوك للأشخاص رفض مشاركة بعض الأذونات مع تطبيقك. ويحتوي مربع حوار تسجيل الدخول على شاشة تبدو على النحو التالي:

عادةً ما يكون الإذن public_profile مطلوبًا دائمًا وغير نشط لعدم توفر إمكانية تعطيله.

ومع ذلك، إذا حاول شخص ما إلغاء تحديد user_likes (تسجيلات الإعجاب) في هذا المثال، فإن التحقق من /me/permissions بحثًا عن الأذونات التي تم منحها سيؤدي إلى:

{
  "data":
    [
      {
        "permission":"public_profile",
        "status":"granted"
      },
      {
        "permission":"user_likes",
        "status":"declined"
      }
    ]
}

لاحظ أنه تم رفض الإذن user_likes بدلاً من منحه.

لا توجد مشكلة في أن تطلب مرة أخرى من شخص ما أن يمنحك أذونات التطبيق التي رفضها. وينبغي أن توفر شاشة توضح الأسباب التي تقنع الشخص بمنحك الإذن، وبعد ذلك أعد طلب الإذن. ولكن إذا قمت بإلغاء مربع الحوار تسجيل الدخول كما في السابق، فلن يطلب هذا الإذن.

يرجع هذا إلى أنه بمجرد رفض الشخص للإذن، لا يعيد مربع حوار تسجيل الدخول طلبه، ما لم تخبر مربع الحوار بوضوح بأنك تعيد طلب إذن تم رفضه.

يمكنك إجراء ذلك من خلال إضافة المعلمة auth_type=rerequest إلى عنوان URL لمربع الحوار تسجيل الدخول لديك:

https://www.facebook.com/v21.0/dialog/oauth?
    client_id={app-id}
    &redirect_uri={redirect-uri}
    &auth_type=rerequest
    scope=email
   

باستخدام هذا، سيعيد مربع الحوار تسجيل الدخول طلب الإذن المرفوض.

تخزين رموز الوصول وحالة تسجيل الدخول

عند هذه المرحلة في التدفق، يتوفر لديك شخص ما قد تمت مصادقته وتسجيل دخوله. وأصبح تطبيقك مستعدًا لإجراء استدعاءات API نيابة عنه. وقبل إجراء ذلك، يجب تخزين رمز الوصول وحالة تسجيل الدخول للشخص الذي يستخدم التطبيق.

تخزين رموز الوصول

بعد حصول تطبيقك على رمز الوصول من الخطوة السابقة، ينبغي تخزين الرمز بحيث يتوفر لكل أجزاء التطبيق عند إجراء استدعاءات API. ولا توجد عملية محددة هنا، لكن بشكل عام إذا كنت تُنشئ تطبيق ويب، فمن الأفضل إضافة الرمز كمتغير جلسة لتحديد جلسة المتصفح هذه مع شخص معين، وإذا كنت تُنشئ تطبيق هاتف محمول أو جهاز كمبيوتر أصلي، فيجب حينها استخدام مخزن البيانات المتوفر لتطبيقك. كما يجب على التطبيق تخزين الرمز في قاعدة البيانات بجانب المعرف user_id لتحديده.

يرجى الاطّلاع على ملاحظتنا بشأن حجم رموز الوصول في مستند رمز الوصول.

تتبع حالة تسجيل الدخول

مرة أخرى، ينبغي على تطبيقك تخزين حالة تسجيل دخول الشخص، وهو ما يساعد على تجنب الاضطرار لإجراء استدعاءات إضافية لمربع الحوار تسجيل الدخول. وأيًا كان الإجراء الذي اخترته، قم بتعديل التحقق من حالة تسجيل الدخول لديك لتوضيحه.

تسجيل خروج الأشخاص

يمكنك تسجيل خروج الأشخاص من تطبيقك من خلال إلغاء أي مؤشر حالة تسجيل دخول قمت بإضافته، على سبيل المثال حذف الجلسة التي تشير إلى أن الشخص قد سجل الدخول. كما يجب عليك إزالة رمز الوصول الذي تم تخزينه.

تسجيل خروج شخص ما ليس مماثلاً لإلغاء إذن تسجيل الدخول (إزالة المصادقة الممنوحة مسبقًا)، الذي يمكن تنفيذه بشكل منفصل. لذلك، أنشئ تطبيقك بحيث لا يجبر الأشخاص الذين سجلوا خروجهم على العودة لمربع الحوار تسجيل الدخول تلقائيًا.

اكتشاف عندما يحاول الأشخاص إلغاء تثبيت التطبيقات

يمكن للأشخاص إلغاء تثبيت التطبيقات عبر Facebook.com من دون التفاعل مع التطبيق نفسه. لمساعدة التطبيقات في اكتشاف الأمر عند حدوثه، نسمح لها بتوفير عنوان URL الاستدعاء لإلغاء التصريح الذي سيتم تحديده عند حدوث ذلك.

يمكنك تمكين إلغاء تصريح الاستدعاء عبر لوحة معلومات التطبيق.

الرد على طلبات حذف بيانات المستخدم

يمكن للأشخاص مطالبة أي تطبيق بحذف المعلومات المتعلقة بهم التي تم تلقيها من Facebook. وللاستجابة إلى هذه الطلبات، راجع استدعاء طلب حذف البيانات.