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

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

حالة المكتبة

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

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

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

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

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

تاريخ آخر تعديل: أيلول (سبتمبر) 2024

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

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

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

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

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

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

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

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

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

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

  • ثبِّت أحدث إصدار من Chrome للكمبيوتر المكتبي. يتطلب متصفّح Chrome لنظام التشغيل Android الإصدار M128 أو إصدارًا أحدث، ولا يمكن اختباره باستخدام إصدارات أقدم.
  • اضبط use_fedcm على true عند بدء مكتبة منصّة Google Sign-in في تطبيق الويب. عادةً ما يكون شكل الإعداد على النحو التالي:
    • 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"

تحقّق مما إذا كان من الضروري إجراء تغييرات على permissions-policy وContent Security Policy من خلال فحص طلب مكتبة منصة Google Sign-in. لإجراء ذلك، حدِّد مكان الطلب باستخدام اسم المكتبة وأصلها:

  • في 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:

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

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

كرِّر هذه العملية لكل إطار iframe في المستند. يمكن أن تكون إطارات iframe متداخلة، لذا احرص على إضافة توجيه allow إلى كل إطارات iframe الرئيسية المحيطة.

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

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

بعد اتّباع تعليمات تحديد موقع طلب مكتبة Google Sign-in ، اختَر طلب مكتبة Google Sign-in في لوحة DevTools الشبكة وحدِّد موقع العنوان 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.

    تؤدي إيماءة المستخدِم، وهي حدث <div> عنصر onclick، إلى استدعاء 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.