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

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

الطريقة: google.accounts.id.initialize

تعمل الطريقة google.accounts.id.initialize على إعداد عميل "تسجيل الدخول باستخدام حساب Google" استنادًا إلى كائن الضبط. اطّلع على مثال التعليمة البرمجية التالي للطريقة:

google.accounts.id.initialize(IdConfiguration)

ينفّذ مثال الرمز التالي طريقة google.accounts.id.initialize باستخدام الدالة onload:

<script>
  window.onload = function () {
    google.accounts.id.initialize({
      client_id: 'YOUR_GOOGLE_CLIENT_ID',
      callback: handleCredentialResponse
    });
    google.accounts.id.prompt();
  };
</script>

تنشئ الطريقة google.accounts.id.initialize مثيلاً لعميل "تسجيل الدخول باستخدام حساب Google" يمكن استخدامه ضمنيًا في كل الوحدات في صفحة الويب نفسها.

  • ما عليك سوى طلب الطريقة google.accounts.id.initialize مرة واحدة حتى إذا كنت تستخدم وحدات متعددة (مثل "نقرة واحدة" أو "زر مخصّص" أو "إبطال" أو غير ذلك) في صفحة الويب نفسها.
  • وإذا استدعيت طريقة google.accounts.id.initialize عدة مرات، سيتم تذكّر الإعدادات واستخدامها فقط في المكالمة الأخيرة.

تتم في الواقع إعادة ضبط الإعدادات عند طلب طريقة google.accounts.id.initialize، وتستخدم جميع الطرق اللاحقة في صفحة الويب نفسها الإعدادات الجديدة على الفور.

نوع البيانات: IdConfiguration

يسرد الجدول التالي الحقول وأوصاف نوع بيانات IdConfiguration:

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

client_id

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

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

اختيار تلقائي

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

النوع حقل مطلوب مثال
منطقية إجراء اختياري auto_select: true

معاودة الاتصال

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

النوع حقل مطلوب مثال
function مطلوب لتفعيل ميزة "نقرة واحدة" ووضع "تجربة المستخدم" في "popup" callback: handleResponse

Login_uri

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

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

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

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

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

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

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

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

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

credential=ID_TOKEN

الاتصال_الأصلي

هذا الحقل هو اسم وظيفة JavaScript التي تتعامل مع بيانات اعتماد كلمة المرور التي يتم عرضها من مدير بيانات الاعتماد الأصلي للمتصفح. راجِع الجدول التالي لمزيد من المعلومات:

النوع حقل مطلوب مثال
function إجراء اختياري native_callback: handleResponse

الإلغاء_عند_النقر_خارجيًا

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

النوع حقل مطلوب مثال
منطقية إجراء اختياري cancel_on_tap_outside: false

معرّف_الأصل

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

النوع حقل مطلوب مثال
سلسلة إجراء اختياري prompt_parent_id: 'parent_id'

رقم خاص

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

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

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

سياق

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

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

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

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

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

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

وضع_ux

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

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

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

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

أصل_السماح_الأصلي

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

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

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

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

يمكن أيضًا استخدام بادئات أحرف البدل. على سبيل المثال، يتطابق "https://*.example.com" مع example.com والنطاقات الفرعية التابعة له على جميع المستويات (مثل news.example.com وlogin.news.example.com). ويجب مراعاة النقاط التالية عند استخدام أحرف البدل:

  • لا يمكن أن تتألف سلاسل الأنماط من حرف بدل ونطاق من المستوى الأعلى فقط. على سبيل المثال، https://*.com وhttps://*.co.uk غير صالحَين. وكما هو موضّح أعلاه، تتطابق السمة "https://*.example.com" مع example.com ونطاقاته الفرعية. يمكنك أيضًا استخدام مصفوفة لتمثيل نطاقَين مختلفَين. على سبيل المثال، ["https://example1.com", "https://*.example2.com"] يتطابق مع النطاقات example1.com وexample2.com والنطاقات الفرعية لـ example2.com.
  • يجب أن تبدأ نطاقات أحرف البدل بنظام https:// آمن، وبالتالي يُعدّ "*.example.com" غير صالح.

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

وسيطة_إطارات_iframe_إغلاق_callback

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

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

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

دعم_itp

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

النوع حقل مطلوب مثال
منطقية إجراء اختياري itp_support: true

تلميح_تسجيل الدخول

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

لمزيد من المعلومات، اطّلع على الحقل login_hint في وثائق OpenID Connect.

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

جودة عالية الدقة

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

للمزيد من المعلومات، راجع حقل hd في وثائق OpenID Connect.

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

استخدام_fedcm_for_prompt

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

النوع حقل مطلوب مثال
منطقية إجراء اختياري use_fedcm_for_prompt: true

الطريقة: google.accounts.id.prompt

تعرض الطريقة google.accounts.id.prompt إشعار "نقرة واحدة" أو مدير بيانات الاعتماد الأصلي في المتصفّح بعد استدعاء طريقة initialize(). اطّلِع على مثال الرمز التالي للطريقة:

 google.accounts.id.prompt(/**
 @type{(function(!PromptMomentNotification):void)=} */ momentListener)

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

يتم تنشيط الإشعارات في اللحظات التالية:

  • لحظة العرض: تحدث هذه اللحظة بعد استدعاء طريقة prompt(). ويحتوي الإشعار على قيمة منطقية للإشارة إلى ما إذا كان سيتم عرض واجهة المستخدم أم لا.

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

    في هذه الحالات، ننصح بالمتابعة إلى موفِّري الهوية القادمين، إن وجدوا.

  • لحظة تم إغلاقها: تحدث عندما يسترد محرّك بحث Google بيانات اعتماد بنجاح أو عندما يريد المستخدم إيقاف عملية استرداد بيانات الاعتماد. على سبيل المثال، عندما يبدأ المستخدم في إدخال اسم المستخدم وكلمة المرور في مربّع حوار تسجيل الدخول، يمكنك استدعاء طريقة google.accounts.id.cancel() لإغلاق رسالة المطالبة بنقرة واحدة وتشغيل لحظة الرفض.

ينفّذ مثال الرمز التالي اللحظة التي تم تخطيها:

<script>
  window.onload = function () {
    google.accounts.id.initialize(...);
    google.accounts.id.prompt((notification) => {
      if (notification.isNotDisplayed() || notification.isSkippedMoment()) {
        // continue with another identity provider.
      }
    });
  };
</script>

نوع البيانات: PromptMomentNotifications

يعرض الجدول التالي طرق وأوصاف نوع بيانات "PromptMomentNotification":

الطريقة
isDisplayMoment() هل هذا الإشعار مخصص للحظة عرض؟
isDisplayed() هل هذا الإشعار مخصص للحظة للعرض ويتم عرض واجهة المستخدم؟
isNotDisplayed() هل هذا الإشعار مخصص للحظة عرض ولا يتم عرض واجهة المستخدم؟
getNotDisplayedReason()

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

  • browser_not_supported
  • invalid_client
  • missing_client_id
  • opt_out_or_no_session
  • secure_http_required
  • suppressed_by_user
  • unregistered_origin
  • unknown_reason
isSkippedMoment() هل هذا الإشعار خاص بلحظة تم تخطّيها؟
getSkippedReason()

السبب التفصيلي للحظة التي تم تخطيها. وفي ما يلي القيم المحتمَلة:

  • auto_cancel
  • user_cancel
  • tap_outside
  • issuing_failed
isDismissedMoment() هل هذا الإشعار مخصص للحظة المرفوضة؟
getDismissedReason()

السبب التفصيلي للإغلاق. وفي ما يلي القيم المحتمَلة:

  • credential_returned
  • cancel_called
  • flow_restarted
getMomentType()

عرض سلسلة لنوع اللحظة. وفي ما يلي القيم المحتمَلة:

  • display
  • skipped
  • dismissed

نوع البيانات: CredentialResponse

عند استدعاء دالة callback، يتم تمرير كائن CredentialResponse باعتباره معلَمة. يسرد الجدول التالي الحقول الموجودة في كائن استجابة بيانات الاعتماد:

الحقل
credential هذا الحقل هو الرمز المميّز للمعرّف الذي يتم عرضه.
select_by يحدِّد هذا الحقل كيفية اختيار بيانات الاعتماد.

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

هذا الحقل هو الرمز المميّز للمعرّف كسلسلة رمز JSON المميّز للويب (JWT) بترميز Base64.

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

header
{
  "alg": "RS256",
  "kid": "f05415b13acb9590f70df862765c655f5a7a019e", // JWT signature
  "typ": "JWT"
}
payload
{
  "iss": "https://accounts.google.com", // The JWT's issuer
  "nbf":  161803398874,
  "aud": "314159265-pi.apps.googleusercontent.com", // Your server's client ID
  "sub": "3141592653589793238", // The unique ID of the user's Google Account
  "hd": "gmail.com", // If present, the host domain of the user's GSuite email address
  "email": "elisa.g.beckett@gmail.com", // The user's email address
  "email_verified": true, // true, if Google has verified the email address
  "azp": "314159265-pi.apps.googleusercontent.com",
  "name": "Elisa Beckett",
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/e2718281828459045235360uler",
  "given_name": "Elisa",
  "family_name": "Beckett",
  "iat": 1596474000, // Unix timestamp of the assertion's creation time
  "exp": 1596477600, // Unix timestamp of the assertion's expiration time
  "jti": "abc161803398874def"
}

يحتوي الحقل sub على معرّف فريد عام لحساب Google.

باستخدام الحقول email وemail_verified وhd، يمكنك تحديد ما إذا كان محرّك بحث Google يستضيف عنوان بريد إلكتروني ويكون موثوقًا به. وفي الحالات التي تكون فيها Google موثوقة، يتم التأكيد على أنّ المستخدم هو المالك الشرعي للحساب.

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

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

يمكن للمستخدمين التسجيل في حسابات Google بدون استخدام Gmail أو Google Workspace. إذا لم يتضمّن email لاحقة @gmail.com ولا يتوفّر hd، لا يكون محرّك بحث Google معتمدًا، ويُنصح باستخدام كلمة المرور أو طرق التحقّق الأخرى للتحقُّق من المستخدم. يمكن أن يكون email_verfied صحيحًا أيضًا حيث أثبتت Google هوية المستخدم في البداية عند إنشاء حساب Google، ولكن ربما تغيرت ملكية حساب البريد الإلكتروني التابع لجهة خارجية منذ ذلك الحين.

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

التحديد_حسب

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

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

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

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

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

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

القيمة الوصف
auto تسجيل الدخول التلقائي لمستخدم لديه جلسة حالية سبق له منح الموافقة على مشاركة بيانات الاعتماد
user ضغط أحد المستخدمين الذين لديهم جلسة حالية وكان قد سبق له الموافقة على الزر "متابعة باسم" بنقرة واحدة لمشاركة بيانات الاعتماد.
user_1tap ضغط أحد المستخدمين الذين لديهم جلسة حالية على الزر "متابعة باسم" بنقرة واحدة لمنح الموافقة ومشاركة بيانات الاعتماد. ولا يسري هذا الإعداد إلا على الإصدار 75 من Chrome والإصدارات الأحدث.
user_2tap ضغط مستخدم ليس لديه جلسة حالية على الزر "متابعة باسم" بنقرة واحدة لاختيار حساب، ثم ضغط على زر "التأكيد" في نافذة منبثقة لمنح الموافقة ومشاركة بيانات الاعتماد. ينطبق ذلك على المتصفحات التي لا تستند إلى Chromium.
btn هناك مستخدم لديه جلسة حالية منح الموافقة من قبل ضغط على زر "تسجيل الدخول باستخدام حساب Google" واختَر حسابًا على Google من الخيار "اختيار حساب" لمشاركة بيانات الاعتماد.
btn_confirm ضغط أحد المستخدمين الذين لديهم جلسة حالية على زر "تسجيل الدخول باستخدام حساب Google" وضغط على الزر "تأكيد" لمنح الموافقة ومشاركة بيانات الاعتماد.
btn_add_session ضغط مستخدم ليس لديه جلسة حالية وكان في السابق على الموافقة على زر "تسجيل الدخول باستخدام حساب Google" لاختيار حساب Google ومشاركة بيانات الاعتماد.
btn_confirm_add_session ضغط مستخدم ليس لديه جلسة حالية على زر "تسجيل الدخول باستخدام حساب Google" أولاً لاختيار حساب Google، ثم ضغط على الزر "تأكيد" للموافقة ومشاركة بيانات الاعتماد.

الطريقة: google.accounts.id.renderButton

تعرض طريقة google.accounts.id.renderButton زر "تسجيل الدخول باستخدام حساب Google" في صفحاتك على الويب.

اطّلِع على مثال الرمز التالي للطريقة:

google.accounts.id.renderButton(
      /** @type{!HTMLElement} */ parent,
      /** @type{!GsiButtonConfiguration} */ options
    )

نوع البيانات: GsiButtonConfiguration

يسرد الجدول التالي الحقول وأوصاف نوع بيانات GsiButtonConfiguration:

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

أنواع السمات

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

كتابة

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

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

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

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

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

مظهر

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

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

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

المظهر
outline
مظهر زر عادي.
filled_blue
مظهر لزر باللون الأزرق.
filled_black
مظهر زر أسود اللون.

size

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

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

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

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

text

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

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

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

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

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

shape

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

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

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

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

محاذاة_الشعار

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

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

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

محاذاة_الشعار
left
محاذاة شعار Google إلى اليسار
center
محاذاة شعار Google إلى الوسط.

width

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

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

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

locale

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

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

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

النوع حقل مطلوب مثال
سلسلة إجراء اختياري locale: "zh_CN"

مستمع_النقرة

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

  google.accounts.id.renderButton(document.getElementById("signinDiv"), {
      theme: 'outline',
      size: 'large',
      click_listener: onClickHandler
    });

  
  function onClickHandler(){
    console.log("Sign in with Google button clicked...")
  }

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

نوع البيانات: بيانات الاعتماد

عند استدعاء الدالة native_callback، يتم تمرير كائن Credential كمَعلمة. يسرد الجدول التالي الحقول المضمّنة في الكائن:

الحقل
id تحدِّد هوية المستخدم.
password كلمة المرور

الطريقة: google.accounts.id.disableAutoSelect

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

google.accounts.id.disableAutoSelect()

في ما يلي مثال على الرمز البرمجي لتنفيذ الطريقة google.accounts.id.disableAutoSelect مع الدالة onSignout():

<script>
  function onSignout() {
    google.accounts.id.disableAutoSelect();
  }
</script>

الطريقة: google.accounts.id.storeCredential

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

google.accounts.id.storeCredential(Credential, callback)

في ما يلي مثال على الرمز البرمجي لتنفيذ الطريقة google.accounts.id.storeCredential مع الدالة onSignIn():

<script>
  function onSignIn() {
    let cred = {id: '...', password: '...'};
    google.accounts.id.storeCredential(cred);
  }
</script>

الطريقة: google.accounts.id.cancel

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

google.accounts.id.cancel()

ينفّذ مثال الرمز التالي طريقة google.accounts.id.cancel() باستخدام الدالة onNextButtonClicked():

<script>
  function onNextButtonClicked() {
    google.accounts.id.cancel();
    showPasswordPage();
  }
</script>

معاودة الاتصال بتحميل المكتبة: onGoogleLibraryLoad

يمكنك تسجيل معاودة الاتصال عبر onGoogleLibraryLoad. ويتم إرسال إشعار إليه بعد تحميل مكتبة "تسجيل الدخول باستخدام Google JavaScript":

window.onGoogleLibraryLoad = () => {
    ...
};

معاودة الاتصال هذه ليست سوى اختصار لمعاودة الاتصال على "window.onload". لا توجد اختلافات في السلوك.

ينفّذ مثال الرمز التالي استدعاء onGoogleLibraryLoad:

<script>
  window.onGoogleLibraryLoad = () => {
   google.accounts.id.initialize({
     ...
   });
   google.accounts.id.prompt();
  };
</script>

الطريقة: google.accounts.id.revoke

تؤدي الطريقة google.accounts.id.revoke إلى إبطال منح بروتوكول OAuth المستخدَم لمشاركة الرمز المميّز للمعرّف للمستخدم المُحدّد. اطّلِع على مقتطف الرمز التالي للطريقة: javascript google.accounts.id.revoke(login_hint, callback)

المَعلمة النوع الوصف
login_hint سلسلة عنوان البريد الإلكتروني أو المعرّف الفريد لحساب المستخدم على Google. المعرّف هو السمة sub لحمولة بيانات الاعتماد.
callback function معالج RevocationResponse الاختياري

يوضّح نموذج الرمز البرمجي التالي كيفية استخدام طريقة revoke مع معرّف. 

  google.accounts.id.revoke('1618033988749895', done => {
    console.log(done.error);
  });

نوع البيانات: RevocationResponse

عند استدعاء دالة callback، يتم تمرير كائن RevocationResponse باعتباره معلَمة. يسرد الجدول التالي الحقول الموجودة في كائن الاستجابة للإبطال:

الحقل
successful هذا الحقل هو القيمة المعروضة لاستدعاء الطريقة.
error يحتوي هذا الحقل اختياريًا على رسالة مفصلة للاستجابة عن الخطأ.

ناجح

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

خطأ

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