اعتبارات التكامل

يساعدك هذا الدليل التفصيلي في اتّخاذ قرارات بشأن جميع المشاكل الرئيسية في الدمج.

نظرة عامة على ميزة "تسجيل الدخول باستخدام حساب Google"

في ما يلي الخطوات العامة التي يجب اتّباعها للمستخدمين من أجل تسجيل الدخول أو الاشتراك في موقعك الإلكتروني.

  1. يسجّل المستخدمون الدخول إلى موقع إلكتروني تابع لشركة Google.

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

  2. يتصفّح المستخدمون صفحات الويب التي تم تضمين زر "نقرة واحدة" أو "تسجيل الدخول تلقائيًا" أو "تسجيل الدخول باستخدام حساب Google" فيها.

  3. يتفاعل المستخدمون مع ميزة "نقرة واحدة" وزر "تسجيل الدخول باستخدام حساب Google" ومسارات تجارب المستخدِمين التالية بهدف:

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

    عندما تكون هناك جلسة واحدة نشطة فقط على Google في المتصفّح

    • يختار One Tap الجلسة الوحيدة تلقائيًا، وبالتالي يتخطّى صفحة اختيار الحساب.
    • يبقى الزر "تسجيل الدخول باستخدام حساب Google" متوفّرًا في صفحة اختيار الحساب، ما يسمح للمستخدمين بإضافة جلسة جديدة على Google عند الحاجة.

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

    شاشة طلب الموافقة على زر "تسجيل الدخول باستخدام حساب Google"

    بعد الموافقة، ستسجِّل Google القرار، وذلك لتخطّي صفحة الموافقة في المرة القادمة.

  4. تتم مشاركة مستند اعتماد رمز JSON المميّز للويب (يُشار إليه أيضًا باسم رمز التعريف) الذي يحتوي على اسم المستخدم وبريده الإلكتروني وصورته الشخصية باستخدام إما معالج callback لبرنامج JavaScript أو إرسال مشاركة إلى خدمة الخلفية.

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

  5. من جهة الخادم، يتم التحقّق من بيانات اعتماد JWT الصادرة عن Google و استخدامها لإنشاء حساب جديد أو إنشاء جلسة تمّت مصادقتها على موقعك الإلكتروني.

    ستدير حالة تسجيل دخول المستخدم على موقعك الإلكتروني.

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

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

الوصول إلى خدمات Google وواجهات برمجة التطبيقات

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

فصل واجهة المستخدم للمصادقة والتفويض

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

إذا كان موقعك الإلكتروني قد طلب رمزَي مصادقة وتفويض معًا في السابق، عند استخدام مكتبة JavaScript في Google Identity Services، عليك تعديل تجربة المستخدم لفصل لحظة المصادقة عن لحظة التفويض.

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

لإجراء عملية انتقال سلسة لتجربة المستخدم والحد من التعقيد، من الشائع تقسيم العملية إلى خطوتَين منفصلتَين.

  1. إعادة صياغة تجربة المستخدم لفصل لحظات المصادقة والتفويض
  2. نقل البيانات إلى مكتبة JavaScript في Google Identity Services

واجهة برمجة تطبيقات HTML API مقارنةً بواجهة برمجة تطبيقات JavaScript API

يمكنك استخدام HTML API أو JavaScript API لدمج ميزة One Tap أو ميزة "تسجيل الدخول تلقائيًا" أو زر "تسجيل الدخول باستخدام حساب Google" في صفحات الويب.

باستخدام HTML API، يمكنك الاستفادة من المزيد من الميزات المضمّنة. على سبيل المثال،

  • عرض ميزة "نقرة واحدة" أو زر "تسجيل الدخول باستخدام حساب Google" عند تحميل الصفحة
  • أرسِل بيانات الاعتماد التي تم إرجاعها إلى نقطة النهاية من جهة الخادم، والتي يتم تحديدها من خلال السمة data-login_uri، بعد الانتهاء من تجربة المستخدم في ميزة "النقرة الواحدة" أو ميزة "تسجيل الدخول التلقائي" أو النافذة المنبثقة للزر/إعادة التوجيه.
  • يمكنك منع هجمات CSRF باستخدام double-submit-cookie.
  • استخدِم أداة إنشاء الرموز لإنشاء رمز HTML، ثم انسخ الرمز والصقه في صفحات HTML.

باستخدام HTML API، يمكنك أيضًا كتابة بعض JavaScript لتخصيص السلوك.

  • يمكنك كتابة معالِج ردّ الاتصال الخاص بك، ثم ضبط اسم الدالة على سمة data-callback. ومن الأمثلة الجيدة على ذلك استخدام ملف XmlHttpRequest لإرسال بيانات الاعتماد المعروضة إلى خادمك، لتجنُّب إعادة تحميل الصفحة بسبب إرسال طلب POST التلقائي.

باستخدام JavaScript API، يمكنك الحصول على مرونة أكبر في بعض السيناريوهات.

  • عرض ميزة OneTap وزر "تسجيل الدخول باستخدام حساب Google" في وقت لاحق على سبيل المثال، بعد اختيار المستخدمين تسجيل الدخول من القائمة.
  • استدعاء واجهة برمجة التطبيقات عدة مرات على سبيل المثال، يجب عرض الزر "تسجيل الدخول باستخدام حساب Google" في كل مرة يتم فيها عرض مربّع حوار تسجيل الدخول.
  • إنشاء صفحات HTML ديناميكيًا، ما يجعل من الصعب تضمين رمز طلب البيانات من واجهة برمجة التطبيقات فيها
  • يتم تحميل مكتبة JavaScript في Google Identity Services في وقت متأخّر جدًا.

لا يمكن استدعاء رمز HTML API إلا مرة واحدة، إما في حدث تحميل الصفحة أو في حدث تحميل مكتبة JavaScript في Google Identity Services، أيهما حدث أولاً. يجب استخدام JavaScript API إذا لم يكن سلوك HTML API يلبّي توقعاتك.

لا تستخدِم واجهة برمجة التطبيقات HTML API مع واجهة برمجة التطبيقات JavaScript API في صفحة الويب نفسها ل تهيئة الصفحة أو لعرض ميزة "النقرة الواحدة" والأزرار. تحقّق من الرمز البرمجي، سواءً HTML أو JavaScript، بحثًا عن المواضع التي قد يتداخل فيها الرمز البرمجي. يُرجى ملاحظة ما يلي:

  • يعني ذلك أنّك تستخدم HTML API إذا كان هناك عنصر واحد أو أكثر من العناصر في <div id='g_id_onload' ... ><id> أو <div class='g_id_signin' ...></div> في رمز HTML.
  • يتم استخدام JavaScript API إذا تمّ استدعاء طريقة واحدة أو أكثر من الطرق الواردة في initialize() أو prompt() أو render() في رمز JavaScript، بغض النظر عما إذا كانت مضمّنة أو تم تحميلها من ملف JavaScript منفصل.

يمكن استخدام واجهات برمجة التطبيقات التالية لـ JavaScript بشكل مستقل عن بدء استخدام ميزة "النقرة الواحدة" أو عرض الأزرار، وهي لا تتضمّن واجهات برمجة تطبيقات HTML مقابلة:

اعتبارات حول زر "تسجيل الدخول باستخدام حساب Google"

يناقش هذا القسم الاعتبارات التي يجب مراعاتها عند دمج زر "تسجيل الدخول باستخدام حساب Google" في موقعك الإلكتروني.

النوافذ المنبثقة مقابل عمليات إعادة التوجيه

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

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

تتيح ميزة "تسجيل الدخول باستخدام حساب Google" تجربة مستخدم جيدة لكل من النافذة المنبثقة وعملية إعادة التوجيه. يتم استخدام تجربة المستخدم للنوافذ المنبثقة تلقائيًا. يمكنك تغيير تجربة المستخدم من خلال ضبط سمة data-ux_mode.

هناك بعض الاختلافات بين عملية إعادة التوجيه التي يوفّرها الزر "تسجيل الدخول باستخدام حساب Google" وعملية إعادة التوجيه في OAuth.

  • يستخدم مسار إعادة التوجيه لزر "تسجيل الدخول باستخدام حساب Google" دائمًا الطريقة POST لإرسال بيانات الاعتماد إلى خادم الويب، في حين يستخدم مسار إعادة التوجيه في OAuth عادةً الطريقة GET.
  • تختلف المَعلمات التي ترسلها عملية إعادة التوجيه باستخدام الزر "تسجيل الدخول باستخدام حساب Google" عن تلك الخاصة بعملية إعادة التوجيه باستخدام بروتوكول OAuth.

بالنسبة إلى المطوّرين الذين يستخدمون HTML API، بغض النظر عن تجربة المستخدم المستخدَمة، يتم دائمًا إرسال بيانات الاعتماد إلى data-login_uri باستخدام طريقة POST والمَعلمات نفسها. يتيح لك ذلك تبديل وضع تجربة المستخدم بدون تغييرات أخرى في الرمز. بالنسبة إلى تجربة المستخدم لإعادة التوجيه، يجب إضافة data-login_uri إلى معرِّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه لعميلك في وحدة تحكّم Google APIs.

تخصيص الأزرار

لا يمكنك استخدام زر خاص بك. لا تتوفّر واجهة برمجة تطبيقات لبدء مسار زر بشكل آلي.

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

تتيح لك واجهة برمجة التطبيقات Button rendering API تخصيص مظهر زر "تسجيل الدخول باستخدام حساب Google" وأسلوبه. ننصحك باستخدام أداة إنشاء الرموز البرمجية لتصميم أزرارك بشكل تفاعلي. حتى إذا كنت تستخدم JavaScript API، يمكنك إنشاء رمز HTML أولاً، ثم نسخ الرمز إلى الحقول المقابلة في JavaScript API.

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

يمكنك وضع أزرار متعددة في صفحة الويب نفسها. لا يمكن لأداة إنشاء الرموز سوى إنشاء زر واحد في كل مرة. يمكنك تشغيله عدة مرات ونسخ رمز<div class='g_id_signin' ...></div> الذي تم إنشاؤه إلى صفحة الويب.

أفضل الممارسات المتعلّقة بعرض الأزرار

لأسباب تتعلّق بالخصوصية، يتم عرض الزر المخصّص في إطار iframe من النطاق accounts.google.com. قد يستغرق تحميل إطار iframe وقتًا طويلاً على شبكة اتصالات بطيئة. للحدّ من مشكلة وقت الاستجابة هذا، يتم عرض الأزرار في خطوتَين، على النحو التالي:

  1. يتم عرض نسخة زرّ مضمّنة في شجرة DOM لموقعك الإلكتروني. هذا الزر هو زر نص فقط، ولا يمكن استخدام أي معلومات مخصّصة. والهدف من ذلك هو السماح للمستخدمين برؤية الزر في أقرب وقت ممكن.
  2. يتم إرسال طلب iframe إلى Google لتحميل iframe للزر، والذي قد يحتوي على معلومات مخصّصة. بعد تحميل إطار iframe للزر، تتم إزالة زر الإصدار المضمّن.

في ما يلي بعض أفضل الممارسات لتقليل وقت استجابة عرض مسار الزر "تسجيل الدخول باستخدام Google".

  • حمِّل مكتبة JavaScript الخاصة بخدمة Google Identity Services في أقرب وقت ممكن. ننصحك بتحميل مكتبة JavaScript قبل بعض المكتبات الكبيرة الأخرى، خاصةً على الويب للأجهزة الجوّالة.
  • إذا لم يتم عرض زر "تسجيل الدخول باستخدام حساب Google" إلا بعد اختيار المستخدم تسجيل الدخول من القائمة. يمكنك عرض زر "تسجيل الدخول باستخدام حساب Google" في عنصر مخفي أولاً، ثمّ إظهاره بعد أن يختار المستخدم تسجيل الدخول من القائمة.

نقاط يجب مراعاتها عند استخدام ميزة "نقرة واحدة"

تسجيل الدخول التلقائي

تتيح ميزة "تسجيل الدخول تلقائيًا" للمستخدمين تسجيل الدخول إلى موقعك الإلكتروني بدون النقر على طلب "النقرة الواحدة" إذا سبق لهم منح إذنًا ل موقعك الإلكتروني.

يوفّر تسجيل الدخول التلقائي القابل للإلغاء المزايا التالية:

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

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

حالات عرض واجهة مستخدم ميزة "نقرة واحدة"

باستخدام HTML API، يتم عرض ميزة "النقرة الواحدة" دائمًا عند تحميل الصفحة. باستخدام واجهة برمجة التطبيقات JavaScript API، يمكنك التحكّم في وقت عرض واجهة مستخدم "النقرة الواحدة". يُرجى العِلم أنّ واجهة مستخدم One Tap قد لا تظهر دائمًا بعد استدعاء واجهة برمجة التطبيقات، وذلك للأسباب التالية:

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

مقترَح

  • أظهِر مربّع حوار تسجيل الدخول الذي يتضمّن زرّ تسجيل الدخول باستخدام كلمة المرور و"تسجيل الدخول باستخدام حساب Google" ، واطلِب One Tap API في الوقت نفسه. ويضمن ذلك أن يتم دائمًا تقديم طريقة ما لتسجيل الدخول إلى موقعك الإلكتروني للمستخدمين.

غير مقترَح

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

ميزة "نقرة واحدة" على متصفّحات ITP

بسبب ميزة الحماية الذكية من التتبّع (ITP)، لا تعمل تجربتنا المعتادة للدفع بنقرة واحدة على متصفّحات ITP، مثل Chrome على أجهزة iOS وSafari وFirefox. يتم توفير تجربة مستخدم مختلفة تبدأ بصفحة ترحيب على هذين المتصفّحين بدلاً من ذلك.

يمكن إيقاف تجربة المستخدم في ميزة "النقرة الواحدة" على متصفّحات ITP إذا أردت ذلك. يُرجى الرجوع إلى إتاحة ميزة "النقرة الواحدة" على متصفّحات ITP لمعرفة المزيد من التفاصيل.

لا تتوفّر طريقة لتفعيل تجربة المستخدم هذه على متصفّحات غير مزوّدة بتكنولوجيا ITP، مثل Chrome على Android/macOS/Linux وEdge.

إلغاء الطلب إذا نقر المستخدم على رابط آخر

يتم إغلاق طلب One Tap تلقائيًا إذا نقر المستخدم خارج الطلب. ويمكن تغيير هذا السلوك إذا أردت.

ننصحك بإبقاء طلب One Tap مفتوحًا على الويب على الكمبيوتر المكتبي، لأنّ حجم الشاشة كبير بما يكفي.

تغيير موضع تجربة المستخدم في ميزة "النقرة الواحدة"

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

تغيير سياق تسجيل الدخول

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

السياق
signin "تسجيل الدخول باستخدام حساب Google"
signup "الاشتراك باستخدام حساب Google"
use "الاستخدام مع Google"

حالة واجهة مستخدم ميزة "الاستماع بنقرة واحدة"

لدمج ميزة "النقرة الواحدة" بسلاسة في تجربة المستخدم الأكبر، يمكن أن تُعلمك عند تغيُّر حالة واجهة المستخدم. ومع ذلك، لا تتوفّر هذه الميزة في الإصدارات المستقبلية لإدارة بيانات الاعتماد المُدمَجة.

ميزة "نقرة واحدة" على النطاقات الفرعية

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

ميزة "نقرة واحدة" في صفحات HTML الثابتة

تفترض مكتبة "النظام العالمي للمعلومات الجغرافية" تلقائيًا أنّ صفحات الويب يتم إنشاؤها ديناميكيًا. يتحقّق خادم HTTP من حالة تسجيل دخول المستخدم عند إنشاء رمز HTML.

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

في هذه الحالة، تقع على عاتق خادم الويب مسؤولية إضافة رمز واجهة برمجة التطبيقات One Tap HTML أو إزالته.

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

  • في حال عدم توفّر ملف تعريف ارتباط الجلسة، يتم تفعيل مسار One Tap.
  • إذا كان ملف تعريف ارتباط الجلسة متوفّرًا، يتم تخطّي عملية تسجيل الدخول بنقرة واحدة.

في هذه الحالة، يتم التحكّم في ما إذا كان سيتم تفعيل مسار One Tap من خلال حالة ملف تعريف الارتباط لجلستك، بدلاً من توفّر رمز One Tap HTML API في صفحة الويب.

الدمج من جهة الخادم

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

اعتبارات تجربة المُستخدِم

عادةً ما تحتاج إلى إضافة نقطة نهاية HTTP في مصدرك الخاص لمعالجة الرسائل المرسَلة من جانب الخادم. قد تؤثر العوامل التالية في تجربة المستخدم الناتجة.

في ما يلي وصف لتجربة المستخدم الفعلية التي تحصل عليها.

  1. بالنسبة إلى وضع تجربة المستخدم لإعادة التوجيه في زر "تسجيل الدخول باستخدام حساب Google":

    • سواءً كنت تستخدم واجهة برمجة التطبيقات HTML API أو واجهة برمجة التطبيقات JavaScript API، عليك ضبط معرّف الموارد المنتظم لتسجيل الدخول. من المستحيل استخدام دالة ردّ اتصال JavaScript لمعالجة الردّ، لأنّه سبق أن تمت إعادة توجيه المستخدمين بعيدًا عن صفحة الويب.
    • ملخّص تجربة المستخدم: بعد النقر على زر "تسجيل الدخول باستخدام حساب Google"، تظهر للمستخدمين تتمة إعادة توجيه على مستوى الصفحة إلى واجهة مستخدم Google لاختيار الجلسة والموافقة عليها. بعد الانتهاء، يتم إرسال POST بملء الصفحة إلى عنوان URL لتسجيل الدخول الذي تحديدته.
  2. بالنسبة إلى وضع تجربة المستخدم في النافذة المنبثقة لميزة "النقرة الواحدة" أو زر "تسجيل الدخول باستخدام حساب Google"، في حال استخدام IDE JavaScript API أو استخدام HTML API وتقديم دالّة callback JavaScript:

    • يتمّ تمرير ردود المصادقة إلى دالة ردّ الاتصال في JavaScript.
    • ملخّص تجربة المستخدم: تظهر رسالة طلب One Tap أو نافذة منبثقة فوق صفحة الويب. بعد أن ينتهي المستخدمون من تجربة المستخدم في الطلب أو النافذة المنبثقة لتحديد الجلسة والموافقة عليها، تتلقّى دالة ردّ الاتصال في JavaScript الردود. يتم تحديد تجربة المستخدم اللاحقة حسب الطريقة التي ترسِل بها دالّة callback الردود إلى خادمك.
  3. بخلاف ذلك (واجهة برمجة التطبيقات HTML مع حالة معرّف الموارد المتّصل (URI) لتسجيل الدخول):

    • يتم إرسال ردود المصادقة إلى معرّف الموارد المنتظم لتسجيل الدخول.
    • ملخّص تجربة المستخدم: تظهر رسالة طلب One Tap أو نافذة منبثقة فوق صفحة الويب. بعد أن ينتهي المستخدمون من تجربة المستخدم في الطلب أو النافذة المنبثقة لتحديد الجلسات والموافقة عليها، يتم إرسال ردود المصادقة باستخدام إرسال POST على مستوى الصفحة بالكامل إلى عنوان URL لتسجيل الدخول الذي حدّدته.

ننصحك باستخدام طريقة متّسقة لإرسال ردود ميزة "النقرة الواحدة" و ردود زر "تسجيل الدخول باستخدام حساب Google".

الاعتبارات الأمنية

لمنع هجمات تزوير الطلبات من مواقع إلكترونية مختلفة،

  • بالنسبة إلى عمليات إرسال المشاركات التي تسبّبت فيها مكتبة JavaScript الخاصة بعميل Google Identity Service، يمكنك استخدام نمط ملفات تعريف الارتباط المضمّنة في عملية الإرسال المزدوجة. يُرجى الرجوع إلى مقالة التحقّق من صحة رمز Google المميّز من جهة الخادم لمعرفة المزيد من التفاصيل.
  • لإرسال البيانات إلى مصدرك باستخدام XmlHttpRequest، يمكنك استخدام عنوان HTTP المخصّص أو إجراءات أمان أخرى وافق عليها فريق الأمان.

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

الأسئلة الشائعة

  • هل زرّا "نقرة واحدة" و"تسجيل الدخول باستخدام حساب Google" متوفّران في عروض الويب؟

    لا، بسبب المخاوف الأمنية، يجب ألا يضيف المستخدمون جلسات Google إلى webviews. وبالتالي، يتم إيقاف خدمات GIS في عروض الويب، لأنّه من المفترض ألا تكون هناك جلسات Google.

  • هل يمكنني استخدام زر "تسجيل الدخول باستخدام حساب Google" الخاص بي؟ لا، باستخدام عملية تسجيل الدخول باستخدام بروتوكول OAuth من جهة الخادم أو الإصدار الأقدم من مكتبة JavaScript لميزة "تسجيل الدخول باستخدام حساب Google"، تمكّنت الجهات المعنيّة من استخدام إرشادات وضع العلامة التجارية لميزة "تسجيل الدخول" لإنشاء إصدارات خاصة بها من أزرار ميزة "تسجيل الدخول باستخدام حساب Google".

    ومع ذلك، أزالت ميزة "تسجيل الدخول باستخدام حساب Google" هذه الميزة. يجب أن يتم إنشاء جميع أزرار "تسجيل الدخول باستخدام حساب Google" من مكتبة JavaScript في Google Identity Services. هناك سببان لهذا التغيير.

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

    لفرض هذه القاعدة، لا تعرض مكتبة JavaScript سوى واجهة برمجة تطبيقات لعرض زر، ولكن ليس واجهة برمجة التطبيقات لبدء عملية تسجيل الدخول.

  • ماذا لو كان موقعي الإلكتروني يتيح ميزة "نقرة واحدة" فقط وليس الزر "تسجيل الدخول باستخدام حساب Google"؟

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

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

  • متى يتم تحليل رمز HTML API؟ هل يمكنني تغيير رمز HTML API لاحقًا؟

    تُحلِّل مكتبة JavaScript في Google Identity Services رمز HTML API وتنفِّذه إما عند حدث تحميل مكتبة JavaScript أو عند حدث DomContentLoaded، أيهما لاحق.

    • في حال بدء حدث DomContentLoaded عند تحميل مكتبة JavaScript ، يتم تحليل رمز HTML API وتنفيذه على الفور.
    • بخلاف ذلك، تضيف مكتبة JavaScript أداة معالجة للحدث DomContentLoaded. عند بدء الاستماع، يُحلّل المستمع رمز HTML API وينفّذه.

    يُرجى العلم أيضًا أنّ تحليل رمز HTML API وتنفيذه هو عملية واحدة.

    • بعد التحليل والتنفيذ، يتم تجاهل أي تغييرات لاحقة على رمز HTML API.
    • لا تتوفّر واجهة برمجة تطبيقات للمطوّرين لبدء عملية التحليل أو التنفيذ.