النقل إلى برنامج FedCM

يساعدك هذا الدليل في فهم التغييرات التي أدخلتها Federated Credentials Management API (FedCM) على تطبيقك على الويب.

عند تفعيل FedCM، يعرض المتصفّح طلبات المستخدمين ولا يتم استخدام ملفات تعريف الارتباط التابعة لجهات خارجية.

نظرة عامة

تتيح ميزة FedCM عمليات تسجيل دخول أكثر خصوصية بدون الحاجة إلى استخدام ملفات تعريف الارتباط التابعة لجهات خارجية. يتحكّم المتصفّح في إعدادات المستخدم ويعرض طلبات المستخدمين ويتواصل مع مقدّم خدمة تحديد الهوية، مثل Google، فقط بعد الحصول على موافقة صريحة من المستخدمين.

في معظم المواقع الإلكترونية، يتم نقل البيانات بسلاسة من خلال التحديثات المتوافقة مع الإصدارات السابقة في مكتبة JavaScript الخاصة بخدمة Google Identity Services.

معلومات جديدة حول ميزة "تسجيل الدخول تلقائيًا"

تم إطلاق الإصدار التجريبي من Federated Credential Management (FedCM) لواجهات Google Identity Services في آب (أغسطس) 2023. اختبر العديد من المطوّرين واجهة برمجة التطبيقات وقدّموا ملاحظات مفيدة.

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

في الآونة الأخيرة، أجرى Chrome تغييرًا على تجربة مستخدم عملية تسجيل الدخول التلقائي في FedCM. لا يكون إعادة التأكيد مطلوبًا إلا عند حظر ملفات تعريف الارتباط التابعة لجهات خارجية. وهذا يعني ما يلي:

  1. لا تتطلّب ميزة "تسجيل الدخول التلقائي" في FedCM إعادة التأكيد للمستخدمين المتكرّرين. إذا أعاد المستخدمون التأكيد باستخدام واجهة مستخدم FedCM، سيتم احتساب عملية إعادة التأكيد هذه ضمن متطلبات إيماءات المستخدم في ما يتعلق بفترة ما بعد 3PCD.

  2. سيتحقّق تسجيل الدخول التلقائي في FedCM من حالة إعادة التأكيد عندما يحظر المستخدمون ملفات تعريف الارتباط التابعة لجهات خارجية يدويًا اليوم أو تلقائيًا في Chrome في المستقبل.

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

بالنسبة إلى مسار تسجيل الدخول التلقائي، لن يؤدي JavaScript في GIS إلى تنشيط FedCM على إصدار قديم من Chrome (قبل M121)، حتى إذا اختار موقعك الإلكتروني تفعيل FedCM.

الاختلافات في رحلة المستخدِم

تتشابه تجارب "النقرة الواحدة" باستخدام FedCM وبدون FedCM مع اختلافات بسيطة فقط.

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

باستخدام FedCM، يعرض One Tap اسم النطاق من المستوى الأعلى بدلاً من اسم التطبيق.

استخدام FedCM بدون FedCM
مستخدم جديد في جلسة واحدة يستخدم FedCM مستخدم جديد في جلسة واحدة بدون استخدام ميزة "إدارة العملاء المتعددين"

مستخدم جلسة واحدة يعود للموقع (مع إيقاف ميزة "تسجيل الدخول تلقائيًا")

باستخدام FedCM، يعرض One Tap اسم النطاق من المستوى الأعلى بدلاً من اسم التطبيق.

استخدام FedCM بدون FedCM
رحلة المستخدِم المتكرّر الذي يستخدم جلسة واحدة باستخدام واجهة برمجة التطبيقات FedCM (مع إيقاف ميزة "تسجيل الدخول تلقائيًا") مسار المستخدِم المتكرّر في جلسة واحدة بدون FedCM (مع إيقاف تسجيل الدخول التلقائي)

مستخدم جلسة واحدة يعود للدخول (مع تفعيل ميزة "تسجيل الدخول تلقائيًا")

باستخدام FedCM، يمكن للمستخدمين النقر على X لإلغاء تسجيل الدخول التلقائي في غضون 5 ثواني بدلاً من النقر على الزر إلغاء.

استخدام FedCM بدون FedCM
مسار المستخدِم المتكرّر في جلسة واحدة باستخدام واجهة برمجة التطبيقات FedCM (مع تفعيل ميزة "تسجيل الدخول تلقائيًا") مسار المستخدِم المتكرّر الذي يُجري جلسة واحدة بدون FedCM (مع تفعيل تسجيل الدخول التلقائي)

جلسات متعددة

باستخدام FedCM، يعرض One Tap اسم النطاق من المستوى الأعلى بدلاً من اسم التطبيق.

استخدام FedCM بدون FedCM
مستخدم جلسات متعددة يستخدم FedCM مستخدم جلسات متعددة بدون FedCM

اطّلِع على صفحة الزر "تسجيل الدخول باستخدام حساب Google" للاطّلاع على مسارات المستخدِمين الرئيسية لمسار FedCM Button.

قبل البدء

تأكَّد من أنّ إعدادات المتصفّح وإصداره متوافقان مع FedCM API، ويُنصح بالتحديث إلى أحدث إصدار.

  • تتوفّر FedCM API في الإصدار 117 من Chrome أو الإصدارات الأحدث.

  • تم تفعيل إعداد تسجيل الدخول إلى خدمات تابعة لجهات خارجية في Chrome. لا يؤثر الإعداد إلا في ميزة "النقرة الواحدة"، ولا يؤثّر في مسار زر FedCM.

  • إذا كان إصدار متصفِّح Chrome هو 119 أو إصدار أقدم، افتح chrome://flags و فعِّل ميزة FedCmWithoutThirdPartyCookies التجريبية. ليس عليك اتّباع هذه الخطوة إذا كان لديك الإصدار 120 من متصفّح Chrome أو إصدار أحدث.

نقل بيانات تطبيق الويب

اتّبِع الخطوات التالية لتفعيل FedCM وتقييم التأثير المحتمل لعملية نقل البيانات، و إجراء تغييرات على تطبيق الويب الحالي إذا لزم الأمر:

1. أضِف علامة منطقية لتفعيل FedCM لميزة One Tap عند الإعداد باستخدام:

2. أضِف علامة منطقية لتفعيل FedCM لعنصر الزر عند الإعداد باستخدام: {:#fedcm_button_flag} (اختياري).

  • HTML، اضبط السمة data-use_fedcm_for_button على true ل تفعيل مسار زر FedCM. عند تفعيل مسار أزرار FedCM فقط، يمكنك أيضًا ضبط سمة data-use_fedcm_for_button على true لتفعيل ميزة الاختيار التلقائي الجديدة.

  • في JavaScript، اضبط use_fedcm_for_button على true في عنصر IdConfiguration لتفعيل مسار الزرّ في FedCM. في حال تفعيل ميزة تدفق أزرار FedCM فقط، يمكنك أيضًا ضبط سمة button_auto_select على true لتفعيل ميزة الاختيار التلقائي الجديدة.

3- أزِل استخدام طرق isDisplayMoment() وisDisplayed() وisNotDisplayed() وgetNotDisplayedReason() لميزة "النقرة الواحدة" في الرمز البرمجي.

لتحسين خصوصية المستخدم، لم يعُد المرجع google.accounts.id.prompt يعرض أي إشعارات بشأن لحظات العرض في العنصر PromptMomentNotication. أزِل أي رمز يعتمد على methods المرتبط بلحظة العرض. وهي طُرق isDisplayMoment() وisDisplayed() isNotDisplayed() وgetNotDisplayedReason().

4. أزِل استخدام طريقة getSkippedReason() لميزة "النقرة الواحدة" في الرمز البرمجي.

على الرغم من أنّه سيظلّ يتمّ استدعاء لحظة التخطّي، isSkippedMoment()، من google.accounts.id.prompt الإجراء المُعاد الاتصال به في PromptMomentNotication العنصر، لن يتمّ تقديم سبب تفصيلي. أزِل من الرمز أي رمز يعتمد على getSkippedReason().

يُرجى العلم أنّه عند تفعيل ميزة "إدارة المحتوى في الوقت الفعلي"، لن يتغيّر isDismissedMoment()، وهو إشعار اللحظة المرفوضة، وgetDismissedReason()، وهو طريقة السبب التفصيلي ذي الصلة.

5- أزِل سمات نمط position من data-prompt_parent_id وintermediate_iframes لميزة "النقرة الواحدة".

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

6- عدِّل تنسيق الصفحة إذا لزم الأمر لاستخدام ميزة "النقرة الواحدة".

يتحكّم المتصفّح في حجم طلبات المستخدمين وموضعها. استنادًا إلى تنسيق الصفحات الفردية، قد يتمّ تراكب بعض المحتوى لأنّ مواضع ميزة "النقرة الواحدة على الكمبيوتر المكتبي" المخصّصة غير متاحة بأيّ شكل من الأشكال، مثل سمة style وdata-prompt_parent_id وintermediate_iframes وإطار iframe المخصّص وطرق إبداعية أخرى.

غيِّر تنسيق الصفحة لتحسين تجربة المستخدم عندما يتم حجب معلومات مهمة. لا تبني تجربة المستخدم حول طلب One Tap حتى إذا كنت تفترض أنّه في الموضع التلقائي. بما أنّ FedCM API يتمّ التفاعل معها من خلال المتصفّح، قد يضع مورّدو المتصفّحات المختلفون موضع الطلب بشكلٍ مختلف قليلاً.

7- أضِف سمة allow="identity-credentials-get" إلى الإطار الرئيسي إذا كان تطبيق الويب يستدعي One Tap أو Button API من إطارات iframe من مصادر مختلفة.

يُعدّ إطار iframe من مصادر متعددة إذا كان مصدره غير مطابق تمامًا لمصدر الإطار الرئيسي. على سبيل المثال:

  • نطاقان مختلفان: https://example1.com وhttps://example2.com
  • نطاقات المستوى الأعلى المختلفة: https://example.uk وhttps://example.jp
  • النطاقات الفرعية: https://example.com وhttps://login.example.com

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

ولأنّ هذا التناقض قد يكون مضلِّلاً، فإنّ استخدام ميزة "النقرة الواحدة" في إطارات iframe من مصادر متعددة ولكن من الموقع الإلكتروني نفسه فقط هو طريقة متوافقة. على سبيل المثال، صفحة على النطاق https://www.example.com من المستوى الأعلى تستخدم إطار iframe لتضمين صفحة باستخدام ميزة "النقرة الواحدة" على https://login.example.com. ستظهر رسالة المطالبة بنقرة واحدة قائلة: "تسجيل الدخول إلى example.com باستخدام google.com".

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

  • استخدام زر "تسجيل الدخول باستخدام حساب Google" بدون تفعيل FedCM
  • تنفيذ ميزة "النقرة الواحدة" في نطاق المستوى الأعلى
  • استخدام نقاط نهاية Google OAuth 2.0 لدمج أكثر تخصيصًا
  • إذا كنت تضمّن موقعًا إلكترونيًا تابعًا لجهة خارجية في إطار iframe ولا يمكنك تعديل تنفيذ ميزة "النقرة الواحدة"، يمكنك منع ظهور طلب "النقرة الواحدة" داخل إطار iframe. لإجراء ذلك، أزِل سمة allow="identity-credentials-get" من علامة iframe في الإطار الرئيسي. سيؤدي ذلك إلى إيقاف الطلب، وسيكون بإمكانك توجيه المستخدمين إلى صفحة تسجيل الدخول في الموقع الإلكتروني المضمّن مباشرةً.

عند استدعاء واجهة برمجة التطبيقات One Tap أو Button API من إطارات iframe من مصادر مختلفة، عليك إضافة سمة allow="identity-credentials-get" في كل علامة iframe للإطار الرئيسي:

  <iframe src="https://your.cross-origin/onetap.page" allow="identity-credentials-get"></iframe>

إذا كان تطبيقك يستخدم إطار iframe يحتوي على إطار iframe آخر، يجب التأكّد من إضافة السمة إلى كل إطار iframe، بما في ذلك جميع إطارات iframe الفرعية.

على سبيل المثال، إليك السيناريو التالي:

  • يحتوي المستند العلوي (https://www.example.uk) على إطار iframe باسم "Iframe A"، والذي يضمّن صفحة (https://logins.example.com).

  • تحتوي هذه الصفحة المضمّنة (https://logins.example.com) أيضًا على إطار iframe يُسمى "إطار iframe ب"، والذي يضمّن بدوره صفحة (https://onetap.example2.com) تستضيف ميزة "النقرة الواحدة" أو زرًا.

    لضمان إمكانية عرض ميزة "النقرة الواحدة" أو الزر بشكل صحيح، يجب إضافة السمة إلى كلّ من علامتَي Iframe A وIframe B.

    الاستعداد للإجابة عن الاستفسارات بشأن طلب One Tap أو عدم ظهور الزر قد تضمِّن مواقع إلكترونية أخرى ذات مصادر مختلفة صفحاتك التي تستضيف ميزة "النقرة الواحدة" ضمن إطارات iframe الخاصة بها. قد تتلقّى عددًا متزايدًا من طلبات الدعم المرتبطة بعدم ظهور ميزة "النقرة الواحدة" أو الزر من المستخدمين النهائيين أو مالكي المواقع الإلكترونية الآخرين. على الرغم من أنّه لا يمكن إلا لمالكي المواقع الإلكترونية إجراء التعديلات على صفحاتهم، يمكنك اتّخاذ الإجراءات التالية للحدّ من التأثير:

  • عدِّل مستندات المطوّرين لتتضمّن كيفية إعداد عنصر iframe بشكل صحيح للاتّصال بموقعك الإلكتروني. يمكنك تضمين رابط يؤدي إلى هذه الصفحة في مستنداتك.

  • عدِّل صفحة الأسئلة الشائعة للمطوّرين إذا كان ذلك منطبقًا.

  • يُرجى إبلاغ فريق الدعم بهذا التغيير القادم والاستعداد للردّ على الاستفسار مسبقًا.

  • تواصل بشكل استباقي مع الشركاء أو العملاء أو مالكي المواقع الإلكترونية المتأثّرين لإجراء عملية نقل سلسة لميزة "إدارة العملاء المتعددين".

8. أضِف هذه التوجيهات إلى سياسة أمان المحتوى (CSP).

وهذه الخطوة اختيارية لأنّ بعض المواقع الإلكترونية لا تحدّد سياسة خدمة المحتوى.

  • إذا لم يتم استخدام CSP في موقعك الإلكتروني، ليس عليك إجراء أي تغييرات.

  • إذا كان موفِّر خدمة إدارة المحتوى (CSP) يعمل مع ميزة "النقرة الواحدة" أو الزرّ الحالي ولا تستخدم connect-src أو frame-src أو script-src أو style-src أو default-src، ليس هناك حاجة إلى إجراء تغييرات.

  • بخلاف ذلك، اتّبِع هذا الدليل لإعداد موفّر خدمة إدارة المحتوى. بدون الإعداد الصحيح لبروتوكول CSP، لن يتم عرض ميزة "النقرة أو الزرّ" في إطار عمل FedCM على الموقع الإلكتروني.

9- أزِل ميزة تسجيل الدخول باستخدام صفحات Accelerated Mobile Pages (AMP).

إنّ إتاحة تسجيل دخول المستخدمين في صفحات AMP هي ميزة اختيارية في نظام المعلومات الجغرافية (GIS) الذي قد يكون قد نفَّذه تطبيق الويب. في هذه الحالة،

احذِف أيّ إشارات إلى:

  • عنصر amp-onetap-google المخصّص 
  • <script async custom-element="amp-onetap-google" src="https://cdn.ampproject.org/v0/amp-onetap-google-0.1.js"></script>

    ننصحك بإعادة توجيه طلبات تسجيل الدخول من صفحات AMP إلى مسار تسجيل الدخول المكوّن من رمز HTML في موقعك الإلكتروني. يُرجى العلم أنّ Intermediate Iframe Support API ذات الصلة لن تتغيّر.

اختبار عملية نقل البيانات والتأكّد منها

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

  1. تأكَّد من أنّ المتصفّح متوافق مع FedCM وأنّ لديك جلسة حالية في حساب Google.

  2. انتقِل إلى صفحات "النقرة الواحدة" أو "الزر" في تطبيقك.

  3. تأكَّد من ظهور طلب One Tap أو الزر وتراكبه بأمان على المحتوى الأساسي.

  4. تأكَّد من أنّ بيانات الاعتماد الصحيحة يتم إرجاعها إلى نقطة النهاية أو طريقة طلب إعادة الاتصال عند تسجيل الدخول إلى تطبيقك باستخدام ميزة "النقرة الواحدة" أو الزر.

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

فترة الانتظار لاستخدام ميزة "نقرة واحدة"

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

فترة السكون لميزة "تسجيل الدخول تلقائيًا"

عند اختبار ميزة تسجيل الدخول تلقائيًا باستخدام One Tap من خلال FedCM، يتم تطبيق مدة راحة تبلغ 10 دقائق بين كل محاولة تسجيل دخول تلقائي. لا يمكن مجددًا إعادة ضبط فترة الهدوء. عليك الانتظار لمدة 10 دقائق أو استخدام حساب Google مختلف للاختبار من أجل تفعيل ميزة "تسجيل الدخول تلقائيًا" مرة أخرى.

مراجع مفيدة

أداة تحليل "مبادرة حماية الخصوصية" (PSAT) هي إضافة Chrome DevTools للمساعدة في اعتماد واجهات برمجة تطبيقات بديلة، مثل FedCM. ويعمل هذا الفحص من خلال فحص موقعك الإلكتروني بحثًا عن الميزات المتأثّرة وتقديم قائمة بالتغييرات المقترَحة.