توضّح صفحة المرجع هذه واجهة برمجة التطبيقات Sign-In JavaScript API. يمكنك استخدام واجهة برمجة التطبيقات هذه لعرض طلب One Tap أو زر "تسجيل الدخول باستخدام Google" على صفحات الويب.
الطريقة: google.accounts.id.initialize
تُهيئ الطريقة google.accounts.id.initialize برنامج "تسجيل الدخول باستخدام حساب Google" استنادًا إلى عنصر الإعداد. في ما يلي مثال على الرمز البرمجي الخاص بطريقة العرض:
google.accounts.id.initialize(IdConfiguration)
ينفّذ مثال الرمز البرمجي التالي طريقة google.accounts.id.initialize باستخدام دالة onload:
<script>
window.onload = function () {
google.accounts.id.initialize({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
callback: handleCredentialResponse
});
google.accounts.id.prompt();
};
</script>
تنشئ الطريقة google.accounts.id.initialize مثيلاً لبرنامج "تسجيل الدخول باستخدام حساب Google" يمكن لجميع الوحدات في صفحة الويب نفسها استخدامه بشكل ضمني.
- ما عليك سوى استدعاء طريقة
google.accounts.id.initializeمرة واحدة حتى إذا كنت تستخدم وحدات متعددة (مثل "نقرة واحدة"، والزر المخصّص، والإبطال، وما إلى ذلك) في صفحة الويب نفسها. - في حال استدعاء الطريقة
google.accounts.id.initializeعدة مرات، سيتم تذكُّر الإعدادات في آخر عملية استدعاء واستخدامها فقط.
في الواقع، تتم إعادة ضبط الإعدادات كلما استدعيت الطريقة google.accounts.id.initialize، وتستخدم جميع الطرق اللاحقة في صفحة الويب نفسها الإعدادات الجديدة على الفور.
نوع البيانات: IdConfiguration
يسرد الجدول التالي الحقول وأوصاف نوع البيانات IdConfiguration:
| الحقل | |
|---|---|
client_id |
معرّف العميل لتطبيقك |
auto_select |
تتيح هذه السمة إمكانية الاختيار التلقائي. |
callback |
دالة JavaScript التي تعالج رموز التعريف. يستخدم وضع تجربة المستخدم في ميزة "نقرة واحدة من Google" وزر popup "تسجيل الدخول باستخدام حساب Google" هذه السمة. |
login_uri |
عنوان URL لنقطة نهاية تسجيل الدخول. يستخدم وضع تجربة المستخدم redirect لزر "تسجيل الدخول باستخدام حساب Google" هذه السمة. |
native_callback |
دالة JavaScript التي تعالج بيانات اعتماد كلمة المرور. |
cancel_on_tap_outside |
يلغي الطلب إذا نقر المستخدم خارج الطلب. |
prompt_parent_id |
المعرّف DOM لعنصر حاوية طلب One Tap |
nonce |
سلسلة عشوائية لرموز التعريف |
context |
العنوان والكلمات في إشعار ميزة "نقرة واحدة" |
state_cookie_domain |
إذا كنت بحاجة إلى استدعاء One Tap في النطاق الرئيسي ونطاقاته الفرعية، مرِّر النطاق الرئيسي إلى هذا الحقل ليتم استخدام ملف تعريف ارتباط مشترك واحد. |
ux_mode |
مسار تجربة المستخدم لزر "تسجيل الدخول باستخدام حساب Google" |
allowed_parent_origin |
المصادر المسموح لها بتضمين إطار iframe الوسيط يتم تشغيل One Tap في وضع إطار iframe الوسيط إذا كان هذا الحقل متوفّرًا. |
intermediate_iframe_close_callback |
تتجاوز هذه السمة السلوك التلقائي لإطار iframe الوسيط عندما يغلق المستخدمون ميزة One Tap يدويًا. |
itp_support |
تفعيل تجربة المستخدم المحسّنة لميزة "النقرة الواحدة" على المتصفّحات التي تتوافق مع "سياسة الشفافية وتتبُّع الإعلانات" |
login_hint |
تخطّي اختيار الحساب من خلال تقديم تلميح للمستخدم. |
hd |
تقييد اختيار الحساب حسب النطاق |
use_fedcm_for_prompt |
السماح للمتصفّح بالتحكّم في طلبات تسجيل الدخول للمستخدمين والتوسّط في عملية تسجيل الدخول بين موقعك الإلكتروني وGoogle |
use_fedcm_for_button |
يحدِّد هذا الحقل ما إذا كان يجب استخدام تجربة المستخدم الخاصة بزر FedCM على Chrome
(الإصدار 125 والإصدارات الأحدث على أجهزة الكمبيوتر والإصدار 128 والإصدارات الأحدث على Android). القيمة التلقائية هي false. |
button_auto_select |
تحديد ما إذا كان سيتم تفعيل خيار الاختيار التلقائي في مسار زر FedCM. في حال تفعيل هذه الميزة، سيتم تلقائيًا تسجيل دخول المستخدمين العائدين الذين لديهم جلسة نشطة على Google، وسيتم تجاوز طلب "أداة اختيار الحساب". القيمة التلقائية هي false. |
client_id
هذا الحقل هو معرّف عميل تطبيقك، ويمكن العثور عليه وإنشاؤه في وحدة تحكّم Google Cloud. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | نعم | client_id: "CLIENT_ID.apps.googleusercontent.com" |
auto_select
يحدّد هذا الحقل ما إذا كان سيتم عرض رمز تعريف تلقائيًا بدون أي تفاعل من المستخدم عندما تكون هناك جلسة واحدة فقط على Google وافقت على تطبيقك من قبل. تكون القيمة التلقائية false. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| قيمة منطقية | اختياري | auto_select: true |
callback
هذا الحقل هو دالة JavaScript التي تعالج رمز التعريف المميز الذي يتم عرضه من خلال
نافذة One Tap أو النافذة المنبثقة. هذه السمة مطلوبة في حال استخدام وضع تجربة المستخدم popup في ميزة "نقرة واحدة من Google" أو زر "تسجيل الدخول باستخدام حساب Google". اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| دالة | مطلوب لتفعيل ميزة "نقرة واحدة" وpopup وضع تجربة المستخدم |
callback: handleResponse |
login_uri
هذه السمة هي معرّف الموارد المنتظم (URI) لنقطة نهاية تسجيل الدخول.
يجب أن تتطابق القيمة تمامًا مع أحد معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه الخاصة بعميل OAuth 2.0 الذي ضبطته في Google Cloud Console، ويجب أن تتوافق مع قواعد التحقّق من صحة معرّف الموارد المنتظم (URI) لإعادة التوجيه.
يمكن حذف هذه السمة إذا كانت الصفحة الحالية هي صفحة تسجيل الدخول، وفي هذه الحالة، يتم نشر بيانات الاعتماد إلى هذه الصفحة تلقائيًا.
يتم نشر استجابة بيانات اعتماد رمز التعريف إلى نقطة نهاية تسجيل الدخول عندما ينقر المستخدم على الزر "تسجيل الدخول باستخدام Google" ويتم استخدام وضع تجربة المستخدم لإعادة التوجيه.
اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | اختياري | مثال |
|---|---|---|
| عنوان URL | تكون القيمة التلقائية هي معرّف الموارد المنتظم (URI) للصفحة الحالية أو القيمة التي تحدّدها. لا يتم استخدامها إلا عند ضبط ux_mode: "redirect". |
login_uri: "https://www.example.com/login" |
يجب أن يتعامل نقطة نهاية تسجيل الدخول مع طلبات POST التي تحتوي على المَعلمة credential مع قيمة رمز تعريف في نص الطلب.
native_callback
هذا الحقل هو اسم دالة JavaScript التي تعالج بيانات اعتماد كلمة المرور التي يعرضها مدير بيانات الاعتماد المضمّن في المتصفح. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| دالة | اختياري | native_callback: handleResponse |
cancel_on_tap_outside
يحدّد هذا الحقل ما إذا كان سيتم إلغاء طلب One Tap إذا نقر المستخدم خارج النافذة المنبثقة. تكون القيمة التلقائية true. يمكنك إيقافها إذا ضبطت القيمة على false. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| قيمة منطقية | اختياري | cancel_on_tap_outside: false |
prompt_parent_id
تضبط هذه السمة رقم تعريف DOM لعنصر الحاوية. إذا لم يتم ضبطه، سيظهر طلب One Tap في أعلى يسار النافذة. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | prompt_parent_id: 'parent_id' |
رقم خاص
هذا الحقل عبارة عن سلسلة عشوائية يستخدمها رمز التعريف لمنع هجمات إعادة الإرسال. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | nonce: "biaqbm70g23" |
يقتصر طول الرقم العشوائي المستخدَم مرة واحدة على الحد الأقصى لحجم JWT الذي تتيحه بيئتك، بالإضافة إلى قيود حجم HTTP الفردية في المتصفّح والخادم.
context
يغيّر هذا الحقل نص العنوان والرسائل المعروضة في طلب One Tap، ولا يؤثّر في متصفّحات ITP. القيمة التلقائية هي signin.
اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | context: "use" |
يسرد الجدول التالي جميع السياقات المتاحة وأوصافها:
| السياق | |
|---|---|
signin |
تسجيل الدخول إلى |
signup |
الاشتراك في |
use |
"الاستخدام" |
state_cookie_domain
إذا كنت بحاجة إلى عرض One Tap في النطاق الرئيسي ونطاقاته الفرعية، مرِّر النطاق الرئيسي إلى هذا الحقل ليتم استخدام ملف تعريف ارتباط واحد للحالة المشترَكة. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | state_cookie_domain: "example.com" |
ux_mode
استخدِم هذا الحقل لضبط مسار تجربة المستخدم الذي يستخدمه زر "تسجيل الدخول باستخدام حساب Google". القيمة التلقائية هي popup. ليس لهذه السمة أي تأثير في تجربة المستخدم في One Tap. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | ux_mode: "redirect" |
يسرد الجدول التالي أوضاع تجربة المستخدم المتاحة وأوصافها.
| وضع تجربة المستخدم | |
|---|---|
popup |
تنفيذ عملية تسجيل الدخول في نافذة منبثقة |
redirect |
تنفيذ عملية تسجيل الدخول من خلال إعادة توجيه الصفحة بالكامل |
allowed_parent_origin
المصادر المسموح لها بتضمين إطار iframe الوسيط يعمل خيار "نقرة واحدة" في وضع iframe الوسيط إذا كان هذا الحقل متوفّرًا. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة أو مصفوفة سلاسل | اختياري | allowed_parent_origin: "https://example.com" |
يسرد الجدول التالي أنواع القيم المسموح بها وأوصافها.
| أنواع القيم | ||
|---|---|---|
string |
معرّف موارد منتظم (URI) لنطاق واحد | "https://example.com" |
string array |
مصفوفة من معرّفات الموارد المنتظمة (URI) للنطاقات | ["https://news.example.com", "https://local.example.com"] |
يمكن أيضًا استخدام بادئات أحرف البدل. على سبيل المثال، "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"غير صالح.
إذا كانت قيمة الحقل allowed_parent_origin غير صالحة، سيتعذّر بدء وضع iframe الوسيط في One Tap وسيتوقف.
intermediate_iframe_close_callback
تتجاوز هذه السمة السلوك التلقائي لإطار iframe الوسيط عندما يغلق المستخدمون ميزة One Tap يدويًا من خلال النقر على الزر "X" في واجهة مستخدم One Tap. والسلوك التلقائي هو إزالة إطار iframe الوسيط من DOM على الفور.
لا يسري حقل intermediate_iframe_close_callback إلا في وضع iframe المتوسط. ويؤثر ذلك فقط في إطار iframe الوسيط، وليس في إطار One Tap. تتم إزالة واجهة مستخدم "نقرة واحدة" قبل استدعاء دالة الرجوع.
| النوع | مطلوب | مثال |
|---|---|---|
| دالة | اختياري | intermediate_iframe_close_callback: logBeforeClose |
itp_support
يحدّد هذا الحقل ما إذا كان يجب تفعيل
تجربة المستخدم المحسّنة بنقرة واحدة على المتصفّحات المتوافقة مع ميزة "الحماية الذكية من التتبُّع" (ITP). القيمة التلقائية هي false. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| قيمة منطقية | اختياري | itp_support: true |
login_hint
إذا كان تطبيقك يعرف مسبقًا المستخدم الذي يجب تسجيل دخوله، يمكنه تقديم تلميح تسجيل الدخول إلى Google. وعند نجاح ذلك، يتم تخطّي خطوة اختيار الحساب. القيم المقبولة هي: عنوان بريد إلكتروني أو قيمة حقل sub لرمز مميّز للمعرّف.
لمزيد من المعلومات، اطّلِع على الحقل login_hint في مستندات OpenID Connect.
| النوع | مطلوب | مثال |
|---|---|---|
سلسلة، أو عنوان بريد إلكتروني، أو القيمة من حقل sub في رمز مميّز للمعرّف |
اختياري | login_hint: 'elisa.beckett@gmail.com' |
فائقة الدقة
عندما يكون لدى المستخدم حسابات متعددة ويجب تسجيل الدخول باستخدام حساب Workspace فقط، استخدِم هذا الحقل لتقديم تلميح باسم النطاق إلى Google. في حال نجاح هذا الإجراء، سيتم حصر حسابات المستخدمين المعروضة أثناء اختيار الحساب بالنطاق المقدَّم.
قيمة حرف البدل: * لا تعرض للمستخدم سوى حسابات Workspace وتستبعد حسابات المستهلكين (user@gmail.com) أثناء اختيار الحساب.
لمزيد من المعلومات، يُرجى الاطّلاع على الحقل hd في مستندات OpenID Connect.
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة. اسم نطاق مؤهَّل بالكامل أو *. | اختياري | hd: '*' |
use_fedcm_for_prompt
السماح للمتصفّح بالتحكّم في طلبات تسجيل الدخول للمستخدمين والتوسّط في عملية تسجيل الدخول بين موقعك الإلكتروني وGoogle القيمة التلقائية هي "خطأ". يمكنك الاطّلاع على صفحة الانتقال إلى FedCM للحصول على مزيد من المعلومات.
| النوع | مطلوب | مثال |
|---|---|---|
| قيمة منطقية | اختياري | use_fedcm_for_prompt: true |
use_fedcm_for_button
يحدِّد هذا الحقل ما إذا كان يجب استخدام تجربة المستخدم لزر FedCM على Chrome (الإصدار 125 أو إصدار أحدث على أجهزة الكمبيوتر والإصدار 128 أو إصدار أحدث على أجهزة Android). القيمة التلقائية هي false. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| قيمة منطقية | اختياري | use_fedcm_for_button: true |
button_auto_select
يحدّد هذا الحقل ما إذا كان سيتم تفعيل خيار الاختيار التلقائي في مسار زر FedCM. في حال تفعيل هذه الميزة، سيتم تلقائيًا تسجيل دخول المستخدمين العائدين الذين لديهم جلسة نشطة على Google، وسيتم تجاوز طلب "أداة اختيار الحساب". القيمة التلقائية هي false. يجب تفعيل ميزة "تسجيل الدخول التلقائي باستخدام الزر" بشكل صريح أثناء عملية الموافقة على تشغيل الميزة. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| قيمة منطقية | اختياري | button_auto_select: true |
الطريقة: google.accounts.id.prompt
تعرض الطريقة google.accounts.id.prompt طلب One Tap أو مدير بيانات الاعتماد المضمّن في المتصفّح بعد استدعاء الطريقة initialize().
اطّلِع على مثال الرمز التالي للطريقة:
google.accounts.id.prompt(/**
@type{(function(!PromptMomentNotification):void)=} */ momentListener)
عادةً، يتم استدعاء الطريقة prompt() عند تحميل الصفحة. بسبب حالة الجلسة وإعدادات المستخدم على جهة Google، قد لا تظهر واجهة مستخدم طلب One Tap. لتلقّي إشعارات بشأن حالة واجهة المستخدم في لحظات مختلفة، مرِّر دالة لتلقّي إشعارات بشأن حالة واجهة المستخدم.
يتم إرسال الإشعارات في اللحظات التالية:
- وقت العرض: يحدث ذلك بعد استدعاء الطريقة
prompt(). يحتوي الإشعار على قيمة منطقية لتحديد ما إذا كان سيتم عرض واجهة المستخدم أم لا. الخطوة التي تم تخطّيها: يحدث ذلك عندما يتم إغلاق طلب "نقرة واحدة" بسبب الإلغاء التلقائي أو الإلغاء اليدوي أو عندما يتعذّر على Google إصدار بيانات اعتماد، مثلاً عندما يتم تسجيل الخروج من Google في الجلسة المحدّدة.
في هذه الحالات، ننصحك بمواصلة عملية الربط مع مقدّمي خدمات تحديد الهوية الآخرين، إذا توفّروا.
لحظة الرفض: تحدث هذه الحالة عندما تستردّ Google بيانات اعتماد بنجاح أو عندما يريد المستخدم إيقاف عملية استرداد بيانات الاعتماد. على سبيل المثال، عندما يبدأ المستخدم في إدخال اسم المستخدم وكلمة المرور في مربّع حوار تسجيل الدخول، يمكنك استدعاء الطريقة
google.accounts.id.cancel()لإغلاق طلب One Tap وتفعيل لحظة الرفض.
يوضّح مثال الرمز البرمجي التالي كيفية تنفيذ اللحظة التي تم تخطّيها:
<script>
window.onload = function () {
google.accounts.id.initialize(...);
google.accounts.id.prompt((notification) => {
if (notification.isNotDisplayed() || notification.isSkippedMoment()) {
// continue with another identity provider.
}
});
};
</script>
نوع البيانات: PromptMomentNotification
يسرد الجدول التالي طرقًا وأوصافًا لنوع البيانات PromptMomentNotification:
| الطريقة | |
|---|---|
isDisplayMoment() |
هل هذا الإشعار مخصّص لعرض لحظة؟ ملاحظة: عندما تكون واجهة FedCM مفعّلة، لا يتم إطلاق هذا الإشعار. يمكنك الاطّلاع على صفحة الانتقال إلى FedCM للحصول على مزيد من المعلومات. |
isDisplayed() |
هل هذا الإشعار مخصّص لعرض لحظة، وهل تظهر واجهة المستخدم؟ ملاحظة: عندما تكون واجهة FedCM مفعّلة، لا يتم إطلاق هذا الإشعار. يمكنك الاطّلاع على صفحة الانتقال إلى FedCM للحصول على مزيد من المعلومات. |
isNotDisplayed() |
هل هذا الإشعار مخصّص للحظة عرض، ولم يتم عرض واجهة المستخدم؟ ملاحظة: عندما تكون واجهة FedCM مفعّلة، لا يتم إطلاق هذا الإشعار. يمكنك الاطّلاع على صفحة الانتقال إلى FedCM للحصول على مزيد من المعلومات. |
getNotDisplayedReason() |
السبب التفصيلي لعدم عرض واجهة المستخدم في ما يلي القيم المحتمَلة:
|
isSkippedMoment() |
هل هذا الإشعار مخصّص للحظة تم تخطّيها؟ |
getSkippedReason() |
السبب المفصّل لتخطّي اللحظة في ما يلي القيم المحتمَلة:
|
isDismissedMoment() |
هل هذا الإشعار خاص بلمحة تم رفضها؟ |
getDismissedReason() |
السبب المفصّل للرفض في ما يلي القيم المحتمَلة:
|
getMomentType() |
عرض سلسلة لنوع اللحظة في ما يلي القيم المحتمَلة:
|
نوع البيانات: CredentialResponse
عند استدعاء الدالة callback، يتم تمرير العنصر CredentialResponse كمعلَمة. يسرد الجدول التالي الحقول التي يتضمّنها عنصر الرد على بيانات الاعتماد:
| الحقل | |
|---|---|
credential |
رمز JWT المميّز المشفر الذي تصدره Google. |
select_by |
كيفية تسجيل المستخدم الدخول |
state |
لا يتم تحديد هذا الحقل إلا عندما ينقر المستخدم على زر "تسجيل الدخول باستخدام Google" لتسجيل الدخول، ويتم تحديد السمة state الخاصة بالزر. |
شهادة
هذا الحقل هو رمز التعريف كسلسلة JSON المميّزة للويب (JWT) بترميز base64.
عند فك ترميز JWT، سيظهر على النحو التالي:
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": "Elisa", "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_verfied صحيحة أيضًا لأنّ Google أثبتت في البداية ملكية المستخدم للحساب عند إنشاء حساب Google، ولكن قد تكون ملكية حساب البريد الإلكتروني التابع لجهة خارجية قد تغيّرت منذ ذلك الحين.
يعرض الحقل exp وقت انتهاء صلاحية الرمز المميز لإثبات ملكيته على
الخادم. تبلغ مدة صلاحية رمز التعريف المميز الذي يتم الحصول عليه من ميزة "تسجيل الدخول باستخدام حساب Google" ساعة واحدة. يجب تأكيد الرمز المميّز قبل انتهاء صلاحيته. لا تستخدِم exp لإدارة الجلسات. لا يعني انتهاء صلاحية رمز التعريف
أنّ المستخدم قد سجّل الخروج. يتحمّل تطبيقك مسؤولية إدارة جلسات المستخدمين.
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. |
itp |
مستخدم لديه جلسة حالية سبق له منح الموافقة، ثم ضغط على ميزة "النقرة الواحدة" في متصفّحات ITP |
itp_confirm |
ضغط مستخدم لديه جلسة حالية على زر "نقرة واحدة" في متصفّحات ITP، ثم ضغط على زر "تأكيد" لمنح الموافقة ومشاركة بيانات الاعتماد. |
itp_add_session |
ضغط مستخدم ليس لديه جلسة حالية وسبق له منح الموافقة على زر One Tap في المتصفّحات المتوافقة مع ITP لاختيار حساب Google ومشاركة بيانات الاعتماد. |
itp_confirm_add_session |
ضغط مستخدم ليس لديه جلسة حالية أولاً على One Tap في متصفّحات ITP لاختيار حساب Google، ثم ضغط على زر "تأكيد" للموافقة على مشاركة بيانات الاعتماد. |
btn |
ضغط مستخدم لديه جلسة حالية وسبق له منح الموافقة على الزر "تسجيل الدخول باستخدام حساب Google" واختار حسابًا على Google من "اختيار حساب" لمشاركة بيانات الاعتماد. |
btn_confirm |
ضغط مستخدم لديه جلسة حالية على زر "تسجيل الدخول باستخدام Google"، ثم ضغط على زر "تأكيد" لمنح الموافقة ومشاركة بيانات الاعتماد. |
btn_add_session |
ضغط مستخدم ليس لديه جلسة حالية وسبق له منح الموافقة على زر "تسجيل الدخول باستخدام حساب Google" لاختيار حساب Google ومشاركة بيانات الاعتماد. |
btn_confirm_add_session |
ضغط المستخدم الذي ليس لديه جلسة حالية أولاً على الزر "تسجيل الدخول باستخدام Google" لاختيار حساب Google، ثم ضغط على الزر "تأكيد" للموافقة على مشاركة بيانات الاعتماد. |
الولاية
لا يتم تحديد هذا الحقل إلا عندما ينقر المستخدم على زر "تسجيل الدخول باستخدام Google" لتسجيل الدخول، ويتم تحديد السمة state للزر الذي تم النقر عليه. قيمة هذا الحقل هي القيمة نفسها التي حدّدتها في السمة state الخاصة بالزر.
بما أنّه يمكن عرض أزرار متعدّدة لميزة "تسجيل الدخول باستخدام حساب Google" على الصفحة نفسها، يمكنك تعيين سلسلة فريدة لكل زر. وبالتالي، يمكنك استخدام حقل state هذا
لتحديد الزر الذي نقر عليه المستخدم لتسجيل الدخول.
الطريقة: google.accounts.id.renderButton
تعرض طريقة google.accounts.id.renderButton زر "تسجيل الدخول باستخدام حساب Google" في صفحات الويب.
اطّلِع على مثال الرمز التالي للطريقة:
google.accounts.id.renderButton(
/** @type{!HTMLElement} */ parent,
/** @type{!GsiButtonConfiguration} */ options
)
نوع البيانات: GsiButtonConfiguration
يسرد الجدول التالي الحقول وأوصاف نوع البيانات GsiButtonConfiguration:
| السمة | |
|---|---|
type |
نوع الزر: رمز أو زر عادي |
theme |
مظهر الزر على سبيل المثال، filled_blue أو filled_black. |
size |
حجم الزر على سبيل المثال، صغير أو كبير. |
text |
نص الزر على سبيل المثال، "تسجيل الدخول باستخدام حساب Google" أو "الاشتراك باستخدام حساب Google". |
shape |
شكل الزر على سبيل المثال، مستطيلة أو دائرية. |
logo_alignment |
محاذاة شعار Google: إلى اليسار أو الوسط |
width |
تمثّل هذه السمة عرض الزر بالبكسل. |
locale |
في حال ضبطها، يتم عرض لغة الزر. |
click_listener |
في حال ضبطها، يتم استدعاء هذه الدالة عند النقر على الزر "تسجيل الدخول باستخدام Google". |
state |
في حال ضبطها، يتم عرض هذه السلسلة مع رمز التعريف. |
أنواع السمات
تحتوي الأقسام التالية على تفاصيل حول نوع كل سمة ومثال عليها.
النوع
نوع الزر تكون القيمة التلقائية standard.
اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | نعم | type: "icon" |
يسرد الجدول التالي أنواع الأزرار المتاحة وأوصافها:
| النوع | |
|---|---|
standard |
|
icon |
|
مظهر
مظهر الزر تكون القيمة التلقائية outline. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | theme: "filled_blue" |
يسرد الجدول التالي النُسق المتاحة وأوصافها:
| المظهر | |
|---|---|
outline |
|
filled_blue |
|
filled_black |
|
الحجم
حجم الزر تكون القيمة التلقائية large. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | size: "small" |
يسرد الجدول التالي أحجام الأزرار المتاحة وأوصافها:
| الحجم | |
|---|---|
large |
|
medium |
|
small |
|
نص
نص الزر تكون القيمة التلقائية signin_with. لا توجد اختلافات مرئية في نص أزرار الرموز التي تتضمّن سمات text مختلفة.
الاستثناء الوحيد هو عندما تتم قراءة النص لتسهيل استخدام الشاشة.
اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | text: "signup_with" |
يسرد الجدول التالي جميع نصوص الأزرار المتاحة وأوصافها:
| نص | |
|---|---|
signin_with |
|
signup_with |
|
continue_with |
|
signin |
|
الشكل
شكل الزر تكون القيمة التلقائية rectangular. اطّلِع على الجدول التالي
لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | shape: "rectangular" |
يسرد الجدول التالي أشكال الأزرار المتاحة وأوصافها:
| الشكل | |
|---|---|
rectangular |
icon،
ستكون هي نفسها square.
|
pill |
icon، ستكون مماثلة للسمة circle.
|
circle |
standard،
ستكون هي نفسها pill.
|
square |
standard،
ستكون هي نفسها rectangular.
|
logo_alignment
محاذاة شعار Google تكون القيمة التلقائية left. لا تنطبق هذه السمة إلا على نوع الزر standard. اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | logo_alignment: "center" |
يسرد الجدول التالي عمليات المحاذاة المتاحة وأوصافها:
| logo_alignment | |
|---|---|
left |
|
center |
|
العرض
الحد الأدنى لعرض الزر، بالبكسل. الحد الأقصى للعرض هو 400 بكسل.
اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | width: "400" |
locale
اختيارية: عرض نص الزر باستخدام اللغة المحدّدة، وإلا سيتم استخدام اللغة التلقائية لحساب Google أو إعدادات المتصفّح. أضِف المَعلمة hl ورمز اللغة إلى التوجيه src عند تحميل المكتبة، على سبيل المثال:
gsi/client?hl=<iso-639-code>.
في حال عدم ضبطها، يتم استخدام اللغة التلقائية للمتصفّح أو اللغة المفضّلة للمستخدم في جلسة Google. لذلك، قد يرى المستخدمون المختلفون إصدارات مختلفة من الأزرار المترجمة، وربما بأحجام مختلفة.
اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | locale: "zh_CN" |
click_listener
يمكنك تحديد دالة JavaScript يتم استدعاؤها عند النقر على زر click_listener باستخدام السمة click_listener.
google.accounts.id.renderButton(document.getElementById("signinDiv"), { theme: 'outline', size: 'large', click_listener: onClickHandler }); function onClickHandler(){ console.log("Sign in with Google button clicked...") }
في هذا المثال، يتم تسجيل الرسالة تم النقر على زر "تسجيل الدخول باستخدام حساب Google"... في وحدة التحكّم عند النقر على زر "تسجيل الدخول باستخدام حساب Google".
الولاية
اختياري، بما أنّه يمكن عرض عدّة أزرار "تسجيل الدخول باستخدام Google" على الصفحة نفسها، يمكنك تخصيص سلسلة فريدة لكل زر. سيتم عرض السلسلة نفسها مع الرمز المميّز، ما يتيح لك تحديد الزر الذي نقر عليه المستخدم لتسجيل الدخول.
اطّلِع على الجدول التالي لمزيد من المعلومات:
| النوع | مطلوب | مثال |
|---|---|---|
| سلسلة | اختياري | data-state: "button 1" |
نوع البيانات: بيانات اعتماد
عند استدعاء دالة
native_callback، يتم تمرير عنصر Credential كمعلَمة. يسرد الجدول التالي الحقول التي يتضمّنها العنصر:
| الحقل | |
|---|---|
id |
تحدّد هوية المستخدم. |
password |
كلمة المرور |
الطريقة: google.accounts.id.disableAutoSelect
عندما يسجّل المستخدم الخروج من موقعك الإلكتروني، عليك استدعاء الطريقة
google.accounts.id.disableAutoSelect لتسجيل الحالة في ملفات تعريف الارتباط. يمنع ذلك حدوث حلقة مفرغة في تجربة المستخدم. اطّلِع على مقتطف الرمز التالي الخاص بالطريقة:
google.accounts.id.disableAutoSelect()
ينفّذ مثال الرمز البرمجي التالي طريقة google.accounts.id.disableAutoSelect باستخدام الدالة onSignout():
<script>
function onSignout() {
google.accounts.id.disableAutoSelect();
}
</script>
الطريقة: google.accounts.id.storeCredential
هذه الطريقة هي برنامج تضمين لطريقة store() في واجهة برمجة التطبيقات المضمّنة في المتصفّح لإدارة بيانات الاعتماد. لذلك، لا يمكن استخدامها إلا لتخزين بيانات اعتماد كلمة المرور. اطّلِع على مثال الرمز التالي للطريقة:
google.accounts.id.storeCredential(Credential, callback)
ينفّذ مثال الرمز البرمجي التالي طريقة google.accounts.id.storeCredential باستخدام الدالة onSignIn():
<script>
function onSignIn() {
let cred = {id: '...', password: '...'};
google.accounts.id.storeCredential(cred);
}
</script>
الطريقة: google.accounts.id.cancel
يمكنك إلغاء عملية One Tap إذا أزلت الطلب من نموذج المستند (DOM) الخاص بالجهة المعتمِدة. يتم تجاهل عملية الإلغاء إذا تم اختيار بيانات اعتماد من قبل. اطّلِع على مثال الرمز البرمجي التالي للطريقة:
google.accounts.id.cancel()
ينفّذ مثال الرمز البرمجي التالي طريقة google.accounts.id.cancel() باستخدام دالة onNextButtonClicked():
<script>
function onNextButtonClicked() {
google.accounts.id.cancel();
showPasswordPage();
}
</script>
دالة ردّ الاتصال عند تحميل المكتبة: onGoogleLibraryLoad
يمكنك تسجيل دالة ردّ الاتصال onGoogleLibraryLoad. يتم إرسال الإشعار بعد تحميل مكتبة JavaScript الخاصة بخدمة "تسجيل الدخول باستخدام Google":
window.onGoogleLibraryLoad = () => {
...
};
هذه الدالة هي مجرد اختصار للدالة window.onload. ولا تختلف طريقة عملها.
يوضّح مثال الرمز البرمجي التالي كيفية تنفيذ onGoogleLibraryLoad ردّ اتصال:
<script>
window.onGoogleLibraryLoad = () => {
google.accounts.id.initialize({
...
});
google.accounts.id.prompt();
};
</script>
الطريقة: google.accounts.id.revoke
يبطل الأسلوب google.accounts.id.revoke إذن OAuth المستخدَم لمشاركة الرمز المميز
لمعرّف المستخدم المحدّد. راجِع مقتطف الرمز التالي الخاص بالطريقة:
javascript
google.accounts.id.revoke(login_hint, callback)
| المَعلمة | النوع | الوصف |
|---|---|---|
login_hint |
سلسلة | عنوان البريد الإلكتروني أو المعرّف الفريد لحساب المستخدم على Google المعرّف هو السمة sub في حمولة بيانات الاعتماد. |
callback |
دالة | معالج RevocationResponse اختياري |
يوضّح نموذج الرمز البرمجي التالي كيفية استخدام طريقة revoke مع معرّف.
google.accounts.id.revoke('1618033988749895', done => {
console.log(done.error);
});نوع البيانات: RevocationResponse
عند استدعاء الدالة callback، يتم تمرير العنصر RevocationResponse كمعلَمة. يسرد الجدول التالي الحقول التي يتضمّنها عنصر رد الإبطال:
| الحقل | |
|---|---|
successful |
هذا الحقل هو القيمة المعروضة من استدعاء الطريقة. |
error |
يحتوي هذا الحقل اختياريًا على رسالة استجابة مفصّلة للخطأ. |
ناجح
هذا الحقل هو قيمة منطقية تم ضبطها على "صحيح" إذا نجح طلب طريقة الإبطال أو "خطأ" في حال حدوث خطأ.
خطأ
هذا الحقل هو قيمة سلسلة ويحتوي على رسالة خطأ مفصّلة في حال تعذّر تنفيذ استدعاء طريقة الإبطال، ويكون غير محدّد في حال النجاح.