تصف هذه الصفحة المرجعية واجهة برمجة تطبيقات 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 |
تفعيل ميزة "تجربة المستخدم بنقرة واحدة" التي تمت ترقيتها على متصفِّحات ITP |
login_hint |
تخطي اختيار الحساب من خلال تقديم تلميح للمستخدم. |
hd |
حصر اختيار الحسابات حسب النطاق |
use_fedcm_for_prompt |
السماح للمتصفّح بالتحكّم في طلبات تسجيل الدخول الخاصة بالمستخدمين والتوسّط في عملية تسجيل الدخول بين موقعك الإلكتروني وGoogle |
client_id
هذا الحقل هو معرّف العميل لتطبيقك، ويتم العثور عليه وإنشاؤه في Google Developers Console. اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:
النوع | حقل مطلوب | مثال |
---|---|---|
سلسلة | نعم | client_id: "CLIENT_ID.apps.googleusercontent.com" |
اختيار تلقائي
يحدّد هذا الحقل ما إذا كان سيتم عرض الرمز المميّز للمعرّف تلقائيًا بدون أي تفاعل من جانب المستخدم عندما تكون هناك جلسة واحدة فقط في Google وافقت على تطبيقك من قبل. ستكون القيمة التلقائية false
. انظر الجدول التالي للحصول على مزيد من المعلومات:
النوع | حقل مطلوب | مثال |
---|---|---|
منطقية | إجراء اختياري | 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
الاتصال_الأصلي
هذا الحقل هو اسم وظيفة JavaScript التي تتعامل مع بيانات اعتماد كلمة المرور التي يتم عرضها من مدير بيانات الاعتماد الأصلي للمتصفح. راجِع الجدول التالي لمزيد من المعلومات:
النوع | حقل مطلوب | مثال |
---|---|---|
function | إجراء اختياري | native_callback: handleResponse |
الإلغاء_عند_النقر_خارجيًا
يحدّد هذا الحقل ما إذا كان سيتم إلغاء طلب "نقرة واحدة" أم لا إذا نقر المستخدم
خارج رسالة المطالبة. ستكون القيمة التلقائية true
. يمكنك إيقافها إذا ضبطت
القيمة على false
. اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:
النوع | حقل مطلوب | مثال |
---|---|---|
منطقية | إجراء اختياري | cancel_on_tap_outside: false |
معرّف_الأصل
تعيّن هذه السمة معرّف DOM لعنصر الحاوية. وإذا تم تركها بدون ضبط، سيتم عرض رسالة "نقرة واحدة" في أعلى يسار النافذة. راجِع الجدول التالي لمزيد من المعلومات:
النوع | حقل مطلوب | مثال |
---|---|---|
سلسلة | إجراء اختياري | prompt_parent_id: 'parent_id' |
رقم خاص
هذا الحقل هو سلسلة عشوائية يستخدمها الرمز المميز للمعرّف لمنع هجمات إعادة التشغيل. اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:
النوع | حقل مطلوب | مثال |
---|---|---|
سلسلة | إجراء اختياري | nonce: "biaqbm70g23" |
يكون طول الرمز مقيَّدًا بالحد الأقصى لحجم JWT الذي تستخدمه بيئتك وقيود حجم HTTP لكل من المتصفح والخادم.
سياق
يؤدي هذا الحقل إلى تغيير نص العنوان والرسائل في إشعار "نقرة واحدة". راجِع الجدول التالي لمزيد من المعلومات:
النوع | حقل مطلوب | مثال |
---|---|---|
سلسلة | إجراء اختياري | context: "use" |
يسرد الجدول التالي السياقات المتاحة وأوصافها:
السياق | |
---|---|
signin |
"تسجيل الدخول باستخدام حساب Google" |
signup |
"الاشتراك باستخدام حساب Google" |
use |
"الاستخدام مع Google" |
نطاق_ملف تعريف الارتباط_الحالة
إذا كنت تريد عرض "نقرة واحدة" في النطاق الرئيسي والنطاقات الفرعية التابعة له، أدخِل النطاق الرئيسي في هذا الحقل بحيث يتم استخدام ملف تعريف ارتباط واحد للحالة المشتركة. راجِع الجدول التالي لمزيد من المعلومات:
النوع | حقل مطلوب | مثال |
---|---|---|
سلسلة | إجراء اختياري | state_cookie_domain: "example.com" |
وضع_ux
استخدِم هذا الحقل لإعداد مسار تجربة المستخدم الذي يستخدمه زر "تسجيل الدخول باستخدام حساب Google". والقيمة التلقائية هي popup
. لا تؤثّر هذه السمة في تجربة المستخدم لتطبيق OneTap. راجِع الجدول التالي لمزيد من المعلومات:
النوع | حقل مطلوب | مثال |
---|---|---|
سلسلة | إجراء اختياري | ux_mode: "redirect" |
يسرد الجدول التالي أوضاع تجربة المستخدم المتاحة وأوصافها.
وضع تجربة المستخدم | |
---|---|
popup |
يجري مسار تجربة المستخدم لتسجيل الدخول في نافذة منبثقة. |
redirect |
يؤدي تدفق تجربة المستخدم في تسجيل الدخول من خلال إعادة توجيه الصفحة بأكملها. |
أصل_السماح_الأصلي
المصادر التي يُسمح لها بتضمين إطار 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" المتوسط ويتوقف.
وسيطة_إطارات_iframe_إغلاق_callback
تلغي هذه السياسة سلوك إطار iframe المتوسط التلقائي عندما يغلق المستخدمون يدويًا ميزة "نقرة واحدة" من خلال النقر على الزر "X" في واجهة المستخدم بنقرة واحدة. يتمثل السلوك الافتراضي في إزالة إطار iframe المتوسط من نموذج العناصر في المستند (DOM) على الفور.
ولن يسري تأثير الحقل intermediate_iframe_close_callback
إلا في
وضع iframe المتوسط. وهو يؤثر فقط في إطار iframe المتوسط، بدلاً من تأثير iframe بنقرة واحدة. تتم إزالة واجهة المستخدم بنقرة واحدة قبل استدعاء معاودة الاتصال.
النوع | حقل مطلوب | مثال |
---|---|---|
function | إجراء اختياري | intermediate_iframe_close_callback: logBeforeClose |
دعم_itp
يحدّد هذا الحقل ما إذا كان يجب تفعيل
تجربة المستخدم بنقرة واحدة التي تمت ترقيتها على المتصفّحات التي تتوافق مع ميزة "منع التتبّع الذكي" (ITP). القيمة التلقائية هي false
. انظر الجدول التالي للحصول على مزيد من المعلومات:
النوع | حقل مطلوب | مثال |
---|---|---|
منطقية | إجراء اختياري | itp_support: true |
تلميح_تسجيل الدخول
إذا كان تطبيقك يعرف مسبقًا المستخدم الذي يجب أن يسجّل الدخول، يمكنه تقديم تلميح لتسجيل الدخول إلى Google. عند نجاح هذا الإجراء، يتم تخطّي اختيار الحساب. القيم المقبولة هي: عنوان بريد إلكتروني أو قيمة حقل فرع للرمز المميّز للمعرّف.
لمزيد من المعلومات، اطّلع على الحقل login_hint في وثائق OpenID Connect.
النوع | حقل مطلوب | مثال |
---|---|---|
سلسلة أو عنوان بريد إلكتروني أو القيمة من حقل الرمز المميّز للمعرّف
sub . |
إجراء اختياري | login_hint: 'elisa.beckett@gmail.com' |
جودة عالية الدقة
في حال كان لدى المستخدم حسابات متعددة ويجب تسجيل الدخول باستخدام حسابه على Workspace فقط، استخدِم هذا الخيار لتقديم تلميح إلى Google عن اسم النطاق. عند نجاح هذا الإجراء، تقتصر حسابات المستخدمين
التي يتم عرضها أثناء اختيار الحساب على النطاق المقدَّم.
قيمة حرف بدل: تقدِّم *
للمستخدم حسابات Workspace فقط وتستثني
حسابات المستهلكين (user@gmail.com) أثناء اختيار الحسابات.
للمزيد من المعلومات، راجع حقل hd في وثائق OpenID Connect.
النوع | حقل مطلوب | مثال |
---|---|---|
سلسلة. اسم مجال مؤهل بالكامل أو *. | إجراء اختياري | hd: '*' |
استخدام_fedcm_for_prompt
السماح للمتصفّح بالتحكّم في طلبات تسجيل الدخول الخاصة بالمستخدمين والتوسّط في عملية تسجيل الدخول بين موقعك الإلكتروني وGoogle الخيار التلقائي هو "خطأ".
النوع | حقل مطلوب | مثال |
---|---|---|
منطقية | إجراء اختياري | 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>
نوع البيانات: PromptMomentNotifications
يعرض الجدول التالي طرق وأوصاف نوع بيانات "PromptMomentNotification
":
الطريقة | |
---|---|
isDisplayMoment() |
هل هذا الإشعار مخصص للحظة عرض؟ |
isDisplayed() |
هل هذا الإشعار مخصص للحظة للعرض ويتم عرض واجهة المستخدم؟ |
isNotDisplayed() |
هل هذا الإشعار مخصص للحظة عرض ولا يتم عرض واجهة المستخدم؟ |
getNotDisplayedReason() |
السبب التفصيلي لعدم عرض واجهة المستخدم. وفي ما يلي القيم المحتمَلة:
|
isSkippedMoment() |
هل هذا الإشعار خاص بلحظة تم تخطّيها؟ |
getSkippedReason() |
السبب التفصيلي للحظة التي تم تخطيها. وفي ما يلي القيم المحتمَلة:
|
isDismissedMoment() |
هل هذا الإشعار مخصص للحظة المرفوضة؟ |
getDismissedReason() |
السبب التفصيلي للإغلاق. وفي ما يلي القيم المحتمَلة:
|
getMomentType() |
عرض سلسلة لنوع اللحظة. وفي ما يلي القيم المحتمَلة:
|
نوع البيانات: 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.
باستخدام الحقول 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
". يُستخدم نوع الزر المستخدم مع الجلسة وحالة الموافقة لتحديد القيمة
ضغط المستخدم إمّا على زر "نقرة واحدة" أو "تسجيل الدخول باستخدام حساب 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 |
مظهر الزر على سبيل المثال، filled_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 |
![]() ![]() |
signup_with |
![]() ![]() |
continue_with |
![]() ![]() |
signin |
![]() ![]() |
shape
شكل الزر. ستكون القيمة التلقائية rectangular
. اطّلِع على الجدول التالي
للحصول على مزيد من المعلومات:
النوع | حقل مطلوب | مثال |
---|---|---|
سلسلة | إجراء اختياري | shape: "rectangular" |
يسرد الجدول التالي أشكال الأزرار المتاحة وأوصافها:
شكل | |
---|---|
rectangular |
![]() ![]() ![]() icon ، سيكون مماثلاً لنوع الزر square .
|
pill |
![]() ![]() ![]() icon ، سيتم استخدام النوع نفسه مثل circle .
|
circle |
![]() ![]() ![]() standard ، سيكون مماثلاً لنوع الزر pill .
|
square |
![]() ![]() ![]() standard ، سيكون مماثلاً لنوع الزر rectangular .
|
محاذاة_الشعار
محاذاة شعار Google. ستكون القيمة التلقائية left
. تنطبق هذه السمة
فقط على نوع الزر standard
. انظر الجدول التالي للحصول على مزيد من المعلومات:
النوع | حقل مطلوب | مثال |
---|---|---|
سلسلة | إجراء اختياري | logo_alignment: "center" |
يسرد الجدول التالي عمليات المحاذاة المتاحة وأوصافها:
محاذاة_الشعار | |
---|---|
left |
![]() |
center |
![]() |
width
الحد الأدنى لعرض الزر، بالبكسل. الحد الأقصى للعرض هو 400 بكسل.
اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:
النوع | حقل مطلوب | مثال |
---|---|---|
سلسلة | إجراء اختياري | width: "400" |
locale
اختياريّ. عرض نص الزر باستخدام اللغة المحددة، وبخلاف ذلك، يتم عرض نص الزر تلقائيًا على
حساب المستخدمين في Google أو إعدادات المتصفح. أضِف المعلَمة hl
ورمز اللغة إلى التوجيه src عند تحميل المكتبة، على سبيل المثال: gsi/client?hl=<iso-639-code>
.
وفي حال ترك هذه السياسة بدون ضبط، يتم استخدام اللغة التلقائية للمتصفِّح أو تفضيل مستخدم جلسة 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
يمكنك إلغاء عملية "نقرة واحدة" إذا أزلت الطلب من "إدارة الطرف المعتمَد". يتم تجاهل عملية الإلغاء في حال اختيار بيانات اعتماد من قبل. اطّلع على مثال التعليمة البرمجية التالي للطريقة:
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 المستخدَم لمشاركة
الرمز المميّز للمعرّف للمستخدم المُحدّد. اطّلِع على مقتطف الرمز التالي للطريقة:
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 |
يحتوي هذا الحقل اختياريًا على رسالة مفصلة للاستجابة عن الخطأ. |
ناجح
ويُعدّ هذا الحقل قيمة منطقية يتم ضبطها على "صحيح" في حال نجاح استدعاء طريقة الإبطال أو ضبط القيمة على "خطأ" عند الفشل.
خطأ
هذا الحقل هو قيمة سلسلة ويحتوي على رسالة خطأ مفصّلة في حال تعذّر استدعاء طريقة الإبطال، يعني ذلك أنّه غير معرَّف عند النجاح.