يبدأ إيقاف ملفات تعريف الارتباط التابعة لجهات خارجية في Chrome في الربع الأول من عام 2024. اتّبِع دليل نقل البيانات لمراجعة التغييرات المحتمَلة وتجنُّب التأثيرات السلبية على تسجيل دخول المستخدمين إلى موقعك الإلكتروني.

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

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

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

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

تُجري الطريقة 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 وزر "تسجيل الدخول باستخدام حساب Google" `popup` في وضع تجربة المستخدم.
`login_uri`	عنوان URL لنقطة نهاية تسجيل الدخول. زر "تسجيل الدخول باستخدام حساب Google" `redirect` يستخدم وضع "تجربة المستخدم" هذه السمة.
`native_callback`	دالة JavaScript التي تعالج بيانات اعتماد كلمة المرور.
`cancel_on_tap_outside`	يلغِ الطلب إذا نقر المستخدم خارج الطلب.
`prompt_parent_id`	رقم تعريف DOM لعنصر حاوية طلب ميزة "نقرة واحدة"
`nonce`	سلسلة عشوائية للرموز المميّزة لرقم التعريف
`context`	العنوان والكلمات في رسالة "نقرة واحدة"
`state_cookie_domain`	إذا كنت تحتاج إلى طلب "نقرة واحدة" في النطاق الرئيسي ونطاقاته الفرعية، أدخِل النطاق الرئيسي إلى هذا الحقل بحيث يتم استخدام ملف تعريف ارتباط واحد مشترَك.
`ux_mode`	تدفق تجربة المستخدم لزرّ "تسجيل الدخول باستخدام حساب Google"
`allowed_parent_origin`	المصادر التي يُسمح لها بتضمين إطار iframe المتوسط. يتم تشغيل ميزة "نقرة واحدة" في وضع iframe المتوسط في حال توفُّر هذا الحقل.
`intermediate_iframe_close_callback`	تلغي هذه العلامة سلوك "إطار iframe المتوسط" التلقائي عندما يغلق المستخدمون "نقرة واحدة" يدويًا.
`itp_support`	يؤدي هذا الخيار إلى تفعيل ميزة One Tap UX التي تمت ترقيتها على متصفّحات بروتوكول ITP.
`login_hint`	يمكنك تخطّي اختيار الحساب من خلال تقديم تلميح للمستخدم.
`hd`	تحديد الحسابات حسب النطاق
`use_fedcm_for_prompt`	يمكنك السماح للمتصفّح بالتحكّم في طلبات تسجيل الدخول للمستخدمين والتوسط في عملية تسجيل الدخول بين موقعك الإلكتروني وGoogle.

client_id

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

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

auto_select

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

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

معاودة الاتصال

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

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

login_uri

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

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

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

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

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

النوع	اختياري	مثال
عنوان URL	يتم ضبط عنوان URL تلقائيًا على عنوان URI للصفحة الحالية، أو القيمة التي تحددها. لا تُستخدم هذه السياسة إلا عند ضبط `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

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

النوع	مطلوبة	مثال
boolean	اختياري	`cancel_on_tap_outside: false`

prompt_parent_id

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

النوع	مطلوبة	مثال
سلسلة	اختياري	`prompt_parent_id: 'parent_id'`

رقم خاص

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

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

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

سياق

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

النوع	مطلوبة	مثال
سلسلة	اختياري	`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`	معرّف موارد منتظم (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 المتوسط وتتوقّف.

intermediate_iframe_close_callback

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

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

النوع	مطلوبة	مثال
الوظيفة	اختياري	`intermediate_iframe_close_callback: logBeforeClose`

itp_support

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

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

login_hint

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

لمزيد من المعلومات، اطّلِع على الحقل login_hint في وثائق OpenID Connect.

النوع	مطلوبة	مثال
سلسلة أو عنوان بريد إلكتروني أو القيمة من حقل `sub` للرمز المميّز للمعرّف.	اختياري	`login_hint: 'elisa.beckett@gmail.com'`

جودة عالية الدقة

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

لمزيد من المعلومات، اطلع على الحقل دقة عالية في وثائق OpenID Connect.

النوع	مطلوبة	مثال
سلسلة. اسم مجال مؤهل بالكامل أو *.	اختياري	`hd: '*'`

use_fedcm_for_prompt

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

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

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

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

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

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

يتم تنشيط الإشعارات في اللحظات التالية:

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

في هذه الحالات، ننصحك بالمتابعة إلى موفّري الهوية القادمين، إن وُجدوا.
لحظة الرفض: تحدث عندما تسترد Google بيانات اعتماد بنجاح أو عندما يريد المستخدم إيقاف تدفق استرداد بيانات الاعتماد. على سبيل المثال، عندما يبدأ المستخدم في إدخال اسم المستخدم وكلمة المرور في مربّع حوار تسجيل الدخول، يمكنك استدعاء طريقة google.accounts.id.cancel() لإغلاق طلب "نقرة واحدة" وتشغيل لحظة للرفض.

تحذير: في هذه الحالة، لا تجرِّب أيًا من موفِّري الهوية الآخرين.

في ما يلي مثال الرمز البرمجي لتنفيذ اللحظة التي تم تخطيها:

<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 ولا تتم إعادة استخدامه أبدًا. لا تستخدم عنوان البريد الإلكتروني كمعرِّف لأنّه يمكن أن يتضمّن حساب Google عدة عناوين بريد إلكتروني في نقاط زمنية مختلفة.

باستخدام الحقول email وemail_verified وhd، يمكنك تحديد ما إذا كان محرّك بحث Google يستضيف عنوان بريد إلكتروني وأنّه موثوق أم لا. في الحالات التي تحصل فيها 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`	تسجيل الدخول التلقائي لمستخدم لديه جلسة حالية سبق له منح الموافقة على مشاركة بيانات الاعتماد لا ينطبق هذا الإعداد إلا على المتصفِّحات غير المتوافقة مع "المراسلة عبر السحابة الإلكترونية من Firebase".
`user`	هناك مستخدم لديه جلسة حالية سبق له منح الموافقة بالضغط على الزر "متابعة باسم" بنقرة واحدة لمشاركة بيانات الاعتماد. لا ينطبق إلا على المتصفِّحات غير المتوافقة مع "المراسلة عبر السحابة الإلكترونية من Firebase".
`fedcm`	ضغط أحد المستخدمين على الزر "متابعة باسم" بنقرة واحدة لمشاركة بيانات الاعتماد باستخدام خدمة FedCM. ينطبق ذلك فقط على المتصفحات المتوافقة مع FedCM.
`fedcm_auto`	تسجيل الدخول التلقائي لمستخدم لديه جلسة حالية سبق له منح الموافقة على مشاركة بيانات الاعتماد باستخدام ميزة FedCM One Tap ينطبق ذلك فقط على المتصفحات المتوافقة مع 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، ثم ضغط على الزر "تأكيد" للموافقة ومشاركة بيانات الاعتماد.

state

يتم تحديد هذا الحقل فقط عندما ينقر المستخدم على زر "تسجيل الدخول باستخدام حساب 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`	زر صغير.

text

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

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

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

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

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

shape

شكل الزر. تكون القيمة التلقائية 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. لذلك، قد يرى مستخدمون مختلفون إصدارات مختلفة من الأزرار المترجَمة، وربما بأحجام مختلفة.

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

النوع	مطلوبة	مثال
سلسلة	اختياري	`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".

state

اختياري، نظرًا لإمكانية عرض أزرار "تسجيل الدخول باستخدام حساب 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

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

ناجحة

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

خطأ

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