الوصف
استخدام واجهة برمجة التطبيقات chrome.identity
للحصول على رموز الدخول عبر OAuth2
الأذونات
identity
الأنواع
AccountInfo
أماكن إقامة
-
id
سلسلة
معرّف فريد للحساب ولن يتغيّر هذا المعرّف طوال فترة بقاء الحساب.
AccountStatus
التعداد
"SYNC"
يحدد تفعيل "المزامنة" للحساب الأساسي.
"أيّ منهما"
يحدد وجود حساب أساسي، إن وجد.
GetAuthTokenResult
أماكن إقامة
-
grantedScopes
سلسلة[] اختيارية
قائمة بنطاقات OAuth2 الممنوحة للإضافة.
-
رمز مميّز
سلسلة اختيارية
الرمز المميّز المرتبط بالطلب.
InvalidTokenDetails
أماكن إقامة
-
رمز مميّز
سلسلة
الرمز المميّز الذي يجب إزالته من ذاكرة التخزين المؤقت
ProfileDetails
أماكن إقامة
-
accountStatus
AccountStatus اختيارية
حالة الحساب الأساسي الذي تم تسجيل الدخول إليه في ملف شخصي يجب عرض
ProfileUserInfo
الخاص به. الإعداد التلقائي هو حالة حسابSYNC
.
ProfileUserInfo
أماكن إقامة
-
بريد إلكتروني
سلسلة
عنوان بريد إلكتروني لحساب المستخدم الذي تم تسجيل الدخول إليه في الملف الشخصي الحالي يكون هذا الحقل فارغًا إذا لم يسجّل المستخدم الدخول أو لم يتم تحديد إذن ملف البيان
identity.email
. -
id
سلسلة
معرّف فريد للحساب ولن يتغيّر هذا المعرّف طوال فترة بقاء الحساب. فارغ في حال عدم تسجيل دخول المستخدم أو (في الإصدار M41 والإصدارات الأحدث)، لم يتم تحديد إذن البيان
identity.email
.
TokenDetails
أماكن إقامة
-
حساب
AccountInfo اختيارية
رقم تعريف الحساب الذي يجب عرض رمزه المميّز. في حال عدم تحديد ذلك، ستستخدم الدالة حسابًا من الملف الشخصي في Chrome: حساب المزامنة في حال توفُّر واحد، أو حساب الويب الأول على Google.
-
enableGranularPermissions
منطقية اختيارية
الإصدار 87 من Chrome والإصدارات الأحدثتسمح علامة
enableGranularPermissions
للإضافات بتفعيل شاشة الموافقة على الأذونات الدقيقة مبكرًا، والتي يتم فيها منح الأذونات المطلوبة أو رفضها بشكل فردي. -
تفاعلي
منطقية اختيارية
قد يتطلب استرجاع رمز مميّز من المستخدم تسجيل الدخول إلى Chrome أو الموافقة على النطاقات المطلوبة للتطبيق. في حال كانت العلامة التفاعلية هي
true
، سيطلبgetAuthToken
من المستخدم حسب الضرورة. وعندما تكون العلامةfalse
أو محذوفة، ستعرضgetAuthToken
رسالة تعذُّر في أي وقت يكون فيه الطلب مطلوبًا. -
النطاقات
سلسلة[] اختيارية
قائمة بنطاقات OAuth2 المطلوبة لطلبها.
وعند توفُّر الحقل
scopes
، يتم إلغاء قائمة النطاقات المحدَّدة في ملفManifest.json.
WebAuthFlowDetails
أماكن إقامة
-
abortOnLoadForNonInteractive
منطقية اختيارية
Chrome 113 والإصدارات الأحدثما إذا كان سيتم إنهاء
launchWebAuthFlow
للطلبات غير التفاعلية بعد تحميل الصفحة. ولا تؤثر هذه المَعلمة في التدفقات التفاعلية.وعند ضبط هذه السياسة على
true
(الخيار التلقائي)، سيتم إنهاء العملية على الفور بعد تحميل الصفحة. في حال ضبط السياسة علىfalse
، سينتهي المسار فقط بعد مرورtimeoutMsForNonInteractive
. وهذا الإجراء مفيد لموفّري الهوية الذين يستخدمون JavaScript لإجراء عمليات إعادة التوجيه بعد تحميل الصفحات. -
تفاعلي
منطقية اختيارية
ما إذا كان سيتم تشغيل تدفق المصادقة في الوضع التفاعلي
بما أنّ بعض مسارات المصادقة قد تعيد التوجيه على الفور إلى عنوان URL لنتيجة البحث، يخفي
launchWebAuthFlow
طريقة عرض الويب الخاصة به إلى أن تعيد عملية التنقّل الأولى التوجيه إلى عنوان URL النهائي أو تنتهي من تحميل صفحة تريد عرضها.إذا كانت العلامة
interactive
هيtrue
، سيتم عرض النافذة عند اكتمال تحميل الصفحة. إذا كانت العلامةfalse
أو تم حذفها، سيعرضlaunchWebAuthFlow
رسالة خطأ إذا لم يكتمل التنقل الأولي للمسار.بالنسبة إلى التدفقات التي تستخدم JavaScript لإعادة التوجيه، يمكن ضبط
abortOnLoadForNonInteractive
علىfalse
مع الإعدادtimeoutMsForNonInteractive
لمنح الصفحة فرصة لإجراء أي عمليات إعادة توجيه. -
timeoutMsForNonInteractive
الرقم اختياري
Chrome 113 والإصدارات الأحدثالحد الأقصى من الوقت بالملي ثانية المسموح به لتشغيل "
launchWebAuthFlow
" في الوضع غير التفاعلي إجمالاً. لن يكون لذلك أي تأثير إلا إذا كانت قيمة السمةinteractive
هيfalse
. -
url
سلسلة
تشير هذه السمة إلى عنوان URL الذي يبدأ مسار المصادقة.
الطُرق
clearAllCachedAuthTokens()
chrome.identity.clearAllCachedAuthTokens(
callback?: function,
)
إعادة ضبط حالة Identity API:
- تتم إزالة جميع رموز الدخول عبر OAuth2 من ذاكرة التخزين المؤقت للرمز المميّز.
- يزيل إعدادات حساب المستخدم المفضّلة
- إلغاء تفويض المستخدم من جميع مسارات المصادقة
المَعلمات
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 106 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
getAccounts()
chrome.identity.getAccounts(
callback?: function,
)
لاسترداد قائمة من كائنات AccountInfo التي تصف الحسابات الموجودة في الملف الشخصي.
"getAccounts
" غير متاح إلا على قناة مطوّري البرامج.
المَعلمات
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(accounts: AccountInfo[]) => void
-
حسابات
-
المرتجعات
-
Promise<AccountInfo[]>
تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
getAuthToken()
chrome.identity.getAuthToken(
details?: TokenDetails,
callback?: function,
)
يمكنك الحصول على رمز دخول OAuth2 باستخدام معرِّف العميل والنطاقات المحدَّدة في قسم oauth2
في ملفManifest.json.
تخزِّن واجهة برمجة التطبيقات Identity رموز الدخول في الذاكرة، وبذلك يمكن استدعاء getAuthToken
بشكل غير تفاعلي في أي وقت يُطلب فيه رمز مميز. تعالج ذاكرة التخزين المؤقت للرمز المميّز تاريخ انتهاء الصلاحية تلقائيًا.
لتقديم تجربة مستخدم جيدة، من المهم أن تبدأ طلبات الرموز المميزة التفاعلية من خلال واجهة المستخدم في تطبيقك لشرح الغرض من التفويض. وسيؤدي عدم إجراء ذلك إلى حصول المستخدمين على طلبات تفويض، أو إلى شاشات تسجيل الدخول إلى Chrome إذا لم يتم تسجيل الدخول، بدون سياق. وعلى وجه الخصوص، يجب عدم استخدام getAuthToken
بشكل تفاعلي عند إطلاق تطبيقك لأول مرة.
ملاحظة: عند استدعاء هذه الدالة باستخدام معاودة الاتصال، بدلاً من عرض كائن، ستعرض هذه الدالة الخاصيتين كوسيطات منفصلة يتم تمريرها إلى رد الاتصال.
المَعلمات
-
التفاصيل
TokenDetails اختياري
خيارات الرمز المميّز.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(result: GetAuthTokenResult) => void
-
نتيجةChrome 105 والإصدارات الأحدث
-
المرتجعات
-
Promise<GetAuthTokenResult>
Chrome 105 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
getProfileUserInfo()
chrome.identity.getProfileUserInfo(
details?: ProfileDetails,
callback?: function,
)
يسترد عنوان البريد الإلكتروني ومعرّف GAIA الذي تم تشويشه للمستخدم الذي سجَّل الدخول إلى الملف الشخصي.
يجب الحصول على إذن ملف البيان identity.email
. وإلا، سيتم عرض نتيجة فارغة.
تختلف واجهة برمجة التطبيقات هذه عن Identity.getAccounts بطريقتين. وتتوفّر المعلومات التي يتم عرضها بلا اتصال بالإنترنت، ولا تنطبق إلا على الحساب الأساسي للملف الشخصي.
المَعلمات
-
التفاصيل
ProfileDetails اختيارية
الإصدار 84 من Chrome والإصدارات الأحدثخيارات الملف الشخصي.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(userInfo: ProfileUserInfo) => void
-
userInfo
-
المرتجعات
-
Promise<ProfileUserInfo>
Chrome 106 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
getRedirectURL()
chrome.identity.getRedirectURL(
path?: string,
)
تنشئ هذه السياسة عنوان URL لإعادة التوجيه ليتم استخدامه في launchWebAuthFlow
.
تتطابق عناوين URL التي تم إنشاؤها مع النمط https://<app-id>.chromiumapp.org/*
.
المَعلمات
-
المسار
سلسلة اختيارية
المسار الذي تم إلحاقه بنهاية عنوان URL الذي تمّ إنشاؤه
المرتجعات
-
سلسلة
launchWebAuthFlow()
chrome.identity.launchWebAuthFlow(
details: WebAuthFlowDetails,
callback?: function,
)
يبدأ مسار المصادقة على عنوان URL المحدد.
تفعِّل هذه الطريقة مسارات المصادقة مع موفّري الهوية غير التابعين لشركة Google من خلال تشغيل عرض ويب والانتقال إلى عنوان URL الأول في مسار المصادقة لدى موفِّر الهوية. عندما يعيد الموفّر التوجيه إلى عنوان URL يطابق النمط https://<app-id>.chromiumapp.org/*
، سيتم إغلاق النافذة وسيتم تمرير عنوان URL النهائي لإعادة التوجيه إلى الدالة callback
.
لتقديم تجربة مستخدم جيدة، من المهمّ بدء تدفقات المصادقة التفاعلية من خلال واجهة المستخدم في تطبيقك لتوضيح الغرض من التفويض. وسيؤدي عدم إجراء ذلك إلى حصول المستخدمين على طلبات تفويض بدون سياق. وعلى وجه الخصوص، لا تشغِّل تدفق مصادقة تفاعليًا عند إطلاق تطبيقك لأول مرة.
المَعلمات
-
التفاصيل
خيارات مسار WebAuth
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(responseUrl?: string) => void
-
responseUrl
سلسلة اختيارية
-
المرتجعات
-
Promise<string | undefined>
Chrome 106 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
removeCachedAuthToken()
chrome.identity.removeCachedAuthToken(
details: InvalidTokenDetails,
callback?: function,
)
تتم إزالة رمز الدخول المميز عبر OAuth2 من ذاكرة التخزين المؤقت للرمز المميز لواجهة برمجة التطبيقات Identity.
وإذا تم اكتشاف أن رمز الدخول غير صالح، يجب تمريره لإزالة cachedAuthToken لإزالته من ذاكرة التخزين المؤقت. قد يسترد التطبيق بعد ذلك رمزًا مميزًا جديدًا باستخدام getAuthToken
.
المَعلمات
-
التفاصيل
معلومات عن الرمز المميّز
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 106 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
فعاليات
onSignInChanged
chrome.identity.onSignInChanged.addListener(
callback: function,
)
يتم تنشيطها عندما تتغير حالة تسجيل الدخول لحساب في الملف الشخصي للمستخدم.
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:(account: AccountInfo, signedIn: boolean) => void
-
حساب
-
signedIn
boolean
-