تسجيل الدخول باستخدام مرجع واجهة برمجة تطبيقات HTML في Google

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

العنصر الذي يحمل المعرّف "g_id_onload"

يمكنك وضع سمات بيانات ميزة "تسجيل الدخول باستخدام حساب Google" في أي عناصر مرئية أو غير مرئية، مثل <div> و<span>. الشرط الوحيد هو ضبط قيمة g_id_onload لسمة Element ID. لا تضِف هذا المعرّف إلى عناصر متعددة.

سمات البيانات

يسرد الجدول التالي سمات البيانات وأوصافها:

السمة
data-client_id معرّف العميل لتطبيقك
data-auto_prompt عرض Google One انقر على.
data-auto_select تفعيل الاختيار التلقائي في ميزة "النقرة الواحدة" من Google
data-login_uri عنوان URL لنقطة نهاية تسجيل الدخول
data-callback اسم دالة معالِج الرمز المميّز لتعريف الهوية في JavaScript
data-native_login_uri عنوان URL لنقطة نهاية معالِج بيانات اعتماد كلمة المرور
data-native_callback اسم دالة معالجة بيانات اعتماد كلمة المرور في JavaScript
data-native_id_param اسم المَعلمة لقيمة credential.id
data-native_password_param اسم المَعلمة لقيمة credential.password
data-cancel_on_tap_outside يتحكّم هذا الإعداد في ما إذا كان سيتم إلغاء الطلب إذا نقر المستخدم خارج الطلب.
data-prompt_parent_id معرّف DOM لعنصر حاوية طلب One Tap
data-skip_prompt_cookie يتخطّى هذا الخيار ميزة "النقرة الواحدة" إذا كان ملف تعريف الارتباط المحدّد يحتوي على قيمة غير فارغة.
data-nonce سلسلة عشوائية لبيانات تعريف المستخدمين
data-context العنوان والكلمات في طلب ميزة "نقرة واحدة"
data-moment_callback اسم الدالة الخاصة بمعالج إشعارات حالة واجهة المستخدم للمطالبة
data-state_cookie_domain إذا كنت بحاجة إلى طلب One Tap في النطاق الرئيسي والنطاقات الفرعية، عليك تمرير النطاق الرئيسي إلى هذه السمة لاستخدام ملف تعريف ارتباط مشترَك واحد.
data-ux_mode مسار تجربة المستخدم لزر "تسجيل الدخول باستخدام حساب Google"
data-allowed_parent_origin المصادر المسموح لها بتضمين إطار iframe الوسيط يتم تشغيل ميزة "النقرة الواحدة" في وضع iframe الوسيط إذا كانت هذه السمة متوفّرة.
data-intermediate_iframe_close_callback تلغي السلوك التلقائي لإطار iframe الوسيط عندما يغلق المستخدمون ميزة "النقرة الواحدة" يدويًا.
data-itp_support تفعيل تجربة One Tap المحسّنة على متصفّحات ITP
data-login_hint يمكنك تخطّي اختيار الحساب من خلال تقديم تلميح للمستخدم.
data-hd يمكنك حصر اختيار الحسابات حسب النطاق.
data-use_fedcm_for_prompt اسمح للمتصفّح بالتحكّم في طلبات تسجيل دخول المستخدمين والتوسّط في عملية تسجيل الدخول بين موقعك الإلكتروني وGoogle.
data-enable_redirect_uri_validation فعِّل مسار إعادة التوجيه للزر الذي يتوافق مع قواعد التحقّق من معرّف الموارد المنتظم (URI) لإعادة التوجيه.

أنواع السمات

تحتوي الأقسام التالية على تفاصيل عن نوع كل سمة و مثال عليها.

data-client_id

هذه السمة هي معرّف عميل تطبيقك، والذي يمكن العثور عليه وإنشاؤه في وحدة تحكّم Google Cloud. اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع مطلوب مثال
سلسلة نعم data-client_id="CLIENT_ID.apps.googleusercontent.com"

data-auto_prompt

تحدّد هذه السمة ما إذا كان سيتم عرض ميزة "نقرة واحدة" أم لا. القيمة التلقائية هي true. لا يظهر رمز النقرة في Google One عندما تكون هذه القيمة هي false. اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع مطلوب مثال
قيمة منطقية اختياري data-auto_prompt="true"

data-auto_select

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

النوع مطلوب مثال
قيمة منطقية اختياري data-auto_select="true"

data-login_uri

هذه السمة هي معرّف الموارد المنتظم لنقطة نهاية تسجيل الدخول.

يجب أن تتطابق القيمة تمامًا مع أحد معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه لعميل OAuth 2.0 الذي ضبطته في "وحدة تحكّم واجهة برمجة التطبيقات"، ويجب أن تكون متوافقة مع قواعد التحقّق من معرّف الموارد المنتظم (URI) لإعادة التوجيه.

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

يتم نشر استجابة بيانات اعتماد رمز التعريف في نقطة نهاية تسجيل الدخول عندما لا يتم تحديد دالة callback وينقر المستخدم على زر "تسجيل الدخول باستخدام حساب Google" أو زر One Tap، أو يتم تسجيل الدخول تلقائيًا.

اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع اختياري مثال
عنوان URL الإعداد التلقائي هو معرّف الموارد المنتظم للصفحة الحالية أو القيمة التي تحدّدها.
يتم تجاهلها عند ضبط data-ux_mode="popup" و data-callback.		 data-login_uri="https://www.example.com/login"

يجب أن تعالج نقطة نهاية تسجيل الدخول طلبات POST التي تحتوي على مفتاح credential مع قيمة رمز مميّز تحدّد الهوية في النص.

في ما يلي مثال على طلب إلى نقطة نهاية تسجيل الدخول:

POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

credential=ID_TOKEN

data-callback

هذه السمة هي اسم دالة JavaScript التي تعالج رمز هُوية العميل المعروض. اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع مطلوب مثال
سلسلة مطلوبة في حال عدم ضبط data-login_uri. data-callback="handleToken"

قد يتم استخدام إحدى سمتَي data-login_uri وdata-callback. ويعتمد ذلك على إعدادات المكوّن ووضع تجربة المستخدم التالية:

  • تكون سمة data-login_uri مطلوبة لتجربة المستخدم في زر redirect "تسجيل الدخول باستخدام حساب Google"، والذي يتجاهل سمة data-callback.

  • يجب ضبط إحدى هاتين السمتَين لوضع تجربة مستخدم Google OneTap وpopup زر تسجيل الدخول باستخدام حساب Google. في حال ضبط كلتا السمتَين، تكون لسمة data-callback الأولوية الأعلى.

لا تتوافق دوال JavaScript ضمن مساحة اسم مع HTML API. وبدلاً من ذلك، استخدِم دالة JavaScript عامة بدون مساحة اسم. على سبيل المثال، استخدِم mylibCallback بدلاً من mylib.callback.

data-native_login_uri

هذه السمة هي عنوان URL لنقطة نهاية معالِج بيانات اعتماد كلمة المرور. في حال تحديد سمة data-native_login_uri أو سمة data-native_callback ، ستستخدم مكتبة JavaScript مدير بيانات الاعتماد الأصلي في حال عدم توفّر جلسة Google. لا يُسمح لك بضبط كل من السمتَين data-native_callback وdata-native_login_uri. اطّلِع على الجدول التالي لمزيد من المعلومات:

النوع مطلوب مثال
سلسلة اختياري data-login_uri="https://www.example.com/password_login"

data-native_callback

هذه السمة هي اسم دالة JavaScript التي تعالج بيانات اعتماد المسترجعة من مدير بيانات الاعتماد الأصلي في المتصفّح. في حال ضبط سواء سمة data-native_login_uri أو سمة data-native_callback ، تعود مكتبة JavaScript إلى استخدام مدير بيانات الاعتماد الأصلي في حال عدم توفّر جلسة Google. لا يُسمح لك بضبط كل من data-native_callback وdata-native_login_uri. اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع مطلوب مثال
سلسلة اختياري data-native_callback="handlePasswordCredential"

لا تتوافق دوال JavaScript ضمن مساحة اسم مع HTML API. وبدلاً من ذلك، استخدِم دالة JavaScript عامة بدون مساحة اسم. على سبيل المثال، استخدِم mylibCallback بدلاً من mylib.callback.

data-native_id_param

عند إرسال بيانات اعتماد كلمة المرور إلى نقطة نهاية معالِج بيانات اعتماد كلمة المرور، يمكنك تحديد اسم المَعلمة لحقل credential.id. اسم العلامة التلقائي هو email. اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع مطلوب مثال
عنوان URL اختياري data-native_id_param="user_id"

data-native_password_param

عند إرسال بيانات اعتماد كلمة المرور إلى نقطة نهاية معالِج بيانات اعتماد كلمة المرور، يمكنك تحديد اسم المَعلمة لقيمة credential.password. الاسم التلقائي هو password. اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع مطلوب مثال
عنوان URL اختياري data-native_password_param="pwd"

data-cancel_on_tap_outside

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

النوع مطلوب مثال
قيمة منطقية اختياري data-cancel_on_tap_outside="false"

data-prompt_parent_id

تضبط هذه السمة رقم تعريف نموذج عناصر المستند (DOM) لعنصر الحاوية. إذا لم يتم ضبطه، يتم عرض الرسالة One Tap في أعلى يسار النافذة. اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع مطلوب مثال
سلسلة اختياري data-prompt_parent_id="parent_id"

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

النوع مطلوب مثال
سلسلة اختياري data-skip_prompt_cookie="SID"

data-nonce

هذه السمة هي سلسلة عشوائية يستخدمها رمز التعريف لمنع هجمات إعادة التشغيل. اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع مطلوب مثال
سلسلة اختياري data-nonce="biaqbm70g23"

تقتصر طول الرمز المميّز على الحد الأقصى لحجم JWT المتوافق مع بيئتك، وقيود حجم HTTP للمتصفّح والخادم الفرديين.

data-context

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

النوع مطلوب مثال
سلسلة اختياري data-context="use"

يسرد الجدول التالي جميع السياقات المتاحة وأوصافها:

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

data-moment_callback

هذه السمة هي اسم الدالة الخاصة بمُستمع إشعار حالة واجهة مستخدم الطلب. لمزيد من المعلومات، يُرجى الرجوع إلى نوع البيانات PromptMomentNotification.

اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع مطلوب مثال
سلسلة اختياري data-moment_callback="logMomentNotification"

لا تتوافق دوال JavaScript ضمن مساحة اسم مع HTML API. وبدلاً من ذلك، استخدِم دالة JavaScript عامة بدون مساحة اسم. على سبيل المثال، استخدِم mylibCallback بدلاً من mylib.callback.

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

النوع مطلوب مثال
سلسلة اختياري data-state_cookie_domain="example.com"

data-ux_mode

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

النوع مطلوب مثال
سلسلة اختياري data-ux_mode="redirect"

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

وضع تجربة المستخدم
popup تنفيذ تجربة مستخدم تسجيل الدخول في نافذة منبثقة
redirect تنفيذ مسار تجربة المستخدم لتسجيل الدخول من خلال إعادة توجيه الصفحة بالكامل

data-allowed_parent_origin

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

النوع مطلوب مثال
سلسلة أو صفيف سلاسل اختياري data-allowed_parent_origin="https://example.com"

يسرد الجدول التالي أنواع القيم المسموح بها وأوصافها.

أنواع القيم
string معرّف موارد منتظم لنطاق واحد "https://example.com"
string array قائمة بمعرفات الموارد المنتظمة (URI) للنطاقات مفصولة بفواصل "https://news.example.com,https://local.example.com"

إذا كانت قيمة سمة data-allowed_parent_origin غير صالحة، سيتعذّر بدء وضع iframe الوسيط في ميزة "النقرة الواحدة" وسيتوقف.

يمكن أيضًا استخدام بادئات أحرف البدل. على سبيل المثال، يتطابق "https://*.example.com" مع example.com ونطاقاته الفرعية على جميع المستويات (مثل news.example.com، login.news.example.com). يجب مراعاة ما يلي عند استخدام أحرف البدل:

  • لا يمكن أن تتألّف سلاسل الأنماط من حرف بدل ونطاق من المستوى الأعلى فقط. على سبيل المثال، https://*.com و https://*.co.uk غير صالحَين. كما هو موضّح أعلاه، "https://*.example.com" يتطابق مع example.com و نطاقاته الفرعية. يمكنك أيضًا استخدام قائمة مفصولة بفواصل لتمثيل نطاقين مختلفين. على سبيل المثال، يتطابق "https://example1.com,https://*.example2.com" مع النطاقَين example1.com وexample2.com والنطاقات الفرعية من example2.com.
  • يجب أن تبدأ نطاقات البدل بتنسيق https:// آمن، لذا "*.example.com" تُعدّ غير صالحة.

data-intermediate_iframe_close_callback

تلغي هذه السمة السلوك التلقائي لإطار iframe المؤقت عندما يغلق المستخدمون ميزة One Tap يدويًا من خلال النقر على الزر "X" في واجهة مستخدم One Tap. السلوك التلقائي هو إزالة عنصر iframe الوسيط من نموذج DOM على الفور.

لا يسري حقل data-intermediate_iframe_close_callback إلا في وضع iframe الوسيط. ولا يؤثّر ذلك إلا في إطار iframe الوسيط، بدلاً من إطار iframe الخاص بميزة "النقرة الواحدة". تتم إزالة واجهة مستخدم One Tap قبل بدء معالجة طلب إعادة الاتصال.

النوع مطلوب مثال
دالة اختياري data-intermediate_iframe_close_callback="logBeforeClose"

لا تتوافق دوال JavaScript ضمن مساحة اسم مع HTML API. وبدلاً من ذلك، استخدِم دالة JavaScript عامة بدون مساحة اسم. على سبيل المثال، استخدِم mylibCallback بدلاً من mylib.callback.

data-itp_support

يحدِّد هذا الحقل ما إذا كان يجب تفعيل تجربة المستخدِم المحسّنة لميزة "النقرة الواحدة" في المتصفّحات التي تتيح ميزة "الحماية الذكية من التتبّع" (ITP). تكون القيمة التلقائية false. اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع مطلوب مثال
قيمة منطقية اختياري data-itp_support="true"

data-login_hint

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

لمزيد من المعلومات، يُرجى الاطّلاع على مستندات OpenID Connect الخاصة بـ login_hint.

النوع مطلوب مثال
سلسلة. يمكن أن يكون عنوان بريد إلكتروني أو قيمة حقل sub من رمز التعريف. اختياري data-login_hint="elisa.beckett@gmail.com"

data-hd

عندما يكون لدى المستخدم حسابات متعدّدة ويجب تسجيل الدخول باستخدام حسابه على Workspace فقط، يمكنه استخدام هذا الخيار لتقديم تلميح باسم النطاق إلى Google. عند نجاح العملية، تقتصر حسابات المستخدمين المعروضة أثناء اختيار الحساب على النطاق المقدَّم. قيمة العنصر النائب: * يوفّر حسابات Workspace فقط للمستخدم ويستبعد حسابات المستهلكين (user@gmail.com) أثناء اختيار الحساب.

لمزيد من المعلومات، يُرجى الاطّلاع على مستندات OpenID Connect الخاصة بـ hd.

النوع مطلوب مثال
سلسلة. اسم نطاق مؤهّل بالكامل أو *. اختياري data-hd="*"

data-use_fedcm_for_prompt

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

النوع مطلوب مثال
قيمة منطقية اختياري data-use_fedcm_for_prompt="true"

data-enable_redirect_uri_validation

فعِّل مسار إعادة التوجيه للزر الذي يتوافق مع قواعد التحقّق من معرّف الموارد المنتظم (URI) لإعادة التوجيه.

النوع مطلوب مثال
قيمة منطقية اختياري data-enable_redirect_uri_validation="true"

عنصر من فئة g_id_signin

في حال إضافة g_id_signin إلى سمة class للعنصر، يتم عرض العنصر كزر "تسجيل الدخول باستخدام حساب Google".

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

سمات البيانات المرئية

يسرد الجدول التالي سمات البيانات المرئية وأوصافها:

السمة
data-type نوع الزر: رمز أو زر عادي
data-theme مظهر الزر. على سبيل المثال، filled_blue أو filled_black.
data-size حجم الزر على سبيل المثال، صغير أو كبير.
data-text نص الزر. على سبيل المثال، "تسجيل الدخول باستخدام حساب Google" أو "الاشتراك باستخدام حساب Google".
data-shape شكل الزر على سبيل المثال، مستطيل أو دائري
data-logo_alignment محاذاة شعار Google: يمين أو وسط
data-width عرض الزر، بالبكسل
data-locale يتم عرض نص الزر باللغة المحدّدة في هذه السمة.
data-click_listener في حال ضبطها، يتم استدعاء هذه الدالة عند النقر على الزر "تسجيل الدخول باستخدام حساب Google" .
data-state في حال ضبطها، يتم عرض هذه السلسلة مع الرمز المميّز للتعريف.

أنواع السمات

تحتوي الأقسام التالية على تفاصيل عن نوع كل سمة و مثال عليها.

data-type

نوع الزر تكون القيمة التلقائية standard. اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع مطلوب مثال
سلسلة نعم data-type="icon"

يسرد الجدول التالي جميع أنواع الأزرار المتاحة و أوصافها:

النوع
standard
زر يحتوي على نص أو معلومات مخصّصة
icon
زر رمز بدون نص

data-theme

مظهر الزر. تكون القيمة التلقائية outline. اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع مطلوب مثال
سلسلة اختياري data-theme="filled_blue"

يسرد الجدول التالي المظاهر المتاحة وأوصافها:

المظهر
outline
زر عادي بخلفية بيضاء زر رمزي على خلفية بيضاء زر مخصّص بخلفية بيضاء
مظهر الزر العادي.
filled_blue
زر عادي على خلفية زرقاء زر رمزي على خلفية زرقاء زر مخصّص على خلفية زرقاء
مظهر الأزرار ذات اللون الأزرق
filled_black
زر عادي بخلفية سوداء زر رمزي على خلفية سوداء زر مخصّص بخلفية سوداء
مظهر الزرّ المملوء بالأسود.

data-size

حجم الزر. تكون القيمة التلقائية large. اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع مطلوب مثال
سلسلة اختياري data-size="small"

يسرد الجدول التالي أحجام الأزرار المتاحة وأوصافها.

الحجم
large
زر عادي كبير زر رمز كبير زرّ كبير مخصّص
زر كبير.
medium
زر عادي متوسط الحجم زر رمز متوسط
زر متوسط الحجم
small
زر صغير زر رمز صغير
زر صغير.

data-text

نص الزر تكون القيمة التلقائية signin_with. لا توجد اختلافات مرئية في نص أزرار الرموز التي لها سمات data-text مختلفة. الاستثناء الوحيد هو عندما يتم قراءة النص لتوفير إمكانية وصول سهل إلى الشاشة.

اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع مطلوب مثال
سلسلة اختياري data-text="signup_with"

يسرد الجدول التالي نصوص الأزرار المتاحة وأوصافها:

نص
signin_with
زر عادي يحمل العنوان &quot;تسجيل الدخول باستخدام حساب Google&quot; زر رمز بدون نص مرئي
نص الزر هو "تسجيل الدخول باستخدام حساب Google".
signup_with
زر عادي يحمل العنوان &quot;اشتراك باستخدام حساب Google&quot; زر رمز بدون نص مرئي
نص الزر هو "الاشتراك باستخدام حساب Google".
continue_with
زر عادي بعنوان &quot;متابعة باستخدام حساب Google&quot; زر رمز بدون نص مرئي
نص الزر هو "متابعة باستخدام حساب Google".
signin
زر عادي يحمل تصنيف &quot;تسجيل الدخول&quot; زر رمز بدون نص مرئي
نص الزر هو "تسجيل الدخول".

data-shape

شكل الزر تكون القيمة التلقائية rectangular. اطّلِع على الجدول التالي لمزيد من المعلومات:

النوع مطلوب مثال
سلسلة اختياري data-shape="rectangular"

يسرد الجدول التالي أشكال الأزرار المتاحة وأوصافها:

شكل
rectangular
زر مستطيل عادي زر رمز مستطيل زر مستطيل مخصّص
زر مستطيل الشكل إذا تم استخدامه لنوع الزر icon ، يكون مطابقًا لـ square.
pill
زر عادي على شكل قرص زر رمز على شكل قرص زر مخصّص على شكل قرص
زرّ على شكل قرص. إذا تم استخدامه لزر icon ، يكون مطابقًا لـ circle.
circle
زر عادي دائري زر رمز دائري زر دائري مخصّص
زر الشكل الدائري إذا تم استخدامه لنوع الزر standard ، سيكون مطابقًا لـ pill.
square
زرّ مربع عادي زر رمز مربّع زر مربع مخصّص
زرّ مربّع الشكل إذا تم استخدامه لنوع الزر standard ، سيكون مطابقًا لـ rectangular.

data-logo_alignment

محاذاة شعار Google تكون القيمة التلقائية left. لا تنطبق هذه السمة إلا على نوع الزر standard. اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع مطلوب مثال
سلسلة اختياري data-logo_alignment="center"

يسرد الجدول التالي المحاذاة المتاحة وأوصافها:

logo_alignment
left
زر عادي يحمل شعار G على يمينه
محاذاة شعار Google على يمين الصفحة
center
زر عادي يتوسطه شعار G
محاذاة شعار Google في الوسط

data-width

الحد الأدنى لعرض الزر، بالبكسل الحد الأقصى للعرض المتاح هو 400 بكسل.

اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع مطلوب مثال
سلسلة اختياري data-width=400

data-locale

اختيارية: عرض نص الزر باستخدام اللغة المحدّدة، وإلا سيتم استخدام الإعدادات التلقائية في حساب المستخدم على Google أو إعدادات المتصفّح. أضِف المَعلمة hl ورمز اللغة إلى توجيه src عند تحميل المكتبة، على سبيل المثال: gsi/client?hl=<iso-639-code>.

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

اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع مطلوب مثال
سلسلة اختياري data-locale="zh_CN"

data-click_listener

يمكنك تحديد دالة JavaScript ليتمّ استدعاؤها عند النقر على الزر "تسجيل الدخول باستخدام حساب Google" باستخدام سمة data-click_listener.

  <script>
    function onClickHandler(){
      console.log("Sign in with Google button clicked...")
    }
  </script>
  .....
  <div class="g_id_signin"
      data-size="large"
      data-theme="outline"
      data-click_listener="onClickHandler">
  </div>

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

data-state

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

اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع مطلوب مثال
سلسلة اختياري data-state="button 1"

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

يجب أن تعالج نقاط النهاية من جهة الخادم طلبات HTTP POST التالية.

نقطة نهاية معالِج رمز التعريف

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

يحتوي طلب HTTP POST على المعلومات التالية:

التنسيق الاسم الوصف
ملف تعريف الارتباط g_csrf_token سلسلة عشوائية تتغيّر مع كل طلب إلى نقطة نهاية معالِج
مَعلمة الطلب g_csrf_token سلسلة متطابقة مع قيمة ملف تعريف الارتباط السابق، g_csrf_token.
مَعلمة الطلب credential رمز التعريف الذي تصدره Google
مَعلمة الطلب select_by كيفية اختيار بيانات الاعتماد
مَعلمة الطلب state لا يتم تحديد هذه المَعلمة إلا عندما ينقر المستخدم على زر "تسجيل الدخول باستخدام حساب Google" لتسجيل الدخول، ويتم تحديد سمة state للزر.

شهادة

عند فك ترميزه، يبدو رمز التعريف على النحو التالي: 

header
{
  "alg": "RS256",
  "kid": "f05415b13acb9590f70df862765c655f5a7a019e", // JWT signature
  "typ": "JWT"
}
payload
{
  "iss": "https://accounts.google.com", // The JWT's issuer
  "nbf":  161803398874,
  "aud": "314159265-pi.apps.googleusercontent.com", // Your server's client ID
  "sub": "3141592653589793238", // The unique ID of the user's Google Account
  "hd": "gmail.com", // If present, the host domain of the user's GSuite email address
  "email": "elisa.g.beckett@gmail.com", // The user's email address
  "email_verified": true, // true, if Google has verified the email address
  "azp": "314159265-pi.apps.googleusercontent.com",
  "name": "Elisa Beckett",
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/e2718281828459045235360uler",
  "given_name": "Eliza",
  "family_name": "Beckett",
  "iat": 1596474000, // Unix timestamp of the assertion's creation time
  "exp": 1596477600, // Unix timestamp of the assertion's expiration time
  "jti": "abc161803398874def"
}

الحقل sub هو معرّف فريد على مستوى العالم لحساب Google. استخدِم حقل sub فقط كمعرّف للمستخدم لأنّه فريد بين جميع حسابات Google ولا تتم إعادة استخدامه أبدًا. لا تستخدِم عنوان البريد الإلكتروني كمعرّف لأنّه يمكن أن يتضمّن حساب Google عناوين بريد إلكتروني متعدّدة في أوقات مختلفة.

باستخدام الحقول email وemail_verified وhd، يمكنك تحديد ما إذا كانت Google تستضيف عنوان بريد إلكتروني وتكون جهة موثوق بها. في الحالات التي تكون فيها Google مرجعًا موثوقًا، يتم تأكيد أنّ المستخدم هو مالك الحساب الشرعي.

الحالات التي تكون فيها Google جهة موثوقة:

  • إذا كان email يحتوي على اللاحقة @gmail.com، هذا يعني أنّه حساب Gmail.
  • إذا كان email_verified صحيحًا وتم ضبط hd، هذا يعني أنّه حساب Google Workspace.

يمكن للمستخدمين التسجيل في حسابات Google بدون استخدام Gmail أو Google Workspace. عندما لا يحتوي email على اللاحقة @gmail.com ولا يتوفّر hd، لن تكون Google موثوقًا بها، وينُصح باستخدام كلمة المرور أو طرق أخرى لتحدّي المستخدمين بغرض إثبات هويتهم. يمكن أن يكون الخيار email_verified صحيحًا أيضًا لأنّ Google أثبتت هوية المستخدم في البداية عند إنشاء حساب Google، ولكن قد يكون قد تغيّر ملكية حساب البريد الإلكتروني التابع لجهة خارجية.

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

select_by

يسرد الجدول التالي القيم المحتمَلة للحقل select_by. يتم استخدام نوع الزر المستخدَم مع حالة الجلسة والموافقة لضبط القيمة.

  • ضغط المستخدم على الزر "تسجيل الدخول بنقرة واحدة" أو "تسجيل الدخول باستخدام حساب Google" أو استخدم عملية "تسجيل الدخول تلقائيًا" بدون لمس الشاشة.

  • تم العثور على جلسة حالية، أو اختار المستخدم حسابًا على Google وسجلّ الدخول إليه لإنشاء جلسة جديدة.

  • قبل مشاركة بيانات اعتماد رمز التعريف مع تطبيقك، على المستخدم إجراء ما يلي:

    • الضغط على زر "تأكيد" لمنح موافقته على مشاركة بيانات الاعتماد أو
    • قد منحت الموافقة في السابق واستخدمت ميزة "اختيار حساب" لاختيار حساب Google.

يتم ضبط قيمة هذا الحقل على أحد هذه الأنواع:

القيمة الوصف
auto تسجيل دخول تلقائي لمستخدم لديه جلسة حالية سبق له الموافقة على مشاركة بيانات الاعتماد لا ينطبق إلا على المتصفّحات غير المتوافقة مع FedCM.
user مستخدم لديه جلسة حالية وسبق أن منح الموافقة على النقر على زر "متابعة باستخدام الحساب نفسه" في ميزة "النقرة الواحدة" لمشاركة بيانات الاعتماد لا ينطبق هذا الإعداد إلا على المتصفّحات غير المتوافقة مع "إدارة المحتوى في المقاييس".
fedcm ضغط مستخدم على زر "متابعة باسم" في ميزة "النقرة الواحدة" لمشاركة بيانات الاعتماد باستخدام FedCM. لا ينطبق ذلك إلا على المتصفّحات المتوافقة مع FedCM.
fedcm_auto تسجيل دخول تلقائي لمستخدم لديه جلسة حالية سبق له أن منح الموافقة على مشاركة بيانات الاعتماد باستخدام ميزة "النقرة الواحدة" في FedCM لا ينطبق ذلك إلا على المتصفّحات المتوافقة مع FedCM.
user_1tap ضغط مستخدم لديه جلسة حالية على الزر "متابعة باستخدام البيانات نفسها" في ميزة "النقرة الواحدة" لمنح الموافقة ومشاركة بيانات الاعتماد. لا ينطبق هذا الإعداد إلا على الإصدار 75 من Chrome والإصدارات الأحدث.
user_2tap ضغط مستخدم ليس لديه جلسة حالية على زر "متابعة باستخدام" في ميزة "النقرة الواحدة" لاختيار حساب، ثم ضغط على زر التأكيد في النافذة المنبثقة لمنح الموافقة ومشاركة بيانات الاعتماد. ينطبق على المتصفّحات غير المستندة إلى Chromium.
btn مستخدم لديه جلسة حالية منحه الموافقة سابقًا الضغط على الزر "تسجيل الدخول باستخدام حساب Google" واختيار حساب Google من 'اختيار حساب" لمشاركة بيانات الاعتماد
btn_confirm ضغط مستخدم لديه جلسة حالية على الزر "تسجيل الدخول باستخدام حساب Google" ثم على زر "تأكيد" لمنح الموافقة ومشاركة بيانات الاعتماد.
btn_add_session ضغط مستخدم ليس لديه جلسة حالية وسبق له منح الموافقة على زر "تسجيل الدخول باستخدام حساب Google" لاختيار حساب Google ومشاركة بيانات الاعتماد.
btn_confirm_add_session ضغط مستخدم ليس لديه جلسة حالية أولاً على الزر "تسجيل الدخول باستخدام حساب Google" لاختيار حساب Google، ثم ضغط على الزر "تأكيد" للموافقة على مشاركة بيانات الاعتماد.

الولاية

لا يتم تحديد هذه المَعلمة إلا عندما ينقر المستخدِم على زر "تسجيل الدخول باستخدام حساب Google" لتسجيل الدخول، ويتم تحديد سمة data-state للزر الذي تم النقر عليه. قيمة هذا الحقل هي القيمة نفسها التي حدّدتها في سمة data-state للزر.

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

نقطة نهاية معالِج بيانات اعتماد كلمة المرور

تعالج نقطة نهاية معالِج بيانات اعتماد كلمة المرور بيانات اعتماد كلمة المرور التي يسترجعها مدير بيانات الاعتماد الأصلي.

يحتوي طلب HTTP POST على المعلومات التالية:

التنسيق الاسم الوصف
ملف تعريف الارتباط g_csrf_token سلسلة عشوائية تتغيّر مع كل طلب إلى نقطة نهاية معالِج
مَعلمة الطلب g_csrf_token سلسلة متطابقة مع قيمة ملف تعريف الارتباط السابق، g_csrf_token.
مَعلمة الطلب email رمز التعريف هذا الذي تصدره Google.
مَعلمة الطلب password كيفية اختيار بيانات الاعتماد