سيتم نقل "خدمات هوية Google" إلى واجهات برمجة تطبيقات FedCM. يُرجى اتّباع دليل نقل البيانات لمراجعة التغييرات المحتملة وتجنُّب التأثيرات السلبية على تسجيل دخول المستخدمين إلى موقعك الإلكتروني.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

توضّح صفحة المرجع هذه واجهة برمجة التطبيقات 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 مرة واحدة فقط حتى إذا كنت تستخدم وحدات متعددة (مثل One Tap و"الزر المخصّص" والإبطال وما إلى ذلك) في صفحة الويب نفسها.
في حال استدعاء طريقة google.accounts.id.initialize عدة مرات، يتم تذكُّر الإعدادات في آخر استدعاء واستخدامها فقط.

تتم إعادة ضبط الإعدادات عند استدعاء google.accounts.id.initialize، وتستخدِم جميع الطرق اللاحقة في صفحة الويب نفسها الإعدادات الجديدة على الفور.

نوع البيانات: IdConfiguration

يسرد الجدول التالي الحقول والأوصاف لنوع البيانات IdConfiguration:

الحقل
`client_id`	معرّف العميل لتطبيقك
`auto_select`	تفعيل الاختيار التلقائي
`callback`	دالة JavaScript التي تعالج الرموز المميّزة للتعريف تستخدم ميزة "نقرة واحدة" من Google ووضع تجربة المستخدم لزر "تسجيل الدخول باستخدام حساب Google"`popup` هذه السمة.
`login_uri`	عنوان URL لنقطة نهاية تسجيل الدخول. زر "تسجيل الدخول باستخدام حساب Google" يستخدم وضع تجربة المستخدم `redirect` هذه السمة.
`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 الوسيط يتم تشغيل ميزة "النقرة الواحدة" في وضع iframe الوسيط إذا كان هذا الحقل متوفّرًا.
`intermediate_iframe_close_callback`	تلغي الإعدادات التلقائية لإطار iframe المؤقت عندما يغلق المستخدمون ميزة "النقرة الواحدة" يدويًا.
`itp_support`	تفعيل تجربة One Tap المحسّنة على متصفّحات ITP
`login_hint`	يمكنك تخطّي اختيار الحساب من خلال تقديم تلميح للمستخدم.
`hd`	حصر اختيار الحساب حسب النطاق
`use_fedcm_for_prompt`	اسمح للمتصفّح بالتحكّم في طلبات تسجيل دخول المستخدمين والتوسّط في عملية تسجيل الولوج بين موقعك الإلكتروني وGoogle.

client_id

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

النوع	مطلوب	مثال
سلسلة	نعم	`client_id: "CLIENT_ID.apps.googleusercontent.com"`

auto_select

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

النوع	مطلوب	مثال
قيمة منطقية	اختياري	`auto_select: true`

ردّ الاتصال

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

النوع	مطلوب	مثال
دالة	مطلوب لميزة "النقرة الواحدة" ووضع تجربة المستخدم `popup`	`callback: handleResponse`

login_uri

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

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

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

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

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

النوع	اختياري	مثال
عنوان URL	الإعداد التلقائي هو معرّف الموارد المنتظم للصفحة الحالية أو القيمة التي تحدّدها. لا يتم استخدام هذا الحقل إلا عند ضبط `ux_mode: "redirect"`.	`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

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 للمتصفّح والخادم الفردي.

سياق

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

النوع	مطلوب	مثال
سلسلة	اختياري	`context: "use"`

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

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

state_cookie_domain

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

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

ux_mode

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

النوع	مطلوب	مثال
سلسلة	اختياري	`ux_mode: "redirect"`

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

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

allowed_parent_origin

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

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

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

أنواع القيم
`string`	معرّف موارد منتظم لنطاق واحد	`"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 الوسيط في ميزة "النقرة الواحدة" وسيتوقف.

intermediate_iframe_close_callback

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

لا يسري حقل intermediate_iframe_close_callback إلا في وضع ملف iframe intermediate. ولا يؤثّر ذلك إلا في إطار 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. القيمة التلقائية هي false. يُرجى الاطّلاع على صفحة نقل البيانات إلى FedCM لمزيد من المعلومات.

النوع	مطلوب	مثال
قيمة منطقية	اختياري	`use_fedcm_for_prompt: true`

الطريقة: google.accounts.id.prompt

تعرِض الطريقة google.accounts.id.prompt طلب One Tap أو مدير بيانات الاعتماد الأصلي للمتصفّح بعد استدعاء الطريقة initialize(). اطّلِع على مثال الرمز البرمجي التالي للطريقة:

 google.accounts.id.prompt(/**
 @type{(function(!PromptMomentNotification):void)=} */ momentListener)

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

يتم عرض الإشعارات في الحالات التالية:

عرض اللحظة: يحدث ذلك بعد استدعاء الطريقة prompt(). يحتوي الإشعار على قيمة منطقية للإشارة إلى ما إذا كان واجهة المستخدم معروضة أم لا.
لحظة تم تخطّيها: يحدث ذلك عندما يتم إغلاق طلب One Tap من خلال إغلاق تلقائي أو إغلاق يدوي، أو عندما يتعذّر على Google إصدار بيانات اعتماد، مثلاً عندما يتم تسجيل الخروج من Google في الجلسة المحدّدة.

في هذه الحالات، ننصحك بالانتقال إلى مقدّمي خدمات هوية الآخرين، إن توفّروا.
لحظة تم إغلاقها: يحدث ذلك عندما تسترجع Google بيانات اعتماد بنجاح أو عندما يريد المستخدم إيقاف عملية استرداد بيانات الاعتماد. على سبيل المثال، عندما يبدأ المستخدم في إدخال اسم المستخدم وكلمة المرور في مربع diálogo تسجيل الدخول، يمكنك استدعاء طريقة 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()`	السبب التفصيلي لعدم ظهور واجهة المستخدم في ما يلي القيم المحتمَلة: `browser_not_supported` `invalid_client` `missing_client_id` `opt_out_or_no_session` `secure_http_required` `suppressed_by_user` `unregistered_origin` `unknown_reason` ملاحظة: لا تتوفّر هذه الطريقة عند فعالية FedCM . يمكنك الاطّلاع على صفحة نقل البيانات إلى FedCM للحصول على مزيد من المعلومات.
`isSkippedMoment()`	هل هذا الإشعار بشأن لحظة تم تخطّيها؟
`getSkippedReason()`	السبب المفصّل للّحظة التي تم تخطّيها في ما يلي القيم المحتمَلة: `auto_cancel` `user_cancel` `tap_outside` `issuing_failed` ملاحظة: لا تتوفّر هذه الطريقة عند فعالية FedCM . يمكنك الاطّلاع على صفحة نقل البيانات إلى FedCM للحصول على مزيد من المعلومات.
`isDismissedMoment()`	هل هذا الإشعار خاص بلمحة تم إغلاقها؟
`getDismissedReason()`	السبب المفصّل لرفض الطلب في ما يلي القيم المحتمَلة: `credential_returned` `cancel_called` `flow_restarted`
`getMomentType()`	عرض سلسلة لنوع الذكرى في ما يلي القيم المحتمَلة: `display` `skipped` `dismissed`

نوع البيانات: CredentialResponse

عند استدعاء الدالة callback، يتم تمرير عنصر CredentialResponse كمَعلمة. يسرد الجدول التالي الحقول المضمّنة في عنصر استجابة بيانات الاعتماد:

الحقل
`credential`	هذا الحقل هو الرمز المميّز للمعرّف الذي تم إرجاعه.
`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 جهة موثوقة:

إذا كان email يحتوي على اللاحقة @gmail.com، هذا يعني أنّه حساب Gmail.
إذا كان 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`	تسجيل الدخول تلقائيًا لمستخدم لديه جلسة حالية سبق له الموافقة على مشاركة بيانات الاعتماد لا ينطبق إلا على المتصفّحات غير المتوافقة مع "إدارة المحتوى في المقاييس".
`user`	مستخدم لديه جلسة حالية سبق أن منح الموافقة على النقر على الزر "متابعة باسم المستخدم نفسه" في ميزة "النقرة الواحدة" لمشاركة بيانات الاعتماد لا ينطبق هذا الإعداد إلا على المتصفّحات غير المتوافقة مع "إدارة المحتوى في المقاييس".
`fedcm`	ضغط مستخدم على زر "متابعة باسم" في ميزة "النقرة الواحدة" لمشاركة بيانات الاعتماد باستخدام FedCM. لا ينطبق ذلك إلا على المتصفّحات المتوافقة مع FedCM.
`fedcm_auto`	تسجيل دخول تلقائي لمستخدم لديه جلسة حالية سبق له أن منح الموافقة على مشاركة بيانات الاعتماد باستخدام ميزة "النقرة الواحدة" في FedCM لا ينطبق ذلك إلا على المتصفّحات المتوافقة مع FedCM.
`user_1tap`	ضغط مستخدم لديه جلسة حالية على الزر "متابعة باستخدام نفس البيانات" في ميزة "النقرة الواحدة" لمنح الموافقة ومشاركة بيانات الاعتماد. لا ينطبق هذا الإعداد إلا على الإصدار 75 من Chrome والإصدارات الأحدث.
`user_2tap`	ضغط مستخدم ليس لديه جلسة حالية على زر "متابعة باستخدام" في ميزة "النقرة الواحدة" لاختيار حساب، ثم ضغط على زر التأكيد في النافذة المنبثقة لمنح الموافقة ومشاركة بيانات الاعتماد. ينطبق ذلك على المتصفّحات غير المستندة إلى Chromium.
`itp`	مستخدم لديه جلسة حالية منحت الموافقة سابقًا الضغط على ميزة "النقرة الواحدة" في متصفّحات ITP
`itp_confirm`	ضغط مستخدم لديه جلسة حالية على ميزة "نقرة واحدة" في متصفحات ITP، ثم ضغط على زر التأكيد لمنح الموافقة ومشاركة بيانات الاعتماد.
`itp_add_session`	مستخدم ليس لديه جلسة حالية وقد منح الموافقة سابقًا الضغط على ميزة "النقرة الواحدة" في متصفّحات ITP لاختيار حساب Google ومشاركة بيانات الاعتماد
`itp_confirm_add_session`	إذا لم يكن لدى المستخدم جلسة حالية، يضغط أولاً على ميزة "النقرة الواحدة" في متصفحات 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`	نص الزر هو "تسجيل الدخول باستخدام حساب Google".
`signup_with`	نص الزر هو "الاشتراك باستخدام حساب Google".
`continue_with`	نص الزرّ هو "متابعة باستخدام حساب Google".
`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`	محاذاة شعار Google على يمين الصفحة
`center`	محاذاة شعار Google في الوسط

العرض

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

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

النوع	مطلوب	مثال
سلسلة	اختياري	`width: "400"`

locale

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

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

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

النوع	مطلوب	مثال
سلسلة	اختياري	`locale: "zh_CN"`

click_listener

يمكنك تحديد دالة JavaScript ليتمّ استدعاؤها عند النقر على الزر "تسجيل الدخول باستخدام حساب Google" باستخدام السمة 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 المستخدَمة لمشاركة رمز تمييز IDE للمستخدم المحدّد. راجِع مقتطف الرمز التالي للطريقة: 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`	يحتوي هذا الحقل اختياريًا على رسالة استجابة مفصلة للخطأ.

ناجحة

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

خطأ

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