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

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

تسجيل الدخول باستخدام حساب 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 APIs وخدماته. راجع المصادقة للويب للحصول على مزيدٍ من المعلومات.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مع JavaScript API، تتوفّر لك مرونة أكبر في بعض الحالات على النحو التالي.

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

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

ملاحظة: ننصحك باستخدام HTML API، إن أمكن.

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

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

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

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

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

تخصيص الزر

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

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

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

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

يمكنك وضع أزرار متعددة في صفحة ويب واحدة. يمكن لمنشئ التعليمات البرمجية إنشاء زر واحد فقط في كل مرة. يمكنك تشغيلها عدة مرات ونسخ رمز <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" في أقرب وقت ممكن. ننصحك بتحميل مكتبة JavaScript قبل بعض المكتبات الكبيرة الأخرى، خاصةً على الويب على الأجهزة الجوّالة.

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

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

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

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

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

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

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

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

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

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

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

سمة مقترَحة

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

صيغة غير محبَّذة

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

نقرة واحدة على متصفحات 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 الثابتة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2. بالنسبة إلى وضع تجربة المستخدم "نقرة واحدة" أو على زر "تسجيل الدخول باستخدام حساب Google" المنبثق، في حال استخدام واجهة برمجة تطبيقات JavaScript أو استخدام HTML API وتوفير وظيفة استدعاء 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. وبالتالي، يتم إيقاف أنظمة المعلومات الجغرافية (GIS) في مكتبات 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" على تحليل رمز HTML API وتنفيذه إما عند حدث تحميل مكتبة JavaScript أو حدث DomContentLoaded، أيهما لاحقًا.

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

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

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