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

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

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

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

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

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

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

السمة
`data-client_id`	معرِّف العميل لتطبيقك
`data-color_scheme`	نظام الألوان الذي تم تطبيقه على طلب "النقرة الواحدة"
`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 لعنصر حاوية طلب One Tap
`data-skip_prompt_cookie`	يتم تخطّي ميزة "نقرة واحدة" إذا كانت قيمة ملف تعريف الارتباط المحدّد غير فارغة.
`data-nonce`	سلسلة عشوائية لرموز التعريف المميّزة
`data-essential_claims`	مطالبات إضافية لتضمينها في رمز التعريف الذي تعرضه Google
`data-context`	العنوان والكلمات في طلب ميزة "نقرة واحدة"
`data-moment_callback`	اسم دالة أداة الاستماع إلى إشعارات حالة واجهة المستخدم الخاصة بالطلب
`data-state_cookie_domain`	إذا كنت بحاجة إلى استدعاء ميزة "نقرة واحدة" في النطاق الرئيسي ونطاقاته الفرعية، يجب تمرير النطاق الرئيسي إلى هذه السمة ليتم استخدام ملف تعريف ارتباط واحد مشترَك.
`data-ux_mode`	مسار تجربة المستخدم لزر "تسجيل الدخول باستخدام حساب Google"
`data-allowed_parent_origin`	المصادر المسموح لها بتضمين إطار iframe الوسيط يتم تشغيل ميزة One Tap في وضع iframe الوسيط في حال توفُّر هذه السمة.
`data-intermediate_iframe_close_callback`	تتجاوز هذه السمة السلوك التلقائي لإطار iframe الوسيط عندما يغلق المستخدمون ميزة "بنقرة واحدة" يدويًا.
`data-itp_support`	تفعيل تجربة المستخدم المحسّنة لميزة "بنقرة واحدة" على المتصفّحات التي تستخدم ميزة "منع التتبُّع الذكي" (ITP)
`data-login_hint`	تخطّي اختيار الحساب من خلال تقديم تلميح للمستخدم
`data-hd`	تقييد اختيار الحساب حسب النطاق
`data-use_fedcm_for_prompt`	متوقفة نهائيًا: تم إيقاف هذه السمة نهائيًا وسيتم تجاهلها في حال استخدامها. السماح للمتصفّح بالتحكّم في طلبات تسجيل الدخول التي تظهر للمستخدمين والتوسّط في عملية تسجيل الدخول بين موقعك الإلكتروني وGoogle
`data-use_fedcm_for_button`	يحدّد هذا الحقل ما إذا كان يجب استخدام تجربة المستخدم لزر FedCM على Chrome (الإصدار M125 والإصدارات الأحدث على أجهزة الكمبيوتر والإصدار M128 والإصدارات الأحدث على أجهزة Android). القيمة التلقائية هي `false`.
`data-button_auto_select`	ما إذا كان سيتم تفعيل خيار الاختيار التلقائي لمسار زر FedCM. في حال تفعيل هذه الميزة، سيتم تلقائيًا تسجيل دخول المستخدمين المكرري الزيارة الذين لديهم جلسة نشطة على Google، وسيتم تجاوز طلب "محدّد الحساب". القيمة التلقائية هي `false`.

أنواع السمات

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

data-client_id

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

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

data-color_scheme

يمثّل هذا الحقل نظام الألوان المطبَّق على طلب One Tap. اطّلِع على الجدول التالي لمزيد من المعلومات:

النوع	مطلوب	مثال
سلسلة	اختياريّ. يتم ضبطه تلقائيًا على نظام الألوان التلقائي في نظام المستخدمين.	`data-color_scheme="dark"`

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

الألوان
`default`	تطبيق الألوان التلقائية لنظام المستخدم، استنادًا إلى المظهر المفضّل للمستخدم، سواء كان فاتحًا أو داكنًا
`light`	تطبيق ألوان فاتحة
`dark`	طبِّق ألوانًا داكنة.

data-auto_prompt

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

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

data-auto_select

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

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

data-login_uri

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

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

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

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

يجب أن تعالج نقطة نهاية تسجيل الدخول طلبات POST التي تحتوي على مَعلمة credential مع قيمة رمز مميّز للمعرّف في النص.

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

النوع	اختياري	مثال
عنوان URL	يتم ضبطه تلقائيًا على معرّف الموارد المنتظم (URI) للصفحة الحالية أو القيمة التي تحدّدها. يتم تجاهلها عند ضبط `data-ux_mode="popup"` و`data-callback`.	`data-login_uri="https://www.example.com/login"`

data-callback

هذه السمة هي اسم دالة JavaScript التي تعالج رمز التعريف المميّز الذي تم عرضه. اطّلِع على الجدول التالي لمزيد من المعلومات:

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

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

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

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

يتم تمرير كائن CredentialResponse إلى دالّة رد الاتصال كمَعلمة. راجِع CredentialResponse للاطّلاع على تفاصيل قيم الردود المحتمَلة.

data-native_login_uri

هذه السمة هي عنوان URL لنقطة نهاية معالج بيانات اعتماد كلمة المرور. في حال ضبط السمة data-native_login_uri أو السمة data-native_callback، ستعود مكتبة JavaScript إلى Credential Manager المدمج في حال عدم توفّر جلسة 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 إلى Credential Manager المضمّن في حال عدم توفّر جلسة Google. لا يُسمح لك بضبط كل من data-native_callback وdata-native_login_uri. اطّلِع على الجدول التالي لمزيد من المعلومات:

النوع	مطلوب	مثال
سلسلة	اختياري	`data-native_callback="handlePasswordCredential"`

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

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

النوع	مطلوب	مثال
قيمة منطقية	اختياري	`data-cancel_on_tap_outside="false"`

data-prompt_parent_id

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

النوع	مطلوب	مثال
سلسلة	اختياري	`data-prompt_parent_id="parent_id"`

data-skip_prompt_cookie

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

النوع	مطلوب	مثال
سلسلة	اختياري	`data-skip_prompt_cookie="SID"`

data-nonce

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

النوع	مطلوب	مثال
سلسلة	اختياري	`data-nonce="biaqbm70g23"`

يقتصر طول الرمز المميّز على الحد الأقصى لحجم رمز JWT الذي تتيحه بيئتك، وقيود حجم HTTP الفردية للمتصفّح والخادم.

data-essential_claims

هذه السمة هي سلسلة تُستخدَم لطلب تضمين مطالبات إضافية في الرمز المميّز للتعريف الذي تعرضه Google. للاطّلاع على قائمة كاملة بالادّعاءات التي تقبلها Google، يُرجى مراجعة الادّعاءات المتاحة.

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

النوع	مطلوب	مثال
سلسلة	اختياري	`data-essential_claims="auth_time, amr"`

data-context

يغيّر هذا الحقل نص العنوان والرسائل التي تظهر في طلب "نقرة واحدة"، ولا يؤثر في متصفّحات ITP. القيمة التلقائية هي signin.

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

النوع	مطلوب	مثال
سلسلة	اختياري	`data-context="use"`

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

السياق
`signin`	"تسجيل الدخول إلى"
`signup`	"Sign up to"
`use`	"استخدام"

data-moment_callback

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

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

النوع	مطلوب	مثال
سلسلة	اختياري	`data-moment_callback="logMomentNotification"`

data-state_cookie_domain

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

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

النوع	مطلوب	مثال
دالة	اختياري	`data-intermediate_iframe_close_callback="logBeforeClose"`

data-itp_support

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

النوع	مطلوب	مثال
قيمة منطقية	اختياري	`data-itp_support="false"`

data-login_hint

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

لمزيد من المعلومات، يُرجى الاطّلاع على مستندات OpenID Connect حول login_hint.

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

data-hd

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

لمزيد من المعلومات، يُرجى الاطّلاع على مستندات OpenID Connect حول hd.

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

data-use_fedcm_for_prompt

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

النوع	مطلوب	مثال
قيمة منطقية	منهي العمل به	`data-use_fedcm_for_prompt="true"`

data-use_fedcm_for_button

يحدّد هذا الحقل ما إذا كان يجب استخدام تجربة المستخدم لزر FedCM على Chrome (الإصدار M125 والإصدارات الأحدث على أجهزة الكمبيوتر المكتبي والإصدار M128 والإصدارات الأحدث على أجهزة Android). القيمة التلقائية هي false. اطّلِع على الجدول التالي لمزيد من المعلومات:

النوع	مطلوب	مثال
قيمة منطقية	اختياري	`data-use_fedcm_for_button="true"`

data-button_auto_select

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

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

أنواع السمات

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

data-type

نوع الزر تكون القيمة التلقائية standard. اطّلِع على الجدول التالي لمزيد من المعلومات:

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

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

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

data-theme

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

النوع	مطلوب	مثال
سلسلة	اختياري	`data-theme="filled_blue"`

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

المظهر	نماذج	المواصفات
`outline`	مظهر الزر العادي	التعبئة: ‎#FFFFFF الحد الخارجي: ‎#747775 \| ‏1 بكسل \| داخلي الخط: ‎#1F1F1F \| ‏Roboto Medium \| ‏14/20 مخصّص: ‎#1F1F1F \| ‏Roboto \| ‏Medium 12/14 \| ‏Regular 11/13
`filled_blue`	مظهر زرّ باللون الأزرق	Fill: #0B57D0 Stroke: #OB57D0 \| 1px \| inside Font: #FFFFFF \| Google Sans Medium \| 14/20 Personalized: #FFFFFF \| Roboto \| Medium 12/14 \| Regular 11/13
`filled_black`	مظهر زرّ أسود مع شعار متباين	التعبئة: ‎#202124 الحدّ: ‎#OB57D0 \| ‏1 بكسل \| داخلي الخط: ‎#FFFFFF \| ‏Google Sans Medium \| ‏14/20 مخصّص: ‎#FFFFFF \| ‏Roboto \| ‏Medium 12/14 \| ‏Regular 11/13
`outline_dark`	مظهر زرّ أسود اللون	التعبئة: #131314 الحدّ: #8E918F \| 1 بكسل \| داخلي الخط: #FFFFFF \| Google Sans Medium \| 14/20 مخصّص: #FFFFFF \| Roboto \| Medium 12/14 \| Regular 11/13

data-size

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

النوع	مطلوب	مثال
سلسلة	اختياري	`data-size="small"`

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

الحجم
`large`	زر كبير
`medium`	زر متوسط الحجم
`small`	زر صغير

data-text

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

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

النوع	مطلوب	مثال
سلسلة	اختياري	`data-text="signup_with"`

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

نص
`signin_with`	نص الزر هو "تسجيل الدخول باستخدام حساب Google".
`signup_with`	نص الزر هو "الاشتراك باستخدام حساب Google".
`continue_with`	نص الزر هو "المتابعة باستخدام حساب Google".
`signin`	نص الزر هو "تسجيل الدخول".

data-shape

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

النوع	مطلوب	مثال
سلسلة	اختياري	`data-shape="rectangular"`

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

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

data-logo_alignment

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

النوع	مطلوب	مثال
سلسلة	اختياري	`data-logo_alignment="center"`

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

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

data-width

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

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

النوع	مطلوب	مثال
سلسلة	اختياري	`data-width=400`

data-locale

اختياريّ. يتم عرض نص الزر باستخدام الإعدادات المحلية المحدّدة، وإلا سيتم استخدام الإعدادات التلقائية لحساب 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 التالية.

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

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

مثال على طلب إلى نقطة نهاية تسجيل الدخول:

POST /login HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Cookie: g_csrf_token=<RANDOM_STRING>
Host: www.example.com

credential=<JWT_ENCODED_ID_TOKEN>&g_csrf_token=<RANDOM_STRING>

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

التنسيق	الاسم	الوصف
ملف تعريف الارتباط	`g_csrf_token`	سلسلة عشوائية تتغيّر مع كل طلب إلى نقطة نهاية تسجيل الدخول المحدّدة بواسطة `data-login_uri`، ويجب أن تتطابق مع القيمة في مَعلمة طلب `g_csrf_token`.
مَعلمة الطلب	`g_csrf_token`	سلسلة عشوائية تتغيّر مع كل طلب إلى نقطة نهاية تسجيل الدخول المحدّدة من خلال `data-login_uri`، ويجب أن تتطابق مع قيمة ملف تعريف الارتباط `g_csrf_token`.
مَعلمة الطلب	`credential`	رمز تعريف JWT المميّز المشفَّر الذي تصدره Google
مَعلمة الطلب	`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 Google Workspace email address
  "auth_time": 1748875426,
  "amr": ["mfa", "pwd", "tel"],
  "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 creation time
  "exp": 1596477600, // Unix timestamp of the assertion expiration time
  "jti": "abc161803398874def"
}

يجب أن تتجاهل البرامج مطالبات JWT غير المعروفة.

الحقل sub هو معرّف فريد عالميًا لحساب Google. يجب استخدام الحقل 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_verified صحيحًا أيضًا لأنّ Google تحقّقت في البداية من المستخدم عند إنشاء حساب Google، ولكن قد تكون ملكية حساب البريد الإلكتروني التابع لجهة خارجية قد تغيّرت منذ ذلك الحين.

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

g_csrf_token

رمز مميّز للحالة الخاصة لمكافحة التزوير هذا رمز مميّز لتزوير الطلبات من مواقع إلكترونية مختلفة (CSRF) تم إنشاؤه بواسطة مكتبة gsi/client. يتم تضمين قيمة عشوائية كملف تعريف ارتباط وكمَعلمة طلب في نص حمولة POST. إذا لم تتطابق هاتان القيمتان عند معالجة الطلب على الخادم، يجب اعتبار الطلب غير صالح.

الولاية

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

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

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

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

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

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

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

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

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

أنواع السمات

data-client_id

data-color_scheme

data-auto_prompt

data-auto_select

data-login_uri

data-callback

data-native_login_uri

data-native_callback

data-native_id_param

data-native_password_param

data-cancel_on_tap_outside

data-prompt_parent_id

data-skip_prompt_cookie

data-nonce

data-essential_claims

data-context

data-moment_callback

data-state_cookie_domain

data-ux_mode

data-allowed_parent_origin

data-intermediate_iframe_close_callback

data-itp_support

data-login_hint

data-hd

data-use_fedcm_for_prompt

data-use_fedcm_for_button

data-button_auto_select

العنصر الذي يتضمّن الفئة "g_id_signin"

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

أنواع السمات

data-type

data-theme

data-size

data-text

data-shape

data-logo_alignment

data-width

data-locale

data-click_listener

data-state

الدمج على صعيد الخادم

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

شهادة

g_csrf_token

الولاية

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

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