مرجع عميل JavaScript لتسجيل الدخول بحساب Google

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

إذا واجهت أي مشكلة في استخدام المكتبة، يُرجى الإبلاغ عنها في مستودع GitHub. .

إعداد المصادقة

حمِّل مكتبة منصة Google APIs لإنشاء عنصر gapi:

<script src="https://apis.google.com/js/platform.js?onload=init" async defer></script>

بعد تحميل مكتبة المنصة، حمِّل مكتبة auth2:

function init() {
  gapi.load('auth2', function() {
    /* Ready. Make a call to gapi.auth2.init or some other API */
  });
}

gapi.auth2.init(params)

تبدأ عملية إعداد عنصر GoogleAuth. يجب استدعاء هذه الطريقة قبل استدعاء methods gapi.auth2.GoogleAuth.

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

الوسيطات
params عنصر يحتوي على أزواج مفاتيح وقيم لبيانات إعدادات العميل راجِع gapi.auth2.ClientConfig للاطّلاع على خصائص المختلفّة التي يمكن ضبطها. على سبيل المثال: 
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com'
}
المرتجعات
gapi.auth2.GoogleAuth عنصر gapi.auth2.GoogleAuth استخدِم الأسلوب then() للحصول على وعد يتم حلّه عند انتهاء gapi.auth2.GoogleAuth من الإعداد.

GoogleAuth.then(onInit, onError)

تستدعي الدالة onInit عند بدء GoogleAuth بالكامل. في حال حدوث خطأ أثناء الإعداد (يمكن أن يحدث ذلك في المتصفّحات القديمة غير المتوافقة)، سيتمّ استدعاء الدالة onError بدلاً من ذلك.

الوسيطات
onInit الدالة التي يتمّ استدعاؤها باستخدام العنصر GoogleAuth عند بدء استخدامه بالكامل
onError الدالة التي تمّ استدعاؤها باستخدام عنصر يحتوي على سمة error في حال تعذّر بدء تشغيل GoogleAuth
المرتجعات
وعد Promise يتم تنفيذه عند اكتمال دالة onInit أو رفضه في حال حدوث خطأ في الإعداد. ويتم حلّها باستخدام القيمة المعروضة من الدالة onInit، إن توفّرت.

رموز الخطأ

idpiframe_initialization_failed
تعذّر إعداد إطار iframe مطلوب من Google، على سبيل المثال، بسبب بيئة غير متوافقة ستوفّر سمة details مزيدًا من المعلومات عن الخطأ الذي تمّ رصده.

gapi.auth2.ClientConfig

واجهة تمثّل مَعلمات الضبط المختلفة لطريقة gapi.auth2.init

المعلمات
client_id string مطلوبة معرّف عميل التطبيق، الذي يمكن العثور عليه وإنشاؤه في "وحدة تحكّم واجهة برمجة تطبيقات Google"
cookie_policy string النطاقات التي يجب إنشاء ملفات تعريف ارتباط لتسجيل الدخول إليها إما عنوان URI أو single_host_origin أو none يتم ضبط القيمة تلقائيًا على single_host_origin في حال عدم تحديد أي قيمة.
scope string النطاقات المطلوب الحصول عليها، كسلسلة مفصولة بمسافة اختيارية إذا لم يتم ضبط fetch_basic_profile على خطأ.
fetch_basic_profile boolean استرجاع معلومات الملف الشخصي الأساسية للمستخدمين عند تسجيل الدخول تُضيف "profile" و"email" و "openid" إلى النطاقات المطلوبة. صحيح إذا لم يتم تحديد قيمة.
hosted_domain string نطاق G Suite الذي يجب أن ينتمي إليه المستخدمون لتسجيل الدخول. يمكن للعملاء تعديل هذه القيمة، لذا احرص على التحقّق من صحة قيمة الموقع الإلكتروني المستضاف للمستخدم الذي تم إرجاعه. استخدِم GoogleUser.getHostedDomain() على العميل، ومطالبة hd في رمز التعريف على الخادم للتحقّق من أنّ النطاق هو ما توقعته.
use_fedcm boolean اختياري، الإعداد التلقائي هو True. يمكنك تفعيل استخدام واجهات برمجة تطبيقات FedCM للمتصفّح أو إيقافه أثناء تسجيل الدخول.
ux_mode string وضع تجربة المستخدم المراد استخدامه لعملية تسجيل الدخول سيتم تلقائيًا فتح مسار الموافقة في نافذة منبثقة. القيم الصالحة هي popup وredirect.
redirect_uri string في حال استخدام ux_mode='redirect'، تتيح لك هذه المَعلمة إلغاء القيمة التلقائية لـ redirect_uri التي سيتم استخدامها في نهاية عملية الحصول على الموافقة. القيمة التلقائية redirect_uri هي عنوان URL الحالي الذي تمّت إزالة مَعلمات طلب البحث وجزء التجزئة منه.
enable_granular_consent boolean اختيارية: يشير إلى ما إذا كان سيتم تفعيل أذونات دقيقة. في حال ضبط القيمة على false، سيتم إيقاف أذونات حساب Google الأكثر دقة لمعرّفات عملاء OAuth التي تم إنشاؤها قبل 2019. لن يكون هناك أي تأثير في معرّفات عملاء OAuth التي تم إنشاؤها خلال عام 2019 أو بعده، لأنّه يتم دائمًا تفعيل أذونات أكثر دقة لها.
plugin_name string اختيارية: في حال ضبط هذه القيمة، يمكن لمعرّفات العملاء الجديدة التي تم إنشاؤها قبل 29 تموز (يوليو) 2022 استخدام مكتبة Google Platform Library القديمة. تم تلقائيًا حظر معرّفات العملاء التي تم إنشاؤها حديثًا من استخدام مكتبة Platform Library، ويجب بدلاً من ذلك استخدام مكتبة Google Identity Services الأحدث. يمكنك اختيار أي قيمة، ولكن يُنصح باستخدام اسم وصفي مثل اسم المنتج أو المكوّن الإضافي لتحديده. مثلاً: plugin_name: 'YOUR_STRING_HERE'

المصادقة

‫GoogleAuth هي فئة فردية تقدّم طُرقًا للسماح للمستخدم بتسجيل الدخول باستخدام حساب Google، والحصول على حالة تسجيل الدخول الحالية للمستخدم، والحصول على بيانات محدّدة من الملف الشخصي للمستخدم على Google، وطلب نطاقات إضافية، وتسجيل الخروج من الحساب الحالي.

gapi.auth2.getAuthInstance()

عرض عنصر GoogleAuth يجب بدء عنصر GoogleAuth باستخدام gapi.auth2.init() قبل استدعاء هذه الطريقة.

المرتجعات
gapi.auth2.GoogleAuth عنصر gapi.auth2.GoogleAuth استخدِم هذا العنصر لاستدعاء methods gapi.auth2.GoogleAuth.

GoogleAuth.isSignedIn.get()

تعرِض هذه السمة ما إذا كان المستخدم الحالي مسجِّلاً الدخول.

المرتجعات
منطقي true إذا كان المستخدم مسجِّلاً الدخول، أو false إذا سجّل المستخدم الخروج أو لم يتم بدء GoogleAuth

GoogleAuth.isSignedIn.listen(listener)

انتبِه إلى أي تغييرات في حالة تسجيل الدخول للمستخدم الحالي.

الوسيطات
listener دالة تستخدِم قيمة منطقية يُرسِل listen() true إلى هذه الدالة عندما يسجّل المستخدم الدخول، ويُرسِل false عندما يسجّل المستخدم الخروج.

GoogleAuth.signIn()

سجِّل دخول المستخدم باستخدام الخيارات المحدّدة للعنصر gapi.auth2.init().

المرتجعات
وعد Promise يتمّ تنفيذه باستخدام مثيل GoogleUser عندما يُثبِّت مستخدم الهوية بنجاح ويمنح النطاقات المطلوبة، أو يتمّ رفضه باستخدام عنصر يحتوي على سمة error في حال حدوث خطأ. يُرجى الاطّلاع على القسم التالي للحصول على رموز الخطأ.

رموز الخطأ

يُرجى الاطّلاع على GoogleAuth.signIn(options).

GoogleAuth.signIn(options)

تسجيل دخول المستخدم باستخدام الخيارات المحدّدة

الوسيطات
options يمكنك تنفيذ أحد الإجراءَين التاليَين:
  • عنصر gapi.auth2.SignInOptions يحتوي على أزواج مفاتيح وقيم لمَعلمات تسجيل الدخول على سبيل المثال: 
    {
  scope: 'profile email'
}
  • مثيل gapi.auth2.SigninOptionsBuilder على سبيل المثال:
    options = new gapi.auth2.SigninOptionsBuilder();
options.setAppPackageName('com.example.app');
options.setFetchBasicProfile(True);
options.setPrompt('select_account');
options.setScope('profile').setScope('email');
المرتجعات
وعد Promise يتم تنفيذه باستخدام مثيل GoogleUser عندما يُثبِت مستخدم الهوية بنجاح ويمنح النطاقات المطلوبة، أو يتم رفضه باستخدام عنصر يحتوي على سمة error في حال حدوث خطأ (اطّلِع أدناه على رموز الأخطاء).

رموز الخطأ

popup_closed_by_user
أغلق المستخدم النافذة المنبثقة قبل إكمال عملية تسجيل الدخول.
access_denied
رفض المستخدم الإذن بالنطاقات المطلوبة.
immediate_failed
لا يمكن اختيار أي مستخدم تلقائيًا بدون عرض مسار الموافقة. حدث خطأ عند استخدام signIn مع خيار prompt: 'none'. يجب ألا يكون هذا الخيار مطلوبًا لاستخدامه، لأنّ gapi.auth2.init سيُسجِّل دخول المستخدم تلقائيًا في حال سجَّل الدخول سابقًا خلال جلسة سابقة.

gapi.auth2.SignInOptions

واجهة تمثّل مَعلمات الضبط المختلفة لطريقة GoogleAuth.signIn(options)

المعلمات
prompt string فرض وضع معيّن على مسار الموافقة اختيارية:
القيم المحتمَلة هي:
  • consent
    يطلب خادم التفويض من المستخدم الموافقة قبل عرض المعلومات على التطبيق.
  • select_account
    يطلب خادم التفويض من المستخدم اختيار حساب على Google. يتيح ذلك للمستخدم الذي لديه حسابات متعدّدة الاختيار من بين الحسابات المتعدّدة التي قد تكون لديه جلسات حالية لها.
  • none (غير مقترَح)
    لن يعرض خادم التفويض أي صفحات مصادقة أو موافقة من المستخدم، بل سيعرض خطأً إذا لم يتم مصادقة المستخدم ولم يوافق في السابق على النطاقات المطلوبة.
    بما أنّ gapi.auth2.init سيُسجّل دخول المستخدم تلقائيًا إلى التطبيق في حال تسجيل الدخول من قبل، لن تنجح عادةً عملية الاتصال signIn({prompt: 'none'}).
scope string النطاقات المطلوب الحصول عليها، كسلسلة مفصولة بمسافات، بالإضافة إلى النطاقات المحدّدة فيparam. gapi.auth2.init اختيارية إذا لم يتم ضبط fetch_basic_profile على خطأ.
ux_mode string وضع تجربة المستخدم المراد استخدامه لعملية تسجيل الدخول. سيتم تلقائيًا فتح مسار الموافقة في نافذة منبثقة. القيم الصالحة هي popup وredirect.
redirect_uri string في حال استخدام ux_mode='redirect'، تتيح لك هذه المَعلمة إلغاء القيمة التلقائية لـ redirect_uri التي سيتم استخدامها في نهاية عملية الحصول على الموافقة. القيمة التلقائية للمَعلمة redirect_uri هي عنوان URL الحالي الذي تمّت إزالة مَعلمات طلب البحث وجزء علامة التجزئة منه.

GoogleAuth.signOut()

تسجيل الخروج من الحساب الحالي في التطبيق

المرتجعات
وعد Promise يتم تنفيذه عندما يتم تسجيل الخروج من حساب المستخدم.

GoogleAuth.disconnect()

يؤدي ذلك إلى إبطال جميع النطاقات التي منحها المستخدم.

GoogleAuth.grantOfflineAccess(options)

الحصول على إذن من المستخدم للوصول إلى النطاقات المحدّدة بلا إنترنت

الوسيطات
options gapi.auth2.OfflineAccessOptions كائن يحتوي على أزواج مفتاح/قيمة للمَعلمات على سبيل المثال: 
{
  scope: 'profile email'
}
المرتجعات
وعد Promise يتم تنفيذه عندما يمنح المستخدم النطاقات المطلوبة، من خلال تمرير عنصر يحتوي على رمز التفويض إلى معالج تنفيذ Promise. على سبيل المثال: 
auth2.grantOfflineAccess().then(function(resp) {
  var auth_code = resp.code;
});

رموز الخطأ

popup_closed_by_user
أغلق المستخدم النافذة المنبثقة قبل إكمال مسار الموافقة.
access_denied
رفض المستخدم الإذن بالنطاقات المطلوبة.
immediate_failed
لا يمكن اختيار أي مستخدم تلقائيًا بدون عرض مسار الموافقة. حدث خطأ عند استخدام signIn مع خيار prompt: 'none'. يجب ألا يكون هذا الخيار مطلوبًا لاستخدامه، لأنّ gapi.auth2.init سيُسجّل دخول المستخدم تلقائيًا في حال سجّل الدخول سابقًا خلال جلسة سابقة.

gapi.auth2.OfflineAccessOptions

واجهة تمثّل مَعلمات الضبط المختلفة لطريقة GoogleAuth.grantOfflineAccess(options)

المعلمات
prompt string فرض وضع معيّن على مسار الموافقة اختيارية:
القيم المحتمَلة هي:
  • consent
    يطلب خادم التفويض من المستخدم الموافقة قبل عرض المعلومات على التطبيق.
  • select_account
    يطلب خادم التفويض من المستخدم اختيار حساب على Google. يتيح ذلك للمستخدم الذي لديه حسابات متعدّدة الاختيار من بين الحسابات المتعدّدة التي قد تكون لديه جلسات حالية لها.
scope string النطاقات المطلوب الحصول عليها، كسلسلة مفصولة بمسافات، بالإضافة إلى النطاقات المحدّدة فيparam. gapi.auth2.init اختيارية إذا لم يتم ضبط fetch_basic_profile على خطأ.

GoogleAuth.attachClickHandler(container, options, onsuccess, onfailure)

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

الوسيطات
container رقم تعريف عنصر div أو إشارة إليه لشدّ معالج النقر إليه
options عنصر يحتوي على أزواج مفتاح/قيمة للمَعلمات راجِع GoogleAuth.signIn().
onsuccess الدالة التي يتم استدعاؤها بعد اكتمال عملية تسجيل الدخول.
onfailure الدالة التي يتمّ استدعاؤها في حال تعذّر تسجيل الدخول.

المستخدمون

يمثّل عنصر GoogleUser حساب مستخدم واحدًا. يتم عادةً الحصول على عناصر GoogleUser من خلال طلب GoogleAuth.currentUser.get().

GoogleAuth.currentUser.get()

تعرِض هذه الدالة عنصر GoogleUser الذي يمثّل المستخدم الحالي. يُرجى العِلم أنّه في مثيل GoogleAuth تم إعداده حديثًا، لم يتم ضبط المستخدم الحالي. استخدِم الأسلوب currentUser.listen() أو GoogleAuth.then() للحصول على مثيل GoogleAuth تم إعداده.

المرتجعات
GoogleUser المستخدم الحالي

GoogleAuth.currentUser.listen(listener)

انتبِه إلى التغييرات في currentUser.

الوسيطات
listener دالة تأخذ مَعلمة GoogleUser يُرسِل listen إلى هذه الدالة مثيل GoogleUser عند كل تغيير يُعدِّل currentUser.

GoogleUser.getId()

الحصول على سلسلة المعرّف الفريد للمستخدم

المرتجعات
سلسلة المعرّف الفريد للمستخدم

GoogleUser.isSignedIn()

تعرِض هذه الدالة القيمة true إذا كان المستخدم مسجِّلاً الدخول.

المرتجعات
منطقي صحيح إذا كان المستخدم مسجِّلاً الدخول

GoogleUser.getHostedDomain()

الحصول على نطاق G Suite الخاص بالمستخدم إذا سجّل الدخول باستخدام حساب G Suite

المرتجعات
سلسلة نطاق المستخدم على G Suite

GoogleUser.getGrantedScopes()

الحصول على النطاقات التي منحها المستخدم كسلسلة مفصولة بمسافات

المرتجعات
سلسلة النطاقات التي منحها المستخدم

GoogleUser.getBasicProfile()

الحصول على معلومات الملف الشخصي الأساسية للمستخدم

المرتجعات
gapi.auth2.BasicProfile يمكنك استرداد سمات gapi.auth2.BasicProfile باستخدام الطرق التالية:
  • BasicProfile.getId()
  • BasicProfile.getName()
  • BasicProfile.getGivenName()
  • BasicProfile.getFamilyName()
  • BasicProfile.getImageUrl()
  • BasicProfile.getEmail()

GoogleUser.getAuthResponse(includeAuthorizationData)

احصل على عنصر الاستجابة من جلسة مصادقة المستخدم.

الوسيطات
includeAuthorizationData اختياري: قيمة منطقية تحدّد ما إذا كان يجب عرض رمز دخول والنطاقات دائمًا. لا يتم تلقائيًا عرض رمز الوصول والنطاقات المطلوبة عندما تكون قيمة fetch_basic_profile صحيحة (القيمة التلقائية) ولا يتم طلب أي نطاقات إضافية.
المرتجعات
gapi.auth2.AuthResponse عنصر gapi.auth2.AuthResponse

GoogleUser.reloadAuthResponse()

تفرض إعادة تحميل رمز الوصول، ثم تُرجع وعدًا بالقيمة الجديدة لسمة AuthResponse.

المرتجعات
Promise Promise يتم تنفيذه باستخدام gapi.auth2.AuthResponse الذي تمت إعادة تحميله عند الانتهاء من إعادة تحميل الرمز المميّز OAuth

gapi.auth2.AuthResponse

الردّ الذي تم إرجاعه عند استدعاء الأسلوبين GoogleUser.getAuthResponse(includeAuthorizationData) أو GoogleUser.reloadAuthResponse()

أماكن إقامة
access_token string تم منح رمز الوصول.
id_token string تم منح الرمز المميّز لتعريف المستخدم.
scope string النطاقات الممنوحة في رمز الوصول
expires_in number عدد الثواني إلى أن تنتهي صلاحية رمز الوصول
first_issued_at number الطابع الزمني الذي منَح فيه المستخدم النطاقات المطلوبة لأول مرة
expires_at number الطابع الزمني الذي ستنتهي فيه صلاحية رمز الوصول

GoogleUser.hasGrantedScopes(scopes)

تعرِض القيمة "صحيح" إذا منَح المستخدم النطاقات المحدّدة.

الوسيطات
scopes سلسلة نطاقات مفصولة بمسافات
المرتجعات
منطقي صحيح إذا تم منح النطاقات

GoogleUser.grant(options)

طلب نطاقات إضافية للمستخدم

راجِع GoogleAuth.signIn() للاطّلاع على قائمة المَعلمات ورمز الخطأ.

GoogleUser.grantOfflineAccess(options)

الحصول على إذن من المستخدم للوصول إلى النطاقات المحدّدة بلا إنترنت

الوسيطات
options gapi.auth2.OfflineAccessOptions كائن يحتوي على أزواج مفتاح/قيمة للمَعلمات على سبيل المثال: 
{
  scope: 'profile email'
}

GoogleUser.disconnect()

يؤدي ذلك إلى إبطال جميع النطاقات التي منحها المستخدم للتطبيق.

عناصر واجهة المستخدم

gapi.signin2.render(id, options)

تعرِض هذه السمة زر تسجيل الدخول في العنصر الذي يحمل المعرّف المحدّد، وذلك باستخدام الإعدادات التي يحدّدها عنصر options.

الوسيطات
id معرّف العنصر الذي سيتم عرض زر تسجيل الدخول فيه.
options عنصر يحتوي على الإعدادات التي سيتم استخدامها لعرض الزر على سبيل المثال: 
{
  scope: 'email',
  width: 200,
  height: 50,
  longtitle: true,
  theme: 'dark',
  onsuccess: handleSuccess,
  onfailure: handleFailure
}
يمكنك تحديد الخيارات التالية:
المعلمات
نطاق النطاقات المطلوب الحصول عليها عند تسجيل المستخدم الدخول (القيمة التلقائية: profile).
العرض عرض الزر بالبكسل (القيمة التلقائية: 120).
الطول ارتفاع الزر بالبكسل (القيمة التلقائية: 36).
longtitle عرض تصنيفات طويلة، مثل "تسجيل الدخول باستخدام حساب Google" بدلاً من "تسجيل الدخول" (الرمز التلقائي: false). عند استخدام عناوين طويلة، يجب زيادة عرض الزر عن قيمته التلقائية.
مظهر مظهر اللون للزر: إما light أو dark (الإعداد التلقائي: light).
onsuccess دالة ردّ الاتصال التي يتمّ استدعاؤها عندما يسجّل المستخدِم الدخول بنجاح. يجب أن تأخذ هذه الدالة وسيطة واحدة: مثيل من gapi.auth2.GoogleUser (القيمة التلقائية: لا شيء).
onfailure دالّة ردّ الاتصال التي يتمّ استدعاؤها عند تعذُّر تسجيل الدخول لا تأخذ هذه الدالة أي وسيطات (القيمة التلقائية: لا شيء).

متقدّمة

gapi.auth2.authorize(params, callback)

تُجري عملية تفويض OAuth 2.0 لمرة واحدة. استنادًا إلى المَعلمات المستخدَمة، سيؤدي ذلك إلى فتح نافذة منبثقة لمسار تسجيل الدخول إلى Google أو محاولة تحميل الردّ المطلوب بدون تفاعل من المستخدم.

تشمل بعض حالات الاستخدام التي تكون فيها هذه الطريقة مفيدة ما يلي:

  • ما على تطبيقك سوى طلب نقطة نهاية لواجهة برمجة تطبيقات Google مرة واحدة، مثلاً لتحميل فيديوهات YouTube المفضّلة للمستخدم في المرة الأولى التي يسجّل فيها الدخول.
  • يحتوي تطبيقك على البنية الأساسية لإدارة الجلسات، ولا يحتاج سوى إلى رمز التعريف مرة واحدة لتحديد هوية المستخدم في الخلفية.
  • يتم استخدام عدة معرّفات عملاء في الصفحة نفسها.
الوسيطات
params عنصر يحتوي على أزواج مفتاح/قيمة لبيانات الضبط راجِع gapi.auth2.AuthorizeConfig للاطّلاع على الخصائص المختلفة التي يمكن ضبطها. على سبيل المثال: 
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com',
  scope: 'email profile openid',
  response_type: 'id_token permission'
}
callback دالة يتمّ استدعاؤها باستخدام gapi.auth2.AuthorizeResponse بعد اكتمال الطلب (سواءً بنجاح أو تعذّر إكماله).

مثال

gapi.auth2.authorize({
  client_id: 'CLIENT_ID.apps.googleusercontent.com',
  scope: 'email profile openid',
  response_type: 'id_token permission'
}, function(response) {
  if (response.error) {
    // An error happened!
    return;
  }
  // The user authorized the application for the scopes requested.
  var accessToken = response.access_token;
  var idToken = response.id_token;
  // You can also now use gapi.client to perform authenticated requests.
});

رموز الخطأ

idpiframe_initialization_failed
تعذّر إعداد إطار iframe مطلوب من Google، على سبيل المثال، بسبب بيئة غير متوافقة ستوفّر سمة details مزيدًا من المعلومات عن الخطأ الذي تمّ رصده.
popup_closed_by_user
أغلق المستخدم النافذة المنبثقة قبل إكمال عملية تسجيل الدخول.
access_denied
رفض المستخدم الإذن بالنطاقات المطلوبة.
immediate_failed
لا يمكن اختيار أي مستخدم تلقائيًا بدون عرض مسار الموافقة. حدث خطأ عند استخدام signIn مع خيار prompt: 'none'.

gapi.auth2.AuthorizeConfig

واجهة تمثّل مَعلمات الضبط المختلفة لطريقة gapi.auth2.authorize

أماكن إقامة
client_id string مَعلمة مطلوبة. معرّف عميل التطبيق، الذي يمكن العثور عليه وإنشاؤه في "وحدة تحكّم واجهة برمجة تطبيقات Google"
scope string مَعلمة مطلوبة. النطاقات المطلوب الحصول عليها، كسلسلة مفصولة بمسافة
response_type string قائمة بأنواع الردود مع الفصل بينها بمسافات الإعداد التلقائي هو 'permission'. القيم المحتملة هي:
  • id_token، لاسترداد رمز تعريف
  • permission (أو token)، لاسترداد رمز دخول
  • code، لاسترداد رمز التفويض
prompt string فرض وضع معيّن على مسار الموافقة القيم المحتمَلة هي:
  • consent
    يطلب خادم التفويض من المستخدم الموافقة قبل عرض المعلومات على التطبيق.
  • select_account
    يطلب خادم التفويض من المستخدم اختيار حساب على Google. يتيح ذلك للمستخدم الذي لديه حسابات متعدّدة الاختيار من بين الحسابات المتعدّدة التي قد تكون لديه جلسات حالية لها.
  • none
    لن يعرض خادم التفويض أي صفحات مصادقة أو موافقة من المستخدم، بل سيعرض رسالة خطأ إذا لم يتم مصادقة المستخدم ولم يوافق من قبل على النطاقات المطلوبة.
    إذا تم طلب code كنوع استجابة، لن يكون بالإمكان سوى استبدال الرمز الذي يتم إرجاعه برمز access_token، وليس refresh_token.
cookie_policy string النطاقات التي يجب إنشاء ملفات تعريف ارتباط لتسجيل الدخول فيها إما عنوان URI أو single_host_origin أو none يتم ضبط القيمة تلقائيًا على single_host_origin في حال عدم تحديد أي قيمة.
hosted_domain string نطاق G Suite الذي يجب أن ينتمي إليه المستخدمون لتسجيل الدخول. يمكن للعملاء تعديل هذه السمة، لذا احرص على التحقّق من ملكية الموقع الإلكتروني المستضاف للمستخدم الذي تم إرجاعه.
login_hint string عنوان البريد الإلكتروني أو رقم تعريف المستخدم الذي سيتم اختياره مسبقًا في مسار تسجيل الدخول. يمكن للمستخدم تعديل هذه القيمة ما لم يتم استخدام prompt: "none".
include_granted_scopes boolean يحدد هذا الخيار ما إذا كان سيتم طلب رمز دخول يتضمّن جميع النطاقات التي منحها المستخدم سابقًا للتطبيق، أو النطاقات المطلوبة فقط في المكالمة الحالية. الإعداد التلقائي هو true.
enable_granular_consent boolean اختيارية: يشير إلى ما إذا كان سيتم تفعيل أذونات دقيقة. في حال ضبط القيمة على false، سيتم إيقاف أذونات حساب Google الأكثر دقة لمعرّفات عملاء OAuth التي تم إنشاؤها قبل 2019. لن يكون هناك أي تأثير في معرّفات عملاء OAuth التي تم إنشاؤها خلال عام 2019 أو بعده، لأنّه يتم دائمًا تفعيل أذونات أكثر دقة لها.
plugin_name string اختيارية: في حال ضبطها، يمكن لمعرّفات العملاء التي تم إنشاؤها قبل 29 تموز (يوليو) 2022 استخدام Google Platform Library. يتم تلقائيًا حظر معرّفات العملاء التي تم إنشاؤها حديثًا من استخدام مكتبة Platform Library، ويجب بدلاً من ذلك استخدام مكتبة Google Identity Services الأحدث. يمكنك اختيار أي قيمة، ولكن يُنصح باستخدام اسم وصفي مثل اسم المنتج أو المكوّن الإضافي لتسهيل التعرّف عليه. مثلاً: plugin_name: 'YOUR_STRING_HERE'

gapi.auth2.AuthorizeResponse

الردّ الذي تم إرجاعه إلى طريقة ردّ الاتصال gapi.auth2.authorize

أماكن إقامة
access_token string تم منح رمز الوصول. لا تظهر إلا إذا تم تحديد permission أو token في response_type.
id_token string تم منح الرمز المميّز لتعريف المستخدم. لا يظهر هذا الحقل إلا إذا تم تحديد id_token في response_type.
code string تم منح رمز التفويض. لا يظهر هذا الحقل إلا إذا تم تحديد code في response_type.
scope string النطاقات الممنوحة في رمز الوصول لا تظهر هذه السمة إلا إذا تم تحديد permission أو token في response_type.
expires_in number عدد الثواني إلى أن تنتهي صلاحية رمز الوصول لا تظهر هذه السمة إلا إذا تم تحديد permission أو token في response_type.
first_issued_at number الطابع الزمني الذي منَح فيه المستخدم النطاقات المطلوبة لأول مرة لا تظهر إلا إذا كان permission أو token محدّدًا في response_type.
expires_at number الطابع الزمني الذي ستنتهي فيه صلاحية رمز الوصول لا تظهر هذه السمة إلا إذا تم تحديد permission أو token في response_type.
error string عندما يتعذّر تنفيذ الطلب، يحتوي هذا الحقل على رمز الخطأ.
error_subtype string عندما يتعذّر تنفيذ الطلب، يمكن أن يحتوي ذلك على معلومات إضافية عن رمز الخطأ الذي تم تسجيله أيضًا.