اعتبارات الدمج

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

تسجيل الدخول باستخدام حساب Google في المجرّد

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

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

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

   نقطة رئيسية: لأسباب أمنية، لا يُسمح بإضافة جلسات Google جديدة في إطار iframe.

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

   نقطة رئيسية: يمكنك استخدام منشئ الرموز لإنشاء الرمز بسهولة لتضمين زر "نقرة واحدة" و"تسجيل الدخول تلقائيًا" و"تسجيل الدخول باستخدام حساب Google" في صفحات الويب الخاصة بك.

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

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

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

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

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

   

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

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

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

   نقطة رئيسية: للمصادقة بدون إعادة تحميل صفحة الويب، من الممارسات الشائعة تلقّي بيانات اعتماد JWT عبر معالج استدعاء JavaScript، ثم إرسالها إلى الخادم عبر طلب XmlHttpRequest.

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

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

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

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

الوصول إلى Google APIs وخدماتها

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

فصل تجربة المستخدم للمصادقة والترخيص

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

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

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

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

1. يمكنك إعادة ضبط تجربة المستخدم للفصل بين لحظات المصادقة والترخيص.

2. نقل البيانات إلى مكتبة JavaScript في "خدمات Google Identity"

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

واجهة برمجة تطبيقات HTML مقابل واجهة برمجة تطبيقات JavaScript

يمكنك استخدام واجهة برمجة تطبيقات HTML أو واجهة برمجة تطبيقات JavaScript لدمج ميزة "نقرة واحدة" أو "تسجيل الدخول التلقائي" أو "تسجيل الدخول باستخدام حساب Google" في صفحاتك على الويب.

باستخدام واجهة برمجة تطبيقات HTML، يمكنك الحصول على المزيد من الميزات المضمنة. على سبيل المثال:

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

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

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

  نقطة رئيسية: للمصادقة بدون إعادة تحميل صفحة الويب، من الممارسات الشائعة تلقّي بيانات اعتماد JWT من خلال معالج استدعاء JavaScript، ثم إرسالها إلى الخادم عبر طلب XmlHttpRequest.

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

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

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

ملاحظة: ننصحك باستخدام واجهة برمجة تطبيقات HTML، إن أمكن.

لا تستخدم واجهة برمجة التطبيقات HTML مع واجهة برمجة تطبيقات JavaScript في صفحة الويب نفسها لإعداد الصفحة أو لعرض "نقرة واحدة" و"زر". تحقق من التعليمات البرمجية، لكل من HTML وJavaScript، بحثًا عن الأماكن التي قد تتداخل فيها. لاحظ ما يلي:

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

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

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

• revoke
• cancel
• disableAutoSelect
• storeCredential

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

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

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

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

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

نقطة رئيسية: عند النقر على زر "تسجيل الدخول باستخدام حساب Google"، ستظهر لك نافذة منبثقة تعرض تجربة المستخدم.

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

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

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

نقطة رئيسية: لاحظ الاختلافات بين مسار إعادة التوجيه باستخدام زر "تسجيل الدخول باستخدام حساب Google" ومسار إعادة التوجيه عبر OAuth.

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

استخدام الزر الخاص بك غير متاح. لا توجد واجهة برمجة تطبيقات لبدء تدفق الأزرار آليًا.

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

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

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

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

تحذير: يمكنك إضافة عنصر <div id='g_id_onload' ... ><id> واحد فقط في صفحة الويب نفسها. لا تنسخ عناصر g_id_onload متعددة إلى صفحة الويب.

أفضل ممارسات عرض الأزرار

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

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

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

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

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

  نقطة رئيسية: عليك تحميل مكتبة JavaScript لخدمات Google Identity في أقرب وقت ممكن لتقليل وقت استجابة عرض زر "تسجيل الدخول باستخدام حساب Google".

نقاط يجب أخذها في الاعتبار من خلال ميزة "نقرة واحدة"

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

تسجيل الدخول التلقائي القابل للإلغاء يقدم المزايا التالية.

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

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

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

باستخدام HTML API، تظهر ميزة "نقرة واحدة" دائمًا عند تحميل الصفحة. باستخدام JavaScript

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

• ما مِن جلسة Google نشطة في المتصفّح.
• تكون جميع جلسات Google النشطة غير مفعّلة.
• جارٍ إيقاف العملية.

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

سمة مقترَحة

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

غير مقترَح

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

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

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

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

ملاحظة: ميزة "تجربة المستخدم بنقرة واحدة" على متصفّحات ITP لا تتيح تسجيل الدخول تلقائيًا.

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

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

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

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

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

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

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

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

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

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

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

نقطة رئيسية: راجِع القسم تغيير سياق تسجيل الدخول بنقرة واحدة حول كيفية تغيير السياق.

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

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

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

نقرة واحدة في النطاقات الفرعية

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

نقطة رئيسية: يمكنك الرجوع إلى مقالة عرض نقرة واحدة عبر النطاقات الفرعية لمزيد من التفاصيل.

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

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

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

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

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

• في حال عدم وجود ملف تعريف ارتباط الجلسة، يتم تشغيل تدفق "نقرة واحدة".
• في حال توفُّر ملف تعريف ارتباط الجلسة، يتم تخطي تدفق "نقرة واحدة".

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

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

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

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

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

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

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

• ما إذا تم تفعيل "نقرة واحدة" أو "تسجيل الدخول باستخدام حساب Google"
• ما إذا كان سيتم استخدام واجهة برمجة تطبيقات HTML أو واجهة برمجة تطبيقات JavaScript.
• يمكنك اختيار ما إذا تم استخدام معرّف الموارد المنتظم (URI) لتسجيل الدخول أو وظيفة معاودة الاتصال في JavaScript للتعامل مع الاستجابة.

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

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

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

2. عند استخدام "نقرة واحدة" أو وضع "تجربة المستخدم" في النافذة المنبثقة لزر "تسجيل الدخول باستخدام حساب Google"، في حال استخدام واجهة برمجة تطبيقات JavaScript أو استخدام واجهة برمجة تطبيقات HTML وتوفير وظيفة استدعاء JavaScript:

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

3. بخلاف ذلك (واجهة برمجة تطبيقات HTML مع حالة عنوان URI لتسجيل الدخول):

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

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

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

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

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

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

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

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

  لا. بسبب مخاوف متعلقة بالأمان، على المستخدمين عدم إضافة جلسات Google إلى مكتبات WebView. وبالتالي، يتم إيقاف نظم المعلومات الجغرافية في مكتبات WebView، لأنه لا يُفترض أن تكون هناك جلسات Google.

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

  يُرجى العِلم أنّ ميزة "تسجيل الدخول باستخدام حساب Google" قد أزالت هذه الميزة. يجب إنشاء جميع أزرار "تسجيل الدخول باستخدام Google" من خلال مكتبة JavaScript في "خدمات هوية Google". هناك سببان لهذا التغيير.

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

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

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

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

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

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

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

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

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

  • بعد التحليل والتنفيذ، يتم تجاهل أي تغييرات لاحقة على رمز HTML API.
  • لا توجد واجهة برمجة تطبيقات للمطورين لتشغيل عملية التحليل أو التنفيذ.
  ملاحظة: يمكنك استخدام واجهة برمجة تطبيقات JavaScript إذا كانت السلوكيات المذكورة أعلاه لا تلبي متطلباتك.