chrome.identity

الوصف

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

الأذونات

identity

الأنواع

AccountInfo

أماكن إقامة

  • id

    سلسلة

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

AccountStatus

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

Enum

"SYNC"
يحدد هذا الخيار أن المزامنة مفعّلة للحساب الأساسي.

"أيني"
يحدد هذا الحقل وجود حساب أساسي، إن وجد.

GetAuthTokenResult

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

أماكن إقامة

  • grantedScopes

    string[] اختيارية

    قائمة بنطاقات 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 تعذُّر الإجراء في أي وقت يكون فيه الطلب مطلوبًا.

  • النطاقات

    string[] اختيارية

    قائمة بنطاقات OAuth2 المطلوب طلبها.

    عند توفّر الحقل scopes، يتم إلغاء قائمة النطاقات المحدّدة في ملف البيان.json.

WebAuthFlowDetails

أماكن إقامة

  • abortOnLoadForNonInteractive

    قيمة منطقية اختيارية

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

    يمكنك اختيار ما إذا كنت تريد إنهاء launchWebAuthFlow للطلبات غير التفاعلية بعد تحميل الصفحة. ولا تؤثر هذه المعلمة في التدفقات التفاعلية.

    عند ضبط هذه السياسة على true (الخيار التلقائي)، سيتم إنهاء المسار فورًا بعد تحميل الصفحة. عند ضبط السياسة على false، لن ينتهي المسار إلا بعد اجتياز timeoutMsForNonInteractive. يفيد ذلك موفّري الهوية الذين يستخدمون JavaScript لتنفيذ عمليات إعادة التوجيه بعد تحميل الصفحة.

  • تفاعلي

    قيمة منطقية اختيارية

    تحديد ما إذا كان سيتم إطلاق مسار المصادقة في وضع التفاعل.

    وبما أنّ بعض مسارات المصادقة قد تعيد التوجيه مباشرةً إلى عنوان URL لنتيجة البحث، يخفي launchWebAuthFlow طريقة عرضه على الويب إلى أن تتم عملية التنقّل الأولى إما بإعادة التوجيه إلى عنوان URL النهائي أو انتهاء تحميل صفحة سيتم عرضها.

    إذا كانت قيمة علامة interactive هي true، سيتم عرض النافذة عند اكتمال تحميل الصفحة. إذا كانت العلامة false أو تم حذفها، سيتم عرض launchWebAuthFlow مع ظهور خطأ إذا لم يكتمل التنقّل الأولي التدفق.

    بالنسبة إلى التدفقات التي تستخدم JavaScript لإعادة التوجيه، يمكن ضبط abortOnLoadForNonInteractive على false مع الإعداد timeoutMsForNonInteractive لمنح الصفحة فرصة إجراء أي عمليات إعادة توجيه.

  • timeoutMsForNonInteractive

    الرقم اختياري

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

    الحد الأقصى للوقت بالمللي ثانية، الذي يُسمح له بتشغيل launchWebAuthFlow في وضع غير تفاعلي إجمالاً. لن يكون له أي تأثير إلا إذا كانت قيمة interactive هي false.

  • url

    سلسلة

    عنوان URL الذي يبدأ مسار المصادقة.

الطُرق

clearAllCachedAuthTokens()

وعود الإصدار 87 من Chrome أو الإصدارات الأحدث 
chrome.identity.clearAllCachedAuthTokens(
  callback?: function,
)

إعادة ضبط حالة Identity API:

  • إزالة جميع رموز الدخول عبر OAuth2 من ذاكرة التخزين المؤقت للرمز المميز
  • يزيل إعدادات حساب المستخدم المفضّلة
  • يؤدي إلى إلغاء تفويض المستخدم من جميع مسارات المصادقة

المعلمات

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

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

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

getAccounts()

وعود قناة مطوري البرامج 
chrome.identity.getAccounts(
  callback?: function,
)

لاسترداد قائمة بكائنات AccountInfo التي تصف الحسابات المتوفّرة في الملف الشخصي.

لا يتوافق "getAccounts" إلا مع قناة مطوّري البرامج.

المعلمات

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (accounts: AccountInfo[]) => void

المرتجعات

  • Promise&lt;AccountInfo[]&gt;

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

getAuthToken()

وعود 
chrome.identity.getAuthToken(
  details?: TokenDetails,
  callback?: function,
)

يمكن الحصول على رمز دخول OAuth2 باستخدام معرِّف العميل والنطاقات المحدّدة في القسم oauth2 من ملف robots.json.

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

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

ملاحظة: عند استدعائها باستخدام استدعاء، ستعرض هذه الدالة السمتين كوسيطات منفصلة يتم تمريرها إلى رد الاتصال، بدلاً من عرض كائن.

المعلمات

  • التفاصيل

    TokenDetails اختياري

    خيارات الرمز المميّز.

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (result: GetAuthTokenResult) => void

    • نتيجة

      GetAuthTokenResult

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

المرتجعات

  • Promise&lt;GetAuthTokenResult&gt;

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

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

getProfileUserInfo()

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

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

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

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

المعلمات

  • التفاصيل

    ProfileDetails اختياري

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

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

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (userInfo: ProfileUserInfo) => void

المرتجعات

  • Promise&lt;ProfileUserInfo&gt;

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

    تتوفّر الوعود في الإصدار 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 | غير محددة>

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

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

removeCachedAuthToken()

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

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

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

المعلمات

  • التفاصيل

    InvalidTokenDetails

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

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

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

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

فعاليات

onSignInChanged

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

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

المعلمات

  • رد الاتصال

    دالة

    تظهر المَعلمة callback على النحو التالي: 

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