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

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

العنصر الذي يحمل المعرّف "g_id_onload"

يمكنك وضع سمات بيانات "تسجيل الدخول باستخدام حساب Google" في أي عناصر مرئية أو غير مرئية، مثل <div> و<span>. الشرط الوحيد هو ضبط معرّف العنصر على g_id_onload. لا تضع هذا المعرّف على عناصر متعددة.

سمات البيانات

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

السمة
data-client_id معرِّف العميل لتطبيقك
data-auto_prompt عرض بنقرة واحدة في Google One
data-auto_select تفعِّل هذه السياسة الاختيار التلقائي في Google One Tap.
data-login_uri عنوان URL لنقطة نهاية تسجيل الدخول
data-callback اسم وظيفة معالج الرمز المميز لرقم تعريف JavaScript
data-native_login_uri عنوان URL لنقطة نهاية معالج بيانات اعتماد كلمة المرور
data-native_callback اسم وظيفة معالج بيانات اعتماد كلمة مرور JavaScript
data-native_id_param اسم المَعلمة للقيمة credential.id
data-native_password_param اسم المَعلمة للقيمة credential.password
data-cancel_on_tap_outside تتحكّم هذه السياسة في ما إذا كان سيتم إلغاء رسالة المطالبة إذا نقر المستخدم خارج نطاق الإشعار.
data-prompt_parent_id رقم تعريف DOM لعنصر حاوية طلب ميزة "نقرة واحدة"
data-skip_prompt_cookie تخطّي نقرة واحدة إذا كان ملف تعريف الارتباط المحدّد يحتوي على قيمة غير فارغة
data-nonce سلسلة عشوائية للرموز المميّزة للمعرّف
data-context العنوان والكلمات في إشعار "نقرة واحدة"
data-moment_callback اسم الدالة لأداة معالجة إشعارات حالة واجهة المستخدم للطلب
data-state_cookie_domain إذا أردت طلب ميزة "نقرة واحدة" في النطاق الرئيسي والنطاقات الفرعية التابعة له، أضِف النطاق الرئيسي إلى هذه السمة ليتم استخدام ملف تعريف ارتباط مشترك واحد.
data-ux_mode تدفق تجربة المستخدم لزر "تسجيل الدخول باستخدام حساب Google"
data-allowed_parent_origin المصادر التي يُسمح لها بتضمين إطار iframe المتوسط. يتم تشغيل ميزة "نقرة واحدة" في وضع iframe المتوسط في حال توفّر هذه السمة.
data-intermediate_iframe_close_callback تلغي هذه السياسة سلوك إطار iframe المتوسط التلقائي عندما يغلق المستخدمون يدويًا ميزة "نقرة واحدة".
data-itp_support تفعيل ميزة "تجربة المستخدم بنقرة واحدة" التي تمت ترقيتها على متصفِّحات ITP
data-login_hint تخطي اختيار الحساب من خلال تقديم تلميح للمستخدم.
data-hd حصر اختيار الحسابات حسب النطاق
data-use_fedcm_for_prompt السماح للمتصفّح بالتحكّم في طلبات تسجيل الدخول من المستخدمين والتوسّط في عملية تسجيل الدخول بين موقعك الإلكتروني وGoogle

أنواع السمات

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

data-client_id

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

النوع حقل مطلوب مثال
سلسلة نعم data-client_id="CLIENT_ID.apps.googleusercontent.com"

data-prompt

تحدد هذه السمة ما إذا كان سيتم عرض "نقرة واحدة" أم لا. القيمة التلقائية هي true. لا يتم عرض نقرة Google One عندما تكون هذه القيمة false. راجِع الجدول التالي لمزيد من المعلومات:

النوع حقل مطلوب مثال
boolean إجراء اختياري data-auto_prompt="true"

data-auto_select

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

النوع حقل مطلوب مثال
boolean إجراء اختياري data-auto_select="true"

data-login_uri

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

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

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

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

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

النوع إجراء اختياري مثال
عنوان URL يتم ضبط هذه الخاصية تلقائيًا على معرّف الموارد المنتظم (URI) للصفحة الحالية أو القيمة التي تحدّدها.
يتم تجاهل السياسة عند ضبط data-ux_mode="popup" و data-callback.
data-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 التي تتعامل مع الرمز المميّز الذي تم عرضه للمعرّف. اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع حقل مطلوب مثال
سلسلة تكون هذه السمة مطلوبة إذا لم يتم ضبط سياسة data-login_uri. data-callback="handleToken"

ويمكن استخدام إحدى السمتَين data-login_uri وdata-callback. يعتمد ذلك على تكوينات المكونات ووضع تجربة المستخدم التالية:

  • السمة data-login_uri مطلوبة لوضع "تجربة المستخدم" redirect على زر "تسجيل الدخول باستخدام حساب Google"، والذي يتجاهل سمة data-callback.

  • يجب ضبط إحدى هاتين السمتَين في وضع تجربة المستخدم "نقرة واحدة" في Google One وزر "تسجيل الدخول بحساب Google" popup. وفي حال ضبطهما، تكون الأولوية للسمة data-callback.

دوال JavaScript داخل مساحة الاسم غير متوافقة مع واجهة برمجة تطبيقات HTML. بدلاً من ذلك، يمكنك استخدام دالة JavaScript عمومية بدون مساحة اسم. على سبيل المثال، استخدِم mylibCallback بدلاً من mylib.callback.

data-native_login_uri

هذه السمة هي عنوان URL لنقطة نهاية معالج بيانات اعتماد كلمة المرور. في حال ضبط السمة data-native_login_uri أو السمة data-native_callback، تعود مكتبة JavaScript إلى مدير بيانات الاعتماد الأصلي في حال عدم توفّر جلسة Google. لا يُسمح لك بضبط السمتَين data-native_callback وdata-native_login_uri معًا. اطلع على الجدول التالي للحصول على مزيد من المعلومات:

النوع حقل مطلوب مثال
سلسلة إجراء اختياري data-login_uri="https://www.example.com/password_login"

data-Native_callback

هذه السمة هي اسم دالة JavaScript التي تتعامل مع بيانات اعتماد كلمة المرور التي يتم عرضها من مدير بيانات الاعتماد الأصلي في المتصفح. في حال ضبط إما السمة data-native_login_uri أو السمة data-native_callback، تعود مكتبة JavaScript إلى مدير بيانات الاعتماد الأصلي في حال عدم توفّر جلسة Google. لا يُسمح لك بضبط كل من data-native_callback وdata-native_login_uri. انظر الجدول التالي لمزيد من المعلومات:

النوع حقل مطلوب مثال
سلسلة إجراء اختياري data-native_callback="handlePasswordCredential"

دوال JavaScript داخل مساحة الاسم غير متوافقة مع واجهة برمجة تطبيقات HTML. بدلاً من ذلك، يمكنك استخدام دالة JavaScript عمومية بدون مساحة اسم. على سبيل المثال، استخدِم mylibCallback بدلاً من mylib.callback.

data-native_id_param

عند إرسال بيانات اعتماد كلمة المرور إلى نقطة نهاية معالج بيانات اعتماد كلمة المرور، يمكنك تحديد اسم المعلمة للحقل credential.id. والاسم التلقائي هو email. اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع حقل مطلوب مثال
عنوان URL إجراء اختياري data-native_id_param="user_id"

data-native_password_param

عند إرسال بيانات اعتماد كلمة المرور إلى نقطة نهاية معالج بيانات اعتماد كلمة المرور، يمكنك تحديد اسم المعلمة للقيمة credential.password. الاسم التلقائي هو password. انظر الجدول التالي للحصول على مزيد من المعلومات:

النوع حقل مطلوب مثال
عنوان URL إجراء اختياري data-native_password_param="pwd"

data-cancel_on_tap_outside

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

النوع حقل مطلوب مثال
boolean إجراء اختياري data-cancel_on_tap_outside="false"

data-prompt_parent_id

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

النوع حقل مطلوب مثال
سلسلة إجراء اختياري data-prompt_parent_id="parent_id"

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

النوع حقل مطلوب مثال
سلسلة إجراء اختياري data-skip_prompt_cookie="SID"

بيانات غير آمنة

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

النوع حقل مطلوب مثال
سلسلة إجراء اختياري data-nonce="biaqbm70g23"

يكون طول الرمز مقيَّدًا بالحد الأقصى لحجم JWT الذي تستخدمه بيئتك وقيود حجم HTTP لكل من المتصفح والخادم.

سياق البيانات

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

النوع حقل مطلوب مثال
سلسلة إجراء اختياري data-context="use"

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

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

data-moment_callback

هذه السمة هي اسم الدالة لمستمع إشعارات حالة واجهة المستخدم للمطالبة. لمزيد من المعلومات، راجِع نوع البيانات PromptMomentNotification.

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

النوع حقل مطلوب مثال
سلسلة إجراء اختياري data-moment_callback="logMomentNotification"

دوال JavaScript داخل مساحة الاسم غير متوافقة مع واجهة برمجة تطبيقات HTML. بدلاً من ذلك، يمكنك استخدام دالة JavaScript عمومية بدون مساحة اسم. على سبيل المثال، استخدِم mylibCallback بدلاً من mylib.callback.

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

النوع حقل مطلوب مثال
سلسلة إجراء اختياري data-state_cookie_domain="example.com"

data-ux_mode

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

النوع حقل مطلوب مثال
سلسلة إجراء اختياري data-ux_mode="redirect"

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

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

data-allowed_parent_origin

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

النوع حقل مطلوب مثال
مصفوفة سلسلة أو إجراء اختياري data-allowed_parent_origin="https://example.com"

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

أنواع القيم
string معرّف موارد منتظم (URI) لنطاق واحد. "https://example.com"
string array قائمة معرّفات الموارد المنتظمة (URI) المفصولة بفواصل. "https://news.example.com,https://local.example.com"

وإذا كانت قيمة السمة data-allowed_parent_origin غير صالحة، سيتعذّر إتمام عملية إعداد "وضع iframe المتوسط" بنقرة واحدة وتتوقّف.

يمكن أيضًا استخدام بادئات أحرف البدل. على سبيل المثال، يتطابق "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" غير صالح.

data-intermediate_iframe_close_callback

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

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

النوع حقل مطلوب مثال
function إجراء اختياري data-intermediate_iframe_close_callback="logBeforeClose"

دوال JavaScript داخل مساحة الاسم غير متوافقة مع واجهة برمجة تطبيقات HTML. بدلاً من ذلك، يمكنك استخدام دالة JavaScript عمومية بدون مساحة اسم. على سبيل المثال، استخدِم mylibCallback بدلاً من mylib.callback.

data-itp_support

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

النوع حقل مطلوب مثال
boolean إجراء اختياري data-itp_support="true"

data-login_hint

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

للمزيد من المعلومات، يُرجى الاطّلاع على وثائق OpenID Connect لـ login_hint.

النوع حقل مطلوب مثال
سلسلة. يمكن أن يكون عنوان بريد إلكتروني أو قيمة الحقل sub من الرمز المميّز للمعرّف. إجراء اختياري data-login_hint="elisa.beckett@gmail.com"

بيانات عالية الدقة

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

للمزيد من المعلومات، يُرجى الاطّلاع على وثائق OpenID Connect لـ hd.

النوع حقل مطلوب مثال
سلسلة. اسم مجال مؤهل بالكامل أو *. إجراء اختياري data-hd="*"

data-use_fedcm_for_prompt

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

النوع حقل مطلوب مثال
boolean إجراء اختياري data-use_fedcm_for_prompt="true"

العنصر ذو الفئة "g_id_signin"

إذا أضفت g_id_signin إلى سمة class لعنصر معيّن، سيتم عرضه على شكل زر "تسجيل الدخول باستخدام حساب Google".

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

سمات البيانات المرئية

يسرد الجدول التالي سمات البيانات المرئية وأوصافها:

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

أنواع السمات

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

نوع البيانات

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

النوع حقل مطلوب مثال
سلسلة نعم data-type="icon"

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

النوع
standard
زر يتضمن نصًا أو معلومات مخصّصة.
icon
زر رمز بدون نص.

موضوع البيانات

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

النوع حقل مطلوب مثال
سلسلة إجراء اختياري data-theme="filled_blue"

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

المظهر
outline
زر عادي بخلفية بيضاء زر على شكل رمز بخلفية بيضاء زر مخصص بخلفية بيضاء
مظهر الزر العادي.
filled_blue
زر عادي بخلفية زرقاء زر على شكل رمز بخلفية زرقاء زر مخصص بخلفية زرقاء
مظهر الأزرار الأزرق اللون.
filled_black
زر عادي بخلفية سوداء زر على شكل رمز بخلفية سوداء زر مخصص بخلفية سوداء
مظهر الأزرار المملوء باللون الأسود

data-size

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

النوع حقل مطلوب مثال
سلسلة إجراء اختياري data-size="small"

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

حجم الملف
large
زر عادي كبير زر رمز كبير زر كبير مخصّص
زر كبير.
medium
زر عادي متوسط زر رمز متوسط
زر متوسط الحجم.
small
زر صغير زر على شكل رمز صغير
زر صغير.

نص-البيانات

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

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

النوع حقل مطلوب مثال
سلسلة إجراء اختياري data-text="signup_with"

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

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

شكل البيانات

شكل الزر. ستكون القيمة التلقائية rectangular. اطّلِع على الجدول التالي للحصول على مزيد من المعلومات:

النوع حقل مطلوب مثال
سلسلة إجراء اختياري data-shape="rectangular"

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

شكل
rectangular
زر قياسي مستطيل زر رمز مستطيل زر مخصص مستطيل
الزر المستطيل. وإذا تم استخدامها لنوع الزر icon، سيتم استخدام النوع نفسه مع square.
pill
زر عادي على شكل حبة دواء زر رمز على شكل حبة زر مخصَّص على شكل حبة
الزر على شكل حبة دواء. في حال استخدام نوع الزر icon، سيتم استخدام النوع نفسه مثل circle.
circle
زر عادي دائري زر على شكل رمز دائري زر مخصّص دائري
الزر على شكل دائرة. في حال استخدام نوع الزر standard، سيكون مماثلاً لنوع الزر pill.
square
زر عادي مربع زر على شكل رمز مربّع زر مخصص مربع
الزر على شكل مربّع. في حال استخدام نوع الزر standard، سيكون مماثلاً لنوع الزر rectangular.

محاذاة_شعار_البيانات

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

النوع حقل مطلوب مثال
سلسلة إجراء اختياري data-logo_alignment="center"

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

logo_alignment
left
زر عادي مع شعار G على اليسار
محاذاة شعار Google إلى اليسار
center
زر قياسي يحمل شعار G في المنتصف
محاذاة شعار Google إلى الوسط.

عرض البيانات

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

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

النوع حقل مطلوب مثال
سلسلة إجراء اختياري data-width=400

لغة البيانات

اختياريّ. عرض نص الزر باستخدام اللغة المحددة، وبخلاف ذلك، يتم عرض نص الزر تلقائيًا على حساب المستخدمين في Google أو إعدادات المتصفح. أضِف المعلَمة hl ورمز اللغة إلى التوجيه src عند تحميل المكتبة، على سبيل المثال: gsi/client?hl=<iso-639-code>.

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

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

النوع حقل مطلوب مثال
سلسلة إجراء اختياري data-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".

التكامل من جهة الخادم

يجب أن تعالج نقاط النهاية من جهة الخادم طلبات HTTP POST التالية.

نقطة نهاية معالج الرمز المميز لرقم التعريف

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

يحتوي طلب HTTP POST على المعلومات التالية:

التنسيق الاسم الوصف
كعكة g_csrf_token سلسلة عشوائية تتغير مع كل طلب إلى نقطة نهاية المعالج.
مَعلمة الطلب g_csrf_token سلسلة مطابقة لقيمة ملف تعريف الارتباط السابقة، g_csrf_token.
مَعلمة الطلب credential الرمز المميّز لرقم التعريف الذي يصدره محرّك بحث Google
مَعلمة الطلب select_by كيفية اختيار بيانات الاعتماد

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

عند فك ترميز البيانات، يظهر الرمز المميّز للمعرّف على النحو التالي:

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": "Eliza",
  "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، ثم ضغط على الزر "تأكيد" للموافقة ومشاركة بيانات الاعتماد.

نقطة نهاية معالج بيانات اعتماد كلمة المرور

تعالج نقطة نهاية معالج بيانات اعتماد كلمة المرور بيانات اعتماد كلمة المرور التي يستردها مدير بيانات الاعتماد الأصلي.

يحتوي طلب HTTP POST على المعلومات التالية:

التنسيق الاسم الوصف
كعكة g_csrf_token سلسلة عشوائية تتغير مع كل طلب إلى نقطة نهاية المعالج.
مَعلمة الطلب g_csrf_token سلسلة مطابقة لقيمة ملف تعريف الارتباط السابقة، g_csrf_token.
مَعلمة الطلب email الرمز المميّز لرقم التعريف هذا الذي يصدره محرّك بحث Google
مَعلمة الطلب password كيفية اختيار بيانات الاعتماد