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

client_id

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

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

تحديد_تلقائي

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

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

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

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

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

تسجيل الدخول

هذه السمة هي معرّف الموارد المنتظم (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: handleResponse

إلغاء_عند_النقر_بالخارج

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

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

رسالة_تعريف_أحد_الآباء

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

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

رقم خاص

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

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

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

سياق

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

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

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

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

نطاق_ملفات تعريف الارتباط

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

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

وضع_ux

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

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

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

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

مسموح_بمصدر_الأم

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

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

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

أنواع القيم
string	عنوان URL مفرد للنطاق.	"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 الوسيط وإيقافه.

الوسيط_iframe_close_callback

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

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

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

دعم تكنولوجيا المعلومات

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

النوع	مطلوب	مثال
منطقي	اختياري	itp_support: 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()	هل هذا الإشعار لحظة عرض؟
isDisplayed()	هل هذا الإشعار للحظة المعروضة، ويتم عرض واجهة المستخدم؟
isNotDisplayed()	هل هذا الإشعار للحظة المعروضة، ولا يتم عرض واجهة المستخدم؟
getNotDisplayedReason()	السبب التفصيلي لعدم عرض واجهة المستخدم. في ما يلي القيم المحتملة: browser_not_supported invalid_client missing_client_id opt_out_or_no_session secure_http_required suppressed_by_user unregistered_origin unknown_reason
isSkippedMoment()	هل تم تخطي هذا الإشعار؟
getSkippedReason()	السبب التفصيلي للحظة التي تم تخطيها. في ما يلي القيم المحتملة: auto_cancel user_cancel tap_outside issuing_failed
isDismissedMoment()	هل تم تجاهل هذا الإشعار؟
getDismissedReason()	السبب التفصيلي للرفض. في ما يلي القيم المحتملة: credential_returned cancel_called flow_restarted
getMomentType()	عرض سلسلة لنوع اللحظة. في ما يلي القيم المحتملة: display skipped dismissed

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

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

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

شهادة

هذا الحقل هو الرمز المميز للمعرف كسلسلة JSON Web Token (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.

وباستخدام الحقول email وemail_verified وhd، يمكنك تحديد ما إذا كانت Google تستضيف عنوان بريد إلكتروني وموثوقًا به. في الحالات التي تكون فيها Google موثوقة، يُعرف المستخدم حاليًا بأنه المالك الشرعي للحساب.

الحالات التي تكون فيها Google موثوقة:

• لدى email لاحقة @gmail.com، وهذا هو حساب Gmail.
• email_verified صحيح وتم ضبط hd، هذا حساب G Suite.

يمكن للمستخدمين التسجيل في حسابات Google بدون استخدام Gmail أو G Suite. في حال عدم احتواء email على لاحقة @gmail.com وغياب hd، لا تكون Google مصدَّق عليها ويُنصح باستخدام كلمة مرور أو طرق اختبار أخرى للتحقق من المستخدم. يمكن أن يكون email_verfied صحيحًا أيضًا لأن Google تحقّقت من المستخدم في البداية عند إنشاء حساب Google، ولكن من المحتمل أن تكون ملكية حساب البريد الإلكتروني التابع لجهة خارجية قد تغيّرت منذ ذلك الحين.

تحديد_بواسطة

يسرد الجدول التالي القيم المحتملة للحقل select_by. ويُستخدم نوع الزر المستخدَم مع الجلسة وحالة الموافقة لتعيين القيمة،

• ضغط المستخدم على زر "نقرة واحدة" أو زر "تسجيل الدخول باستخدام حساب Google" أو استخدم عملية تسجيل الدخول التلقائي بدون تلامس.

• تم العثور على جلسة حالية، أو تم اختيار المستخدم وتسجيل الدخول إلى حساب Google لإنشاء جلسة جديدة.

• قبل مشاركة بيانات اعتماد الرمز المميّز للرقم التعريفي مع تطبيقك، يمكن للمستخدم أيضًا

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

يتم تعيين قيمة هذا الحقل على أحد هذه الأنواع،

القيمة	الوصف
auto	تسجيل الدخول التلقائي لمستخدم لديه جلسة حالية سبق له منح موافقته على مشاركة بيانات الاعتماد.
user	ضغط مستخدم لديه جلسة حالية سبق له منح الموافقة على الزر "متابعة باسم" بنقرة واحدة لمشاركة بيانات الاعتماد.
user_1tap	ضغط مستخدم يملك جلسة حالية على الزر "متابعة باسم" بنقرة واحدة لمنح الموافقة ومشاركة بيانات الاعتماد. ينطبق هذا الإعداد فقط على الإصدار 75 والإصدارات الأحدث من Chrome.
user_2tap	ضغط مستخدم بدون جلسة حالية على الزر One 'Continue as' (اختيار باسم) لاختيار حساب ثم ضغط على الزر "تأكيد" في نافذة منبثقة لمنح الموافقة ومشاركة بيانات الاعتماد. ينطبق ذلك على المتصفِّحات غير المستندة إلى 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 أو fill_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	زر صغير:

ملف نصي

نص الزر. القيمة التلقائية هي 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.

محاذاة_الشعار

محاذاة شعار Google. القيمة التلقائية هي left. تنطبق هذه السمة على نوع الزر standard فقط. اطلِع على الجدول التالي للحصول على مزيد من المعلومات:

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

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

محاذاة_الشعار
left	محاذاة إلى اليمين شعار Google.
center	محاذاة شعار Google إلى الوسط.

width

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

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

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

locale

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

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

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

مستمع قائمة النقرات

يمكنك تحديد دالة 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. يتم إرسال إشعار إليه بعد تحميل مكتبة "تسجيل الدخول باستخدام Google JavaScript":

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 المستخدمة لمشاركة الرمز المميز لرقم التعريف للمستخدم المُحدّد. اطّلع على مقتطف الرمز التالي للطريقة: google.accounts.id.revoke(hint, callback)

المعلمة	النوع	الوصف
hint	سلسلة	عنوان البريد الإلكتروني أو المعرّف الفريد لحساب المستخدم على Google. المعرّف هو السمة sub لحمولة بيانات الاعتماد.
callback	الدالة	معالج RevocationResponse الاختياري.

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

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

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

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

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

ناجحة

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

خطأ

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