توضّح صفحة المرجع هذه واجهة برمجة التطبيقات لسمات بيانات HTML الخاصة بميزة "تسجيل الدخول باستخدام Google". يمكنك استخدام واجهة برمجة التطبيقات لعرض طلب One Tap أو زر "تسجيل الدخول باستخدام حساب Google" على صفحات الويب.
العنصر الذي يحمل المعرّف "g_id_onload"
يمكنك وضع سمات بيانات ميزة "تسجيل الدخول باستخدام حساب Google" في أي عناصر مرئية أو غير مرئية، مثل <div> و<span>. الشرط الوحيد هو ضبط معرّف العنصر على g_id_onload. لا تضع هذا المعرّف على عناصر متعددة.
سمات البيانات
يسرد الجدول التالي سمات البيانات مع أوصافها:
| السمة | |
|---|---|
data-client_id |
معرّف العميل لتطبيقك |
data-auto_prompt |
عرض نقرة Google One |
data-auto_select |
تتيح هذه السمة الاختيار التلقائي على Google One Tap. |
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 الوسيط عندما يغلق المستخدمون ميزة One Tap يدويًا. |
data-itp_support |
تفعيل تجربة المستخدم المحسّنة لميزة "النقرة الواحدة" على المتصفّحات التي تتوافق مع "سياسة الشفافية وتتبُّع الإعلانات" |
data-login_hint |
تخطّي اختيار الحساب من خلال تقديم تلميح للمستخدم. |
data-hd |
تقييد اختيار الحساب حسب النطاق |
data-use_fedcm_for_prompt |
السماح للمتصفّح بالتحكّم في طلبات تسجيل الدخول للمستخدمين والتوسّط في عملية تسجيل الدخول بين موقعك الإلكتروني وGoogle |
data-use_fedcm_for_button |
يحدِّد هذا الحقل ما إذا كان يجب استخدام تجربة المستخدم الخاصة بزر FedCM على Chrome
(الإصدار 125 والإصدارات الأحدث على أجهزة الكمبيوتر والإصدار 128 والإصدارات الأحدث على Android). القيمة التلقائية هي false. |
data-button_auto_select |
تحديد ما إذا كان سيتم تفعيل خيار الاختيار التلقائي في مسار زر FedCM. في حال تفعيل هذه الميزة، سيتم تلقائيًا تسجيل دخول المستخدمين العائدين الذين لديهم جلسة نشطة على Google، وسيتم تخطّي طلب "أداة اختيار الحساب". القيمة التلقائية هي false. |
أنواع السمات
تحتوي الأقسام التالية على تفاصيل حول نوع كل سمة ومثال عليها.
data-client_id
هذه السمة هي معرّف العميل لتطبيقك، ويمكن العثور عليها وإنشاؤها في وحدة تحكّم Google Cloud. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | نعم | data-client_id="CLIENT_ID.apps.googleusercontent.com" |
data-auto_prompt
تحدّد هذه السمة ما إذا كان سيتم عرض ميزة "نقرة واحدة" أم لا. القيمة التلقائية هي true. لا يتم عرض ميزة "نقرة واحدة من Google" عندما تكون هذه القيمة false. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| قيمة منطقية | اختياري | data-auto_prompt="true" |
data-auto_select
تحدّد هذه السمة ما إذا كان سيتم عرض رمز مميّز للمعرّف تلقائيًا
بدون أي تفاعل من المستخدم، وذلك في حال وافقت جلسة واحدة فقط على تطبيقك.
القيمة التلقائية هي false. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| قيمة منطقية | اختياري | data-auto_select="true" |
data-login_uri
هذه السمة هي معرّف الموارد المنتظم (URI) لنقطة نهاية تسجيل الدخول.
يجب أن تتطابق القيمة تمامًا مع أحد معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه الخاصة بعميل OAuth 2.0 الذي أعددته في "منصة مصادقة Google"، ويجب أن تتوافق مع قواعد التحقّق من صحة معرّف الموارد المنتظمة (URI) لإعادة التوجيه.
يمكن حذف هذه السمة إذا كانت الصفحة الحالية هي صفحة تسجيل الدخول، وفي هذه الحالة، يتم نشر بيانات الاعتماد إلى هذه الصفحة تلقائيًا.
يتم نشر استجابة بيانات اعتماد رمز التعريف إلى نقطة نهاية تسجيل الدخول عندما لا يتم تحديد دالة معاودة الاتصال وينقر المستخدم على زر "تسجيل الدخول باستخدام حساب Google" أو زر One Tap، أو عندما يتم تسجيل الدخول تلقائيًا.
يجب أن تعالج نقطة نهاية تسجيل الدخول طلبات POST التي تحتوي على المَعلمة credential مع قيمة رمز التعريف في نص الطلب.
اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | اختياري | مثال |
|---|---|---|
| عنوان URL | تكون القيمة التلقائية هي معرّف الموارد المنتظم (URI) للصفحة الحالية أو القيمة التي تحدّدها. يتم تجاهله عند ضبط data-ux_mode="popup" وdata-callback. |
data-login_uri="https://www.example.com/login" |
data-callback
هذه السمة هي اسم دالة JavaScript التي تعالج رمز التعريف الذي تم عرضه. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | مطلوبة إذا لم يتم ضبط data-login_uri. |
data-callback="handleToken" |
قد يتم استخدام إحدى السمتَين data-login_uri وdata-callback. ويعتمد ذلك على إعدادات المكوّن ووضع تجربة المستخدم التالية:
السمة
data-login_uriمطلوبة لوضع تجربة المستخدمredirectلزر "تسجيل الدخول باستخدام حساب Google"، والذي يتجاهل السمةdata-callback.يجب ضبط إحدى هاتين السمتَين لوضع تجربة المستخدم في ميزة One Tap من Google وزر
popupتسجيل الدخول باستخدام حساب Google. وفي حال ضبط كليهما، تكون الأولوية لسمةdata-callback.
لا تتوافق واجهة برمجة تطبيقات HTML مع دوال JavaScript ضِمن مساحة اسم.
بدلاً من ذلك، استخدِم دالة 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" |
لا تتوافق واجهة برمجة تطبيقات HTML مع دوال JavaScript ضِمن مساحة اسم.
بدلاً من ذلك، استخدِم دالة 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
يستخدم ملف تعريف ارتباط للتحكّم في عرض طلب One Tap. إذا كانت ملفات تعريف الارتباط المحدّدة في هذه السمة تتضمّن قيمة غير فارغة، لن يتم عرض الطلب. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | data-skip_prompt_cookie="SID" |
data-nonce
هذه السمة هي سلسلة عشوائية يستخدمها الرمز المميّز لتعريف الهوية لمنع هجمات إعادة الإرسال. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | data-nonce="biaqbm70g23" |
يقتصر طول الرقم العشوائي المستخدَم مرة واحدة على الحد الأقصى لحجم JWT الذي تتيحه بيئتك، بالإضافة إلى قيود حجم HTTP الفردية في المتصفّح والخادم.
data-context
يغيّر هذا الحقل نص العنوان والرسائل المعروضة في طلب One Tap، ولا يؤثّر في متصفّحات ITP. القيمة التلقائية هي signin.
اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | data-context="use" |
يسرد الجدول التالي جميع السياقات المتاحة وأوصافها:
| السياق | |
|---|---|
signin |
تسجيل الدخول إلى |
signup |
الاشتراك في |
use |
"الاستخدام" |
data-moment_callback
هذه السمة هي اسم الدالة الخاصة بمستمع إشعارات حالة واجهة مستخدم الطلب. لمزيد من المعلومات، راجِع نوع البيانات
PromptMomentNotification.
اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | data-moment_callback="logMomentNotification" |
لا تتوافق واجهة برمجة تطبيقات HTML مع دوال JavaScript ضِمن مساحة اسم.
بدلاً من ذلك، استخدِم دالة JavaScript عامة بدون مساحة اسم. على سبيل المثال، استخدِم
mylibCallback بدلاً من mylib.callback.
data-state_cookie_domain
إذا كنت بحاجة إلى عرض One Tap في نطاق رئيسي ونطاقاته الفرعية، مرِّر النطاق الرئيسي إلى هذه السمة ليتم استخدام ملف تعريف ارتباط واحد للحالة المشتركة. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | data-state_cookie_domain="example.com" |
data-ux_mode
تحدّد هذه السمة مسار تجربة المستخدم الذي يستخدمه زر "تسجيل الدخول باستخدام حساب Google". القيمة التلقائية هي popup. ليس لهذه السمة أي تأثير في تجربة المستخدم في One Tap. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | data-ux_mode="redirect" |
يسرد الجدول التالي أوضاع تجربة المستخدم المتاحة وأوصافها.
| وضع تجربة المستخدم | |
|---|---|
popup |
تنفيذ عملية تسجيل الدخول في نافذة منبثقة |
redirect |
تنفيذ عملية تسجيل الدخول من خلال إعادة توجيه الصفحة بالكامل |
data-allowed_parent_origin
المصادر المسموح لها بتضمين إطار iframe الوسيط يعمل One Tap في وضع iframe الوسيط إذا كانت هذه السمة متوفّرة. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة أو مصفوفة سلاسل | اختياري | data-allowed_parent_origin="https://example.com" |
يسرد الجدول التالي أنواع القيم المسموح بها وأوصافها.
| أنواع القيم | ||
|---|---|---|
string |
معرّف موارد منتظم (URI) لنطاق واحد | "https://example.com" |
string array |
قائمة بمعرّفات الموارد المنتظمة (URI) الخاصة بالنطاقات مفصولة بفواصل | "https://news.example.com,https://local.example.com" |
إذا كانت قيمة السمة data-allowed_parent_origin غير صالحة، سيتعذّر إعداد وضع iframe الوسيط في One Tap وسيتوقف.
يمكن أيضًا استخدام بادئات أحرف البدل. على سبيل المثال، "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" |
لا تتوافق واجهة برمجة تطبيقات HTML مع دوال JavaScript ضِمن مساحة اسم.
بدلاً من ذلك، استخدِم دالة 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 القيمة التلقائية هي "خطأ". يمكنك الاطّلاع على صفحة الانتقال إلى FedCM للحصول على مزيد من المعلومات.
| النوع | مطلوب | مثال |
|---|---|---|
| قيمة منطقية | اختياري | data-use_fedcm_for_prompt="true" |
data-use_fedcm_for_button
يحدِّد هذا الحقل ما إذا كان يجب استخدام تجربة المستخدم لزر FedCM على Chrome (الإصدار 125 أو إصدار أحدث على أجهزة الكمبيوتر والإصدار 128 أو إصدار أحدث على أجهزة Android). القيمة التلقائية هي false. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| قيمة منطقية | اختياري | data-use_fedcm_for_button="true" |
data-button_auto_select
يحدّد هذا الحقل ما إذا كان سيتم تفعيل خيار الاختيار التلقائي في مسار زر FedCM. في حال تفعيل هذه الميزة، سيتم تلقائيًا تسجيل دخول المستخدمين العائدين الذين لديهم جلسة نشطة على Google، وسيتم تجاوز طلب "أداة اختيار الحساب". القيمة التلقائية هي false. يجب تفعيل ميزة "تسجيل الدخول التلقائي باستخدام الزر" بشكل صريح أثناء عملية الموافقة على تشغيل الميزة. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| قيمة منطقية | اختياري | data-button_auto_select="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 |
|
signup_with |
|
continue_with |
|
signin |
|
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 |
|
center |
|
data-width
الحد الأدنى لعرض الزر، بالبكسل. الحد الأقصى للعرض المتاح هو 400 بكسل.
اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | data-width=400 |
data-locale
اختيارية: عرض نص الزر باستخدام اللغة المحدّدة، وإلا سيتم استخدام اللغة التلقائية لحساب Google أو إعدادات المتصفّح. أضِف المَعلمة hl ورمز اللغة إلى التوجيه src عند تحميل المكتبة، على سبيل المثال:
gsi/client?hl=<iso-639-code>.
في حال عدم ضبطها، يتم استخدام اللغة التلقائية للمتصفّح أو اللغة المفضّلة للمستخدم في جلسة Google. لذلك، قد يرى المستخدمون المختلفون إصدارات مختلفة من الأزرار المترجمة، وربما بأحجام مختلفة.
اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | data-locale="zh_CN" |
data-click_listener
يمكنك تحديد دالة JavaScript يتم استدعاؤها عند النقر على زر data-click_listener باستخدام السمة 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 التالية.
نقطة نهاية معالج الرمز المميز لتعريف الهوية
تعالج نقطة نهاية معالج الرمز المميز لتعريف الهوية الرمز المميز لتعريف الهوية. استنادًا إلى حالة الحساب المعني، يمكنك تسجيل دخول المستخدم وتوجيهه إما إلى صفحة تسجيل أو إلى صفحة ربط حساب للحصول على معلومات إضافية.
مثال على طلب إلى نقطة نهاية تسجيل الدخول:
POST /login HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Cookie: g_csrf_token=<RANDOM_STRING>
Host: www.example.com
credential=<JWT_ENCODED_ID_TOKEN>&g_csrf_token=<RANDOM_STRING>
يتضمّن طلب HTTP POST المعلومات التالية:
| التنسيق | الاسم | الوصف |
|---|---|---|
| ملف تعريف الارتباط | g_csrf_token |
سلسلة عشوائية تتغيّر مع كل طلب إلى نقطة نهاية تسجيل الدخول المحدّدة بواسطة data-login_uri، ويجب أن تتطابق مع القيمة في مَعلمة الطلب g_csrf_token. |
| مَعلمة الطلب | g_csrf_token |
سلسلة عشوائية تتغيّر مع كل طلب إلى نقطة نهاية تسجيل الدخول المحدّدة بواسطة data-login_uri، ويجب أن تتطابق مع قيمة ملف تعريف الارتباط g_csrf_token. |
| مَعلمة الطلب | credential |
رمز JWT المميّز المشفر الذي تصدره 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 ولا تتم إعادة استخدامه أبدًا.
باستخدام الحقول email وemail_verified وhd، يمكنك تحديد ما إذا كانت Google تستضيف عنوان بريد إلكتروني وتملك سلطة إدارته. في الحالات التي تكون فيها Google هي الجهة الموثوقة، يتم التأكّد من أنّ المستخدم هو صاحب الحساب الشرعي.
الحالات التي تكون فيها Google هي الجهة الموثوقة:
- إذا كان عنوان البريد الإلكتروني ينتهي باللاحقة
@gmail.com، فهذا يعني أنّه حساب Gmail.email - إذا كانت قيمة
email_verifiedصحيحة وتم ضبطhd، يكون هذا حساب Google Workspace.
يمكن للمستخدمين التسجيل للحصول على حسابات Google بدون استخدام Gmail أو Google Workspace.
عندما لا يحتوي email على لاحقة @gmail.com ولا يتوفّر hd، لا يكون Google مصدرًا موثوقًا به، ويُنصح باستخدام كلمة المرور أو طرق أخرى للتحقّق من هوية المستخدم. يمكن أن تكون القيمة email_verified صحيحة أيضًا لأنّ Google أثبتت في البداية ملكية المستخدم للحساب عند إنشاء حساب Google، ولكن قد تكون ملكية حساب البريد الإلكتروني التابع لجهة خارجية قد تغيّرت منذ ذلك الحين.
يعرض الحقل exp وقت انتهاء صلاحية الرمز المميز لإثبات ملكيته على
الخادم. تبلغ مدة صلاحية رمز التعريف المميز الذي يتم الحصول عليه من ميزة "تسجيل الدخول باستخدام حساب Google" ساعة واحدة. يجب تأكيد الرمز المميّز قبل انتهاء صلاحيته. لا تستخدِم exp لإدارة الجلسات. لا يعني انتهاء صلاحية رمز التعريف
أنّ المستخدم قد سجّل الخروج. يتحمّل تطبيقك مسؤولية إدارة جلسات المستخدمين.
g_csrf_token
رمز مميّز للحالة مضاد للتزوير هذه الرمز المميز لتزوير الطلبات من مواقع إلكترونية مختلفة (CSRF) تم إنشاؤه بواسطة مكتبة gsi/client. يتم تضمين قيمة عشوائية كملف تعريف ارتباط وكإحدى مَعلمات الطلب في نص حمولة POST. إذا لم تتطابق هاتان القيمتان عند معالجة الطلب على خادمك، يجب اعتبار الطلب غير صالح.
select_by
يسرد الجدول التالي القيم المحتملة للحقل select_by. يتم استخدام نوع الزر مع حالة الجلسة والموافقة لضبط القيمة.
ضغط المستخدم على الزر "نقرة واحدة" أو "تسجيل الدخول باستخدام حساب Google" أو استخدم عملية "تسجيل الدخول تلقائيًا" بدون لمس.
تم العثور على جلسة حالية، أو اختار المستخدم حساب Google وسجّل الدخول إليه لإنشاء جلسة جديدة.
قبل مشاركة بيانات اعتماد رمز التعريف مع تطبيقك، يجب أن يكون المستخدم قد
- ضغط على زر "تأكيد" لمنح موافقته على مشاركة بيانات الاعتماد، أو
- سبق له منح الموافقة واستخدام ميزة "اختيار حساب" لاختيار حساب Google.
يتم ضبط قيمة هذا الحقل على أحد الأنواع التالية:
| القيمة | الوصف |
|---|---|
auto |
تسجيل دخول تلقائي لمستخدم لديه جلسة حالية وسبق له الموافقة على مشاركة بيانات الاعتماد لا ينطبق ذلك إلا على المتصفّحات التي لا تتوافق مع FedCM. |
user |
نقر مستخدم لديه جلسة حالية وسبق له منح الموافقة على الزر "متابعة باسم" في One Tap لمشاركة بيانات الاعتماد. لا ينطبق هذا الإعداد إلا على المتصفّحات التي لا تتوافق مع FedCM. |
fedcm |
ضغط المستخدم على زر "متابعة باسم" في One Tap لمشاركة بيانات الاعتماد باستخدام FedCM. لا ينطبق هذا الإعداد إلا على المتصفّحات التي تتوافق مع FedCM. |
fedcm_auto |
تسجيل دخول المستخدم تلقائيًا باستخدام جلسة حالية بعد أن سبق له الموافقة على مشاركة بيانات الاعتماد باستخدام FedCM One Tap لا ينطبق هذا الإعداد إلا على المتصفّحات التي تتوافق مع FedCM. |
user_1tap |
ضغط مستخدم لديه جلسة حالية على زر "المتابعة باسم" في خدمة "نقرة واحدة" لمنح الموافقة ومشاركة بيانات الاعتماد. ينطبق هذا الإعداد فقط على الإصدار 75 من Chrome والإصدارات الأحدث. |
user_2tap |
ضغط مستخدم ليس لديه جلسة حالية على زر "المتابعة باسم" في One Tap لاختيار حساب، ثم ضغط على زر "تأكيد" في نافذة منبثقة لمنح الموافقة ومشاركة بيانات الاعتماد. ينطبق ذلك على المتصفّحات غير المستندة إلى 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 |
سلسلة عشوائية تتغيّر مع كل طلب إلى نقطة نهاية تسجيل الدخول المحدّدة بواسطة data-native_login_uri، ويجب أن تتطابق مع القيمة في مَعلمة الطلب g_csrf_token. |
| مَعلمة الطلب | g_csrf_token |
سلسلة عشوائية تتغيّر مع كل طلب إلى نقطة نهاية تسجيل الدخول المحدّدة بواسطة data-native_login_uri، ويجب أن تتطابق مع قيمة ملف تعريف الارتباط g_csrf_token. |
| مَعلمة الطلب | email |
هذه هي الرمز المميز لمعرّف Google الذي تصدره Google. |
| مَعلمة الطلب | password |
كيفية اختيار بيانات الاعتماد |