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

تصف هذه الصفحة المرجعية واجهة برمجة تطبيقات JavaScript لتسجيل الدخول. يمكنك استخدام واجهة برمجة التطبيقات هذه لعرض إشعار "نقرة واحدة" أو زر "تسجيل الدخول باستخدام حساب 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 One" وزر "تسجيل الدخول باستخدام حساب 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 Developers Console. اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

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

auto_select

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

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

رد الاتصال

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

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

login_uri

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

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

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

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

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

النوع اختياري مثال
عنوان 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 التي تعالج بيانات اعتماد كلمة المرور التي يتم عرضها من مدير بيانات الاعتماد الأصلي للمتصفّح. راجِع الجدول التالي لمزيد من المعلومات:

النوع مطلوبة مثال
function اختياري 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: "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 المتوسط التلقائي عند إغلاق المستخدمين لتطبيق One Tap يدويًا من خلال النقر على الزر "X" في واجهة المستخدم بنقرة واحدة. يتمثل السلوك الافتراضي في إزالة إطار iframe المتوسط من DOM على الفور.

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

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

itp_support

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

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

login_hint

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

لمزيد من المعلومات، اطّلع على الحقل 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.
isSkippedMoment() هل هذا الإشعار مخصص للحظة تم تخطيها؟
getSkippedReason()

السبب التفصيلي لللحظة التي تم تخطّيها. وفي ما يلي القيم المحتمَلة:

  • auto_cancel
  • user_cancel
  • tap_outside
  • issuing_failed
ملاحظة: عندما تكون هذه الميزة مفعّلة، لا تكون هذه الطريقة متاحة. لمزيد من المعلومات، يمكنك الاطّلاع على صفحة نقل البيانات إلى برنامج FedCM.
isDismissedMoment() هل هذا الإشعار مخصّص للحظة التي تم تجاهلها؟
getDismissedReason()

السبب التفصيلي للرفض. وفي ما يلي القيم المحتمَلة:

  • credential_returned
  • cancel_called
  • flow_restarted
getMomentType()

عرض سلسلة لنوع اللحظة. وفي ما يلي القيم المحتمَلة:

  • display
  • skipped
  • dismissed

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

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

الحقل
credential هذا الحقل هو الرمز المميّز للمعرّف الذي تم عرضه.
select_by يحدِّد هذا الحقل كيفية اختيار بيانات الاعتماد.

بيانات اعتماد

هذا الحقل هو الرمز المميّز للمعرّف كسلسلة رمز 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 تسجيل الدخول التلقائي لمستخدم له جلسة حالية وافق سابقًا على مشاركة بيانات الاعتماد معها.
user هناك مستخدم لديه جلسة حالية سبق له منح الموافقة ضغط على الزر "متابعة باسم" بنقرة واحدة لمشاركة بيانات الاعتماد.
user_1tap ضغط أحد المستخدمين الذين لديهم جلسة حالية على الزر "متابعة باسم" بنقرة واحدة لمنح الموافقة ومشاركة بيانات الاعتماد. لا ينطبق هذا الإعداد سوى على الإصدار 75 من Chrome والإصدارات الأحدث.
user_2tap ضغط مستخدم ليس لديه جلسة حالية على الزر "متابعة باسم" بنقرة واحدة لاختيار حساب، ثم ضغط على زر "التأكيد" في نافذة منبثقة لمنح الموافقة ومشاركة بيانات الاعتماد. ينطبق ذلك على المتصفحات التي لا تستند إلى Chromium.
btn وقد ضغط أحد المستخدمين، الذي لديه جلسة حالية، والذي سبق أن منح موافقته، على زر "تسجيل الدخول باستخدام حساب Google" واختار "حساب Google" من الخيار "اختيار حساب" لمشاركة بيانات الاعتماد.
btn_confirm ضغط أحد المستخدمين الذين لديهم جلسة حالية على زر "تسجيل الدخول باستخدام حساب Google" وضغط على زر "التأكيد" لمنح الموافقة ومشاركة بيانات الاعتماد.
btn_add_session هناك مستخدم لم يحصل على جلسة حالية وسبق له منح الموافقة ضغط على زر "تسجيل الدخول باستخدام حساب Google" لاختيار حساب Google ومشاركة بيانات الاعتماد.
btn_confirm_add_session ضغط أولاً مستخدم ليس لديه جلسة حالية على زر "تسجيل الدخول باستخدام حساب Google" لاختيار حساب على Google، ثم ضغط على زر "التأكيد" للموافقة على بيانات الاعتماد ومشاركتها.

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

تعرض الطريقة google.accounts.id.renderButton زر "تسجيل الدخول باستخدام حساب Google" في صفحاتك على الويب.

اطّلِع على مثال الرمز التالي للطريقة:

google.accounts.id.renderButton(
      /** @type{!HTMLElement} */ parent,
      /** @type{!GsiButtonConfiguration} */ options
    )

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

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

السمة
type نوع الزر: أيقونة أو الزر العادي.
theme مظهر الزر على سبيل المثال، fill_blue أو filled_black.
size حجم الزر. على سبيل المثال، صغيرة أو كبيرة.
text نص الزر. على سبيل المثال، "تسجيل الدخول باستخدام حساب Google" أو "الاشتراك باستخدام حساب Google".
shape شكل الزرّ. على سبيل المثال، مستطيلة أو دائرية.
logo_alignment محاذاة شعار Google: لليسار أو الوسط.
width عرض الزر بوحدة البكسل.
locale وفي حال ضبطها، سيتم عرض لغة الزر.
click_listener وفي حال ضبط هذه السياسة، يتم استدعاء هذه الوظيفة عند النقر على زر "تسجيل الدخول باستخدام حساب Google".

أنواع السمات

تحتوي الأقسام التالية على تفاصيل حول نوع كل سمة ومثال.

كتابة

نوع الزر. ستكون القيمة التلقائية standard.

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

النوع مطلوبة مثال
سلسلة نعم type: "icon"

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

النوع
standard
زر يحتوي على نص أو معلومات شخصية.
icon
زر رمز بدون نص.

مظهر

مظهر الزر ستكون القيمة التلقائية outline. راجع الجدول التالي للحصول على مزيد من المعلومات:

النوع مطلوبة مثال
سلسلة اختياري theme: "filled_blue"

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

المظهر
outline
مظهر للزر العادي.
filled_blue
مظهر لزر باللون الأزرق.
filled_black
مظهر زر أسود اللون.

size

حجم الزر. ستكون القيمة التلقائية 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 إلى الوسط.

width

الحد الأدنى لعرض الزر بالبكسل. الحد الأقصى للعرض هو 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".

نوع البيانات: بيانات الاعتماد

عند استدعاء دالة 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 function معالج RevocationResponse الاختياري

يعرض الرمز النموذجي التالي كيفية استخدام طريقة revoke مع رقم تعريف.

  google.accounts.id.revoke('1618033988749895', done => {
    console.log(done.error);
  });

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

عند استدعاء دالة callback، يتم تمرير كائن RevocationResponse كمَعلمة. يسرد الجدول التالي الحقول الموجودة في كائن الاستجابة الإبطال:

الحقل
successful هذا الحقل هو القيمة المعروضة لاستدعاء الطريقة.
error يحتوي هذا الحقل اختياريًا على رسالة تفصيلية للاستجابة للخطأ.

ناجحة

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

خطأ

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