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

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

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

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

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

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

أنواع السمات

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

data-client_id

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

data-auto_prompt

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

data-auto_select

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

data-login_uri

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

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

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

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

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

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

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

POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

credential=ID_TOKEN

data-callback

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

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

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

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

لا تتوافق دوال JavaScript ضمن مساحة اسم مع HTML API. بدلاً من ذلك، يمكنك استخدام دالة 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-native_callback

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

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

data-native_id_param

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

data-native_password_param

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

data-cancel_on_tap_outside

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

data-prompt_parent_id

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

data-skip_prompt_cookie

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

data-nonce

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

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

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

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

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

data-moment_callback

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

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

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

data-state_cookie_domain

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

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

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

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

data-allowed_parent_origin

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

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

إذا كانت قيمة سمة 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 المؤقت عندما يغلق المستخدمون ميزة One Tap يدويًا من خلال النقر على الزر "X" في واجهة مستخدم One Tap. السلوك التلقائي هو إزالة عنصر iframe الوسيط من نموذج DOM على الفور.

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

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

data-itp_support

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

data-login_hint

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

لمزيد من المعلومات، يُرجى الاطّلاع على مستندات OpenID Connect الخاصة بـ login_hint.

data-hd

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

لمزيد من المعلومات، يُرجى الاطّلاع على مستندات OpenID Connect الخاصة بـ hd.

data-use_fedcm_for_prompt

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

data-enable_redirect_uri_validation

فعِّل تدفق إعادة توجيه الزر الذي يتوافق مع قواعد التحقّق من معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه.

عنصر بالفئة "g_id_signin"

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

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

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

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

أنواع السمات

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

data-type

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

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

النوع
standard
icon

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

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

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

المظهر
outline
filled_blue
filled_black

data-size

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

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

الحجم
large
medium
small

data-text

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

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

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

نص
signin_with
signup_with
continue_with
signin

data-shape

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

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

شكل
rectangular
pill
circle
square

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

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

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

logo_alignment
left
center

data-width

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

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

data-locale

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

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

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

أداة استماع النقر على البيانات

يمكنك تحديد دالة 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" في الصفحة نفسها، يمكنك تخصيص سلسلة فريدة لكل زر. سترجع نفس السلسلة مع الرمز المميز للمعرف، حتى تتمكن من تحديد الزر الذي نقر المستخدم فوقه لتسجيل الدخول.

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

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

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

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

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

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

شهادة

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

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

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

select_by

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

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

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

• قبل مشاركة بيانات اعتماد رمز التعريف مع تطبيقك، على المستخدم إجراء ما يلي:

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

يتم ضبط قيمة هذا الحقل على أحد هذه الأنواع:

الولاية

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

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

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

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

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