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

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

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

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

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

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

السمة
data-client_id معرِّف العميل لتطبيقك
data-auto_prompt عرض "نقرة واحدة" في Google
data-auto_select يتم تفعيل الاختيار التلقائي بنقرة واحدة من Google.
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 يؤدي هذا الخيار إلى تفعيل ميزة One Tap UX التي تمت ترقيتها على متصفّحات بروتوكول ITP.
data-login_hint يمكنك تخطّي اختيار الحساب من خلال تقديم تلميح للمستخدم.
data-hd تحديد الحسابات حسب النطاق
data-use_fedcm_for_prompt يمكنك السماح للمتصفّح بالتحكّم في طلبات تسجيل الدخول إلى المستخدمين والتوسّط في عملية تسجيل الدخول بين موقعك الإلكتروني وGoogle.

أنواع السمات

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

data-client_id (معرّف_عميل_البيانات)

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

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

طلب_البيانات تلقائيًا

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

النوع مطلوبة مثال
boolean اختياري data-auto_prompt="true"

تحديد تلقائي للبيانات

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

النوع مطلوبة مثال
boolean اختياري data-auto_select="true"

data-login_uri

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

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

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

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

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

النوع اختياري مثال
عنوان URL يتم ضبط عنوان 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 مطلوبة لوضع "تجربة المستخدم" لزرّ تسجيل الدخول باستخدام حساب Google redirect، والذي يتجاهل السمة data-callback.

  • يجب ضبط إحدى هاتين السمتَين لوضع "تجربة المستخدم" في ميزة "نقرة واحدة من Google" وزر "تسجيل الدخول بحساب 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

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

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

النوع مطلوبة مثال
الوظيفة اختياري 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".
data-state وفي حال ضبطها، يتم إرجاع هذه السلسلة مع الرمز المميّز للمعرّف.

أنواع السمات

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

نوع البيانات

نوع الزر. ستكون القيمة التلقائية 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"

data-click_listener

يمكنك تحديد دالة JavaScript ليتم طلبها عند النقر على زر "تسجيل الدخول باستخدام حساب Google" باستخدام سمة data-click_listener.

  <script>
    function onClickHandler(){
      console.log("Sign in with Google button clicked...")
    }
  </script>
  .....
  <div class="g_id_signin"
      data-size="large"
      data-theme="outline"
      data-click_listener="onClickHandler">
  </div>

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

data-state

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

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

النوع مطلوبة مثال
سلسلة اختياري data-state="button 1"

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

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

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

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

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

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

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

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

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، يتم تأكيد أنّ المستخدم هو المالك الشرعي للحساب.

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

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

يمكن للمستخدمين التسجيل في حسابات Google بدون استخدام Gmail أو Google Workspace. عندما لا يحتوي email على لاحقة @gmail.com وhd غير موثوق، لا يكون محرّك بحث Google معتمدًا، ويُنصَح باستخدام كلمة المرور أو طرق الاختبار الأخرى للتحقّق من المستخدم. يمكن أن يكون email_verified صحيحًا أيضًا لأنّ 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، ثم ضغط على الزر "تأكيد" للموافقة ومشاركة بيانات الاعتماد.

state

يتم تحديد هذه المَعلمة فقط عندما ينقر المستخدم على زر "تسجيل الدخول باستخدام حساب Google" لتسجيل الدخول، ويتم تحديد سمة data-state للزر الذي تم النقر عليه. وتكون قيمة هذا الحقل هي القيمة نفسها التي حدّدتها في سمة data-state للزر.

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

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

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

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

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