تسجيل الدخول باستخدام مرجع واجهة برمجة تطبيقات 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 مرة واحدة فقط حتى إذا كنت تستخدم وحدات متعددة (مثل "النقرة الواحدة" والزر المخصّص والإبطال وما إلى ذلك) في صفحة الويب نفسها.
  • في حال استدعاء طريقة 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.
enable_redirect_uri_validation فعِّل مسار إعادة التوجيه للزر الذي يتوافق مع قواعد التحقّق من معرّف الموارد المنتظم (URI) لإعادة التوجيه.

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، ويجب أن تكون متوافقة مع قواعد التحقّق من معرّف الموارد المنتظم (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

يحدِّد هذا الحقل ما إذا كان سيتم إلغاء طلب "النقرة الواحدة" أم لا إذا نقر المستخدم خارج الطلب. تكون القيمة التلقائية 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: "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 الوسيط. ولا يؤثّر ذلك إلا في إطار 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

enable_redirect_uri_validation

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

النوع مطلوب مثال
قيمة منطقية اختياري enable_redirect_uri_validation: 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 ولا تتم إعادة استخدامه أبدًا. لا تستخدِم عنوان البريد الإلكتروني كمعرّف لأنّه يمكن أن يتضمّن حساب 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 تسجيل دخول تلقائي لمستخدم لديه جلسة حالية سبق له الموافقة على مشاركة بيانات الاعتماد لا ينطبق إلا على المتصفّحات غير المتوافقة مع FedCM.
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 ، ولا يتم تحديده في حال نجاح الاستدعاء.