مرجع عميل 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
تعذّر على Google إعداد إطار iframe مطلوب، بسبب بيئة غير متوافقة مثلاً. ستوفّر سمة 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 جلب معلومات الملف الشخصي الأساسية للمستخدمين عند تسجيل الدخول إضافة "الملف الشخصي" و"البريد الإلكتروني" و"فتح المعرّف" إلى النطاقات المطلوبة. صواب إذا لم يتم تحديده.
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 القديمة. تم تلقائيًا حظر معرّفات العملاء التي تم إنشاؤها حديثًا من استخدام مكتبة 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 وضع تجربة المستخدم (UX) المطلوب استخدامه لتسجيل الدخول. سيتم تلقائيًا فتح مسار الموافقة في نافذة منبثقة. القيم الصالحة هي 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 النطاقات المطلوب طلبها، كسلسلة مفصولة بمسافات، بالإضافة إلى النطاقات المحدّدة في مَعلمات 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).
العنوان الطويل عرض تصنيفات طويلة، مثل "تسجيل الدخول باستخدام حساب Google" بدلاً من "تسجيل الدخول" (الرمز التلقائي: false). عند استخدام عناوين طويلة، يجب زيادة عرض الزر عن قيمته التلقائية.
مظهر مظهر اللون للزر: إما light أو dark (الإعداد التلقائي: light).
نجاح دالة ردّ الاتصال التي يتمّ استدعاؤها عندما يسجّل المستخدِم الدخول بنجاح. يجب أن تأخذ هذه الدالة وسيطة واحدة: مثيل من gapi.auth2.GoogleUser (القيمة التلقائية: لا شيء).
onfailure دالة ردّ الاتصال التي يتمّ استدعاؤها عند تعذُّر تسجيل الدخول لا تأخذ هذه الدالة أي وسيطات (القيمة التلقائية: لا شيء).

متقدّمة

gapi.auth2.تفويض(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
تعذّر على Google إعداد إطار iframe مطلوب، بسبب بيئة غير متوافقة مثلاً. ستوفّر سمة 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 عندما يتعذّر تنفيذ الطلب، يمكن أن يحتوي ذلك على معلومات إضافية عن رمز الخطأ الذي تم تسجيله أيضًا.