تسجيل الدخول بحساب Google باستخدام واجهات برمجة تطبيقات FedCM

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

حالة المكتبة

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

يضيف تحديث متوافق مع الأنظمة القديمة واجهات برمجة تطبيقات FedCM إلى مكتبة "تسجيل الدخول بحساب Google". على الرغم من أنّ معظم التغييرات سلسة، يُجري التحديث تغييرات على طلبات المستخدمين وسياسة أذونات إطار iframe و سياسة أمان المحتوى (CSP). قد تؤثر هذه التغييرات في تطبيق الويب الخاص بك ويتطلب إجراء تغييرات على رمز التطبيق وإعدادات الموقع الإلكتروني.

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

بعد الفترة الانتقالية، تصبح واجهات برمجة التطبيقات FedCM إلزامية لجميع تطبيقات الويب التي تستخدم مكتبة Google Sign-In.

المخطط الزمني

تاريخ آخر تعديل: سبتمبر 2024

في ما يلي التواريخ والتغييرات التي تؤثّر في سلوك تسجيل دخول المستخدمين:

  • آذار (مارس) 2023 إيقاف الدعم لمكتبة منصة "تسجيل الدخول باستخدام حساب Google" نهائيًا
  • ستبدأ فترة النقل في تموز (يوليو) 2024، وستتوفّر في مكتبة منصة "تسجيل الدخول بحساب Google" لواجهات برمجة تطبيقات FedCM. تتحكّم Google تلقائيًا في النسبة المئوية لطلبات تسجيل دخول المستخدمين باستخدام FedCM خلال هذه الفترة. يمكن للتطبيقات على الويب إلغاء هذا السلوك صراحةً باستخدام المَعلمة use_fedcm.
  • الاستخدام الإلزامي لواجهات برمجة تطبيقات FedCM من خلال مكتبة منصة "تسجيل الدخول بحساب Google" في آذار (مارس) 2025، وبعد ذلك يتم تجاهل مَعلمة use_fedcm ويستفيد جميع طلبات تسجيل دخول المستخدمين من FedCM

الخطوات التالية

هناك ثلاثة خيارات يمكنك اتّباعها:

  1. إجراء تقييم للأثر، وتعديل تطبيق الويب إذا لزم الأمر: يُقيّم هذا النهج ما إذا كانت الميزات التي تتطلّب إجراء تغييرات على تطبيق الويب قيد الاستخدام. يمكنك الاطّلاع على التعليمات في القسم التالي من هذا الدليل.
  2. نقل إلى مكتبة خدمات هوية Google (GIS). يوصى بشدة بالانتقال إلى مكتبة تسجيل الدخول الأحدث والمتوافقة. يمكنك إجراء ذلك باتّباع هذه التعليمات.
  3. عدم اتّخاذ أي إجراء: سيتم تحديث تطبيق الويب تلقائيًا عند نقل مكتبة Google Sign-in إلى واجهات برمجة التطبيقات FedCM لتسجيل دخول المستخدمين. هذا هو العمل الأقلّ، ولكن هناك بعض المخاطر التي قد تؤدي إلى عدم تمكّن المستخدمين من تسجيل الدخول إلى تطبيق الويب.

إجراء تقييم للأثر

اتّبِع التعليمات التالية لتحديد ما إذا كان بإمكانك تحديث تطبيق الويب بسلاسة من خلال تحديث متوافق مع الإصدارات القديمة أو ما إذا كانت التغييرات ضرورية لتجنُّب عدم تمكّن المستخدمين من تسجيل الدخول عندما تتبنّى مكتبة منصة Google Sign-in بالكامل واجهات برمجة تطبيقات FedCM.

ضبط إعدادات الجهاز

إنّ واجهات برمجة تطبيقات المتصفّح وأحدث إصدار من مكتبة منصة Google Sign-In ضروريان لاستخدام FedCM أثناء تسجيل دخول المستخدم.

قبل المتابعة:

  • ثبِّت أحدث إصدار من Chrome للكمبيوتر المكتبي. يتطلب متصفّح Chrome لنظام التشغيل Android الإصدار M128 أو إصدارًا أحدث، ولا يمكن اختباره باستخدام إصدارات أقدم.

  • افتح chrome://flags واضبط الميزات التالية على القيم التالية:

    • #fedcm-authz مفعَّل
    • #tracking-protection-3pcd مفعَّل
    • #third-party-cookie-deprecation-trial غير مفعَّل
    • تم إيقاف #tpcd-metadata-grants
    • #tpcd-heuristics-grants غير مفعّلة

    ثم أعِد تشغيل Chrome.

  • اضبط السمة use_fedcm على true عند إعداد مكتبة منصة "تسجيل الدخول بحساب Google" في تطبيق الويب. تظهر عملية الإعداد عادةً على النحو التالي:

    • gapi.client.init({use_fedcm: true}) أو
    • gapi.auth2.init({use_fedcm: true})، أو
    • gapi.auth2.authorize({use_fedcm: true}).

  • يجب إلغاء صلاحية النُسخ المخزّنة مؤقتًا من مكتبة منصة Google Sign-in. لا تكون هذه الخطوة ضرورية عادةً لأنّ أحدث إصدار من المكتبة يتم تنزيله مباشرةً إلى المتصفّح من خلال تضمين api.js أو client.js أو platform.js في علامة <script src> (قد يستخدم الطلب أيًا من أسماء الحِزم التالية للمكتبة).

  • تأكَّد من إعدادات OAuth لمعرِّف عميل OAuth:

    1. افتح صفحة "بيانات الاعتماد" في Google API Console.

    2. تأكَّد من أنّ معرّف الموارد المنتظم (URI) لموقعك الإلكتروني مُدرَج في مصادر JavaScript المسموح بها. يتضمّن معرّف الموارد المنتظم (URI) المخطّط و اسم المضيف المؤهَّل بالكامل فقط. مثلاً: https://www.example.com

    3. اختياريًا، يمكن عرض بيانات الاعتماد باستخدام إعادة توجيه إلى نقطة نهاية تستضيفها بدلاً من استدعاء JavaScript. وفي هذه الحالة، تأكَّد من تضمين معرّفات الموارد المنتظمة (URI) الخاصة بإعادة التوجيه في معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه. تتضمّن معرّفات الموارد المنتظمة لإعادة التوجيه المخطط واسم المضيف المؤهّل بالكامل والمسار، ويجب أن تكون متوافقة مع قواعد التحقّق من معرّفات الموارد المنتظمة لإعادة التوجيه. على سبيل المثال، https://www.example.com/auth-receiver.

الاختبار

بعد اتّباع التعليمات الواردة في عملية الإعداد:

تحديد طلب مكتبة "تسجيل الدخول بحساب Google"

تحقَّق مما إذا كان تغيير سياسة الأذونات وسياسة أمان المحتوى ضروريًا من خلال فحص طلب مكتبة منصة "تسجيل الدخول بحساب Google". لإجراء ذلك، حدِّد مكان الطلب باستخدام اسم المكتبة وأصلها:

  • في Chrome، افتح لوحة الشبكة في "أدوات مطوّري البرامج" وأعِد تحميل الصفحة.
  • استخدِم القيم في عمودَي النطاق والاسم لتحديد موقع المكتبة request:
    • النطاق هو apis.google.com
    • الاسم هو api.js أو client.js أو platform.js. تعتمد قيمة الاسم المحددة على حزمة المكتبة التي يطلبها المستند.

على سبيل المثال، يمكنك الفلترة حسب apis.google.com في عمود النطاق وplatform.js في عمود الاسم.

التحقّق من سياسة أذونات إطار iframe

قد يستخدم موقعك الإلكتروني مكتبة منصة Google Sign-in داخل إطار div متعدّد المصادر. في هذه الحالة، يجب تحديث التطبيق.

بعد اتّباع تعليمات تحديد موقع طلب مكتبة Google Sign-in ، اختَر طلب مكتبة Google Sign-in في لوحة DevTools الشبكة وحدِّد موقع العنوان Sec-Fetch-Site في عناوين الطلبات في علامة التبويب العناوين. إذا كانت قيمة العنوان هي:

  • same-siteأو same-origin، لن يتم تطبيق سياسات الوصول من نطاقات أخرى ولن يكون هناك تغييرات مطلوبة.
  • قد يكون من الضروري إجراء تغييرات في cross-origin عند استخدام إطار iframe.

للتأكّد من توفّر إطار iframe:

  • اختيار لوحة العناصر (Elements) في "أدوات مطوري البرامج في Chrome"
  • استخدِم Ctrl-F للعثور على إطار iframe في المستند.

في حال العثور على إطار iframe، عليك فحص المستند بحثًا عن طلبات لدوالّgapi.auth2 أو توجيهات script src التي تحمِّل مكتبة Google Sign-in داخل إطار iframe. في هذه الحالة:

كرر هذه العملية لكل إطار iframe في المستند. يمكن تضمين إطارات iframe، لذا يُرجى التأكد من إضافة أمر Allow إلى جميع إطارات iframe الرئيسية المحيطة.

التحقّق من سياسة أمان المحتوى

إذا كان موقعك الإلكتروني يستخدم سياسة أمان المحتوى، قد تحتاج إلى تعديل سياسة أمان المحتوى للسماح باستخدام مكتبة "تسجيل الدخول باستخدام حساب Google".

بعد اتّباع تعليمات تحديد موقع طلب مكتبة تسجيل الدخول بحساب Google، اختَر طلب مكتبة تسجيل الدخول بحساب Google في لوحة شبكة أدوات مطوّري البرامج وابحث عن العنوان Content-Security-Policy في قسم عناوين الرد ضمن علامة التبويب العناوين.

إذا لم يتم العثور على العنوان، ليس عليك إجراء أي تغييرات. بخلاف ذلك، تحقَّق مما إذا كان أيّ من هذه التوجيهات لسياسة CSP محدّدًا في عنوان CSP وعدِّله من خلال:

  • إضافة https://apis.google.com/js/ وhttps://accounts.google.com/gsi/ وhttps://acounts.google.com/o/fedcm/ إلى أيّ من توجيهات connect-src أو default-src أو frame-src

  • الإضافة إلى https://apis.google.com/js/bundle-name.js إلى التوجيه script-src. استبدِل bundle-name.js إما بـ api.js أو client.js أو platform.jsبناءً على حزمة المكتبة التي تطلبها المستندات.

التحقّق من التغييرات في طلبات المستخدمين

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

صورة مربّع الحوار المشروط في FedCM

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

تفعيل حساب المستخدم

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

  • تسجيل المستخدِم الدخول أولاً إلى تطبيق ويب باستخدام نسخة جديدة من المتصفّح
  • يتم استدعاء GoogleAuth.signIn.

في الوقت الحالي، إذا سجّل المستخدم الدخول إلى موقعك الإلكتروني من قبل، يمكنك الحصول على معلومات تسجيل دخول المستخدم عند بدء مكتبة "تسجيل الدخول باستخدام حساب Google" باستخدام gapi.auth2.init، بدون أي تفاعلات أخرى من المستخدم. لم يعُد هذا الإجراء ممكنًا ما لم يمر المستخدم أولاً بمسار تسجيل الدخول إلى FedCM مرتين على الأقل.

من خلال تفعيل FedCM واستدعاء GoogleAuth.signIn، في المرة التالية التي يزور فيها المستخدِم نفسه موقعك الإلكتروني، يمكن أن يحصل gapi.auth2.init على معلومات تسجيل دخول المستخدِم أثناء الإعداد بدون تفاعل من المستخدِم.

حالات الاستخدام الشائعة

تتضمّن مستندات المطوّرين لـ "مكتبة تسجيل الدخول باستخدام حساب Google" أدلة ومواد برمجية لحالات الاستخدام الشائعة. يتناول هذا القسم كيفية تأثير FedCM في سلوكها.

  • دمج ميزة "تسجيل الدخول باستخدام حساب Google" في تطبيق الويب

    في هذا العرض التوضيحي، يعرض العنصر <div> وفئة الزرّ، وبالنسبة إلى المستخدمين الذين سجّلوا الدخول سابقًا، يعرض حدث الصفحة onload بيانات اعتماد المستخدم. يجب أن يتفاعل المستخدم لتسجيل الدخول وإنشاء جلسة جديدة.

    تتمّ عملية إعداد المكتبة من خلال فئة g-signin2 التي تستدعي gapi.load وgapi.auth2.init.

    تُستخدَم إيماءة مستخدِم، وهي حدث <div> عنصر onclick، لطلب auth2.signIn أثناء تسجيل الدخول أو auth2.signOut عند تسجيل الخروج.

  • إنشاء زر مخصّص لتسجيل الدخول بحساب Google

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

    يتمّ إعداد المكتبة من خلال حدث onload لمكتبة platform.js، ويتمّ عرض الزرّ من خلال gapi.signin2.render.

    إشارة المستخدم، وهي الضغط على زر تسجيل الدخول، تؤدي إلى استدعاء auth2.signIn.

    في العرض التوضيحي الثاني، يتم استخدام عنصر <div> وأنماط CSS ورسم مخصّص للتحكّم في مظهر زر تسجيل الدخول. يجب أن يتفاعل المستخدم لتسجيل الدخول وإنشاء جلسة جديدة.

    يتمّ إعداد المكتبة عند تحميل المستند باستخدام وظيفة بدء تستدعي gapi.load وgapi.auth2.init و gapi.auth2.attachClickHandler.

    توجّه إيماءة مستخدم، وهو حدث onclick ضمن عنصر <div>، auth2.signIn باستخدام auth2.attachClickHandler أثناء تسجيل الدخول أو auth2.signOut عند تسجيل الخروج.

  • مراقبة حالة جلسة المستخدم

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

    يتمّ إعداد المكتبة من خلال استدعاء gapi.load و gapi.auth2.init وgapi.auth2.attachClickHandler() مباشرةً بعد تحميل platform.js باستخدام script src.

    تؤدي إيماءة المستخدِم، وهي حدث <div> عنصر onclick، إلى استدعاء auth2.signIn باستخدام auth2.attachClickHandler أثناء تسجيل الدخول أو auth2.signOut عند تسجيل الخروج.

  • طلب أذونات إضافية

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

    يتمّ إعداد المكتبة من خلال حدث onload لمكتبة platform.js من خلال طلب إلى gapi.signin2.render.

    عند النقر على عنصر <button>، يؤدي ذلك إلى بدء طلب للحصول على مزيد من نطاقات OAuth 2.0 باستخدام googleUser.grant أو auth2.signOut عند تسجيل الخروج.

  • دمج ميزة "تسجيل الدخول باستخدام حساب Google" باستخدام مستمعي الأحداث

    في هذا العرض التجريبي، يعرض حدث الصفحة onload بيانات اعتماد المستخدمين الذين سجّلوا الدخول. يجب أن يتفاعل المستخدم لتسجيل الدخول و إنشاء جلسة جديدة.

    يتمّ إعداد المكتبة عند تحميل المستند باستخدام وظيفة بدء تستدعي gapi.load وgapi.auth2.init و gapi.auth2.attachClickHandler. بعد ذلك، يتم استخدام auth2.isSignedIn.listen و auth2.currentUser.listen لإعداد إشعار بالتغييرات التي تطرأ على حالة الجلسة. أخيرًا، يتم استدعاء auth2.SignIn لعرض بيانات الاعتماد للمستخدمين الذين سجّلوا الدخول.

    تؤدي إيماءة المستخدِم، وهي حدث <div> عنصر onclick، إلى استدعاء auth2.signIn باستخدام auth2.attachClickHandler أثناء تسجيل الدخول أو auth2.signOut عند تسجيل الخروج.

  • تسجيل الدخول باستخدام حساب Google للتطبيقات من جهة الخادم

    في هذا العرض التجريبي، يتم استخدام إيماءة المستخدم لطلب رمز مصادقة OAuth 2.0، ويُجري طلب إعادة الاتصال بوحدة JavaScript طلب AJAX لإرسال الرد إلى خادم الخلفي للتحقّق.

    يتمّ إعداد المكتبة باستخدام حدث onload لمكتبة platform.js ، والتي تستخدِم دالة start للاتّصالgapi.load و gapi.auth2.init.

    تؤدي إيماءة المستخدم، وهي النقر على عنصر <button>، إلى بدء طلب للحصول على رمز تفويض من خلال الاتصال بـ auth2.grantOfflineAccess.

  • الدخول المُوحَّد (SSO) على جميع المنصات

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

إدارة الفترة الانتقالية

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

يؤدي اختيار الموافقة إلى إرسال المستخدم عبر عملية تسجيل الدخول في FedCM، بينما يؤدي اختيار الإيقاف إلى إرسال المستخدمين من خلال مسار تسجيل الدخول الحالي. يتم التحكّم في هذا السلوك باستخدام المَعلمة use_fedcm.

اشتراك

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

إيقاف

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

بعد اكتمال عملية الاعتماد الإلزامي، يتم تجاهل أي إعدادات use_fedcm من قِبل مكتبة منصة "تسجيل الدخول باستخدام حساب Google".

الحصول على مساعدة

يمكنك البحث عن أسئلة أو طرحها على StackOverflow باستخدام علامة google-signin.