chrome.identity

الوصف

استخدام واجهة برمجة التطبيقات chrome.identity للحصول على رموز الدخول عبر OAuth2

الأذونات

identity

الأنواع

AccountInfo

أماكن إقامة

  • id

    سلسلة

    معرّف فريد للحساب ولن يتغيّر هذا المعرّف طوال فترة بقاء الحساب.

AccountStatus

الإصدار 84 من Chrome والإصدارات الأحدث

التعداد

"SYNC"
يحدد تفعيل "المزامنة" للحساب الأساسي.

"أيّ منهما"
يحدد وجود حساب أساسي، إن وجد.

GetAuthTokenResult

Chrome 105 والإصدارات الأحدث

أماكن إقامة

  • grantedScopes

    سلسلة[] اختيارية

    قائمة بنطاقات OAuth2 الممنوحة للإضافة.

  • رمز مميّز

    سلسلة اختيارية

    الرمز المميّز المرتبط بالطلب.

InvalidTokenDetails

أماكن إقامة

  • رمز مميّز

    سلسلة

    الرمز المميّز الذي يجب إزالته من ذاكرة التخزين المؤقت

ProfileDetails

الإصدار 84 من Chrome والإصدارات الأحدث

أماكن إقامة

  • 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()

الوعد الإصدار 87 من Chrome أو الإصدارات الأحدث 
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 والإصدارات الأحدث

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

getProfileUserInfo()

وعد 
chrome.identity.getProfileUserInfo(
  details?: ProfileDetails,
  callback?: function,
)

يسترد عنوان البريد الإلكتروني ومعرّف GAIA الذي تم تشويشه للمستخدم الذي سجَّل الدخول إلى الملف الشخصي.

يجب الحصول على إذن ملف البيان identity.email. وإلا، سيتم عرض نتيجة فارغة.

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

المَعلمات

  • التفاصيل

    ProfileDetails اختيارية

    الإصدار 84 من Chrome والإصدارات الأحدث

    خيارات الملف الشخصي.

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

    الدالة اختيارية

    تبدو معلَمة callback على النحو التالي: 

    (userInfo: ProfileUserInfo)=>void

المرتجعات

  • 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.

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

المَعلمات

  • التفاصيل

    WebAuthFlowDetails

    خيارات مسار WebAuth

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

    الدالة اختيارية

    تبدو معلَمة callback على النحو التالي: 

    (responseUrl?: string)=>void

    • responseUrl

      سلسلة اختيارية

المرتجعات

  • الوعد<string|unified>

    Chrome 106 والإصدارات الأحدث

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

removeCachedAuthToken()

وعد 
chrome.identity.removeCachedAuthToken(
  details: InvalidTokenDetails,
  callback?: function,
)

تتم إزالة رمز الدخول المميز عبر OAuth2 من ذاكرة التخزين المؤقت للرمز المميز لواجهة برمجة التطبيقات Identity.

وإذا تم اكتشاف أن رمز الدخول غير صالح، يجب تمريره لإزالة cachedAuthToken لإزالته من ذاكرة التخزين المؤقت. قد يسترد التطبيق بعد ذلك رمزًا مميزًا جديدًا باستخدام getAuthToken.

المَعلمات

  • التفاصيل

    InvalidTokenDetails

    معلومات عن الرمز المميّز

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

    الدالة اختيارية

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

    Chrome 106 والإصدارات الأحدث

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

فعاليات

onSignInChanged

chrome.identity.onSignInChanged.addListener(
  callback: function,
)

يتم تنشيطها عندما تتغير حالة تسجيل الدخول لحساب في الملف الشخصي للمستخدم.

المَعلمات

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

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (account: AccountInfo,signedIn: boolean)=>void