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

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

حالة المكتبة

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

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

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

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

تاريخ آخر تعديل: يوليو 2024

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

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

بعد الانتقال إلى واجهات برمجة تطبيقات FedCM، لن تعود مكتبة منصة "تسجيل الدخول بحساب Google" متاحة بحظر ملفات تعريف الارتباط التابعة لجهات خارجية. للاطّلاع على آخر الأخبار حول ملفات تعريف الارتباط التابعة لجهات خارجية حظر المحتوى، يُرجى الاطّلاع على المخطط الزمني لـ "مبادرة حماية الخصوصية" في Chrome.

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

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

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

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

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

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

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

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

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

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

    • #fedcm-authz مُفعَّل، إذا كان موقعك الإلكتروني يستخدم سياسة أمان المحتوى التي تحظر https://accounts.google.com/gsi/ottoken.
    • تم تفعيل #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" عادةً ما تكون هذه الخطوة غير ضرورية نظرًا لأن أحدث إصدار من المكتبة يتم تنزيله مباشرةً إلى المتصفح من خلال تضمين 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) المعتمَدة لإعادة التوجيه تتضمّن معرّفات الموارد المنتظمة (URI) الخاصة بإعادة التوجيه المخطط واسم المضيف المؤهّل بالكامل والمسار ويجب أن يلتزم بقواعد التحقّق من معرّف الموارد المنتظم (URI) لإعادة التوجيه. على سبيل المثال: https://www.example.com/auth-receiver

الاختبار

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

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

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

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

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

الاطّلاع على سياسة أذونات إطار iframe

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

بعد اتّباع خطوات تحديد مكان طلب مكتبة "تسجيل الدخول بحساب Google" يمكنك اختيار طلب مكتبة "تسجيل الدخول بحساب Google" في "أدوات مطوّري البرامج" لوحة الشبكة وحدِّد مكان عنوان Sec-Fetch-Site في قسم طلب العناوين في علامة التبويب العناوين إذا كانت قيمة العنوان :

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

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

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

في حال العثور على إطار iframe، افحص المستند للتحقق من وجود اتصالات مع gapi.auth2 الدوال أو script src التي تحمِّل مكتبة "تسجيل الدخول بحساب Google" داخل 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 متطلبات تفعيل المستخدم المعدَّلة. سيؤدي الضغط على زر ما أو النقر على رابط هي أمثلة على إيماءات المستخدمين التي تسمح بمصادر تابعة لجهات خارجية لإجراء طلبات الشبكة أو لتخزين البيانات. باستخدام FedCM، يطالب المتصفح موافقة المستخدم في الحالات التالية:

  • تسجيل دخول المستخدم لأول مرة إلى تطبيق ويب باستخدام مثيل متصفح جديد، أو
  • تسمّى GoogleAuth.signIn.

أما اليوم، إذا سجَّل المستخدم الدخول إلى موقعك الإلكتروني من قبل، يمكنك الحصول على معلومات تسجيل دخول المستخدم عند إعداد مكتبة تسجيل الدخول بحساب Google باستخدام gapi.auth2.init، بدون أي تفاعلات إضافية من المستخدم.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    تم إعداد المكتبة باستخدام حدث onload لـ platform.js التي تستخدم دالة بدء لاستدعاء 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.