chrome.identity

refresh date: 2026-09-25 robots: noindex

الوصف

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

الأذونات

identity

الأنواع

AccountInfo

الخصائص

• id

  سلسلة

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

AccountStatus

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

Enum

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

"ANY"
تحدّد وجود حساب أساسي، إن توفّر.

GetAuthTokenResult

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

الخصائص

• grantedScopes

  string[] اختياري

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

• رمز مميز

  string اختياري

  الرمز المميّز المحدّد المرتبط بالطلب

InvalidTokenDetails

الخصائص

• رمز مميز

  سلسلة

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

ProfileDetails

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

الخصائص

• accountStatus

  AccountStatus اختيارية

  حالة الحساب الأساسي الذي تم تسجيل الدخول إليه في ملف شخصي يجب عرض ProfileUserInfo له. يتم ضبطه تلقائيًا على حالة حساب SYNC.

ProfileUserInfo

الخصائص

• البريد الإلكتروني

  سلسلة

  عنوان بريد إلكتروني لحساب المستخدم الذي تم تسجيل الدخول إليه في الملف الشخصي الحالي تكون فارغة إذا لم يسجّل المستخدم الدخول أو لم يتم تحديد إذن البيان identity.email.

• id

  سلسلة

  معرّف فريد للحساب ولن يتغيّر هذا المعرّف طوال مدة استخدام الحساب. ويكون فارغًا إذا لم يسجّل المستخدم الدخول أو إذا لم يتم تحديد إذن بيان identity.email (في الإصدار M41 والإصدارات الأحدث).

TokenDetails

الخصائص

• حساب

  AccountInfo اختياري

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

• enableGranularPermissions

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

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

  تسمح العلامة enableGranularPermissions للإضافات بالموافقة مبكرًا على شاشة طلب الموافقة على الأذونات الدقيقة، حيث يتم منح الأذونات المطلوبة أو رفضها بشكل فردي.

• تفاعلي

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

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

• النطاقات

  string[] اختياري

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

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

WebAuthFlowDetails

الخصائص

• abortOnLoadForNonInteractive

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

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

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

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

• تفاعلي

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

  ما إذا كان سيتم تشغيل عملية المصادقة في وضع التفاعل

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

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

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

• timeoutMsForNonInteractive

  number اختيارية

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

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

• url

  سلسلة

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

الطُرق

clearAllCachedAuthTokens()

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

chrome.identity.clearAllCachedAuthTokens(
  callback?: function,
): Promise<void>

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

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

المعلمات

• callback

  function اختياري

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

  () => void

المرتجعات

• وعد<فراغ>

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

  تعرض هذه الطريقة كائن Promise يتم حله عند محو الحالة.

  لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

getAccounts()

Promise قناة مطوّري البرامج

chrome.identity.getAccounts(
  callback?: function,
): Promise<AccountInfo[]>

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

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

المعلمات

• callback

  function اختياري

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

  (accounts: AccountInfo[]) => void

  • حسابات

    AccountInfo[]

المرتجعات

• Promise<AccountInfo[]>

  لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

getAuthToken()

Promise

chrome.identity.getAuthToken(
  details?: TokenDetails,
  callback?: function,
): Promise<GetAuthTokenResult>

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

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

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

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

المعلمات

• التفاصيل

  ‫TokenDetails اختياري

  خيارات الرموز المميّزة

• callback

  function اختياري

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

  (result: GetAuthTokenResult) => void

  • نتيجة

    GetAuthTokenResult

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

المرتجعات

• Promise<GetAuthTokenResult>

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

  تعرض هذه الطريقة Promise يتم حله باستخدام رمز الدخول OAuth2 كما هو محدّد في البيان، أو يتم رفضه في حال حدوث خطأ. تتم تعبئة المَعلمة grantedScopes منذ الإصدار 87 من Chrome. عند توفّر هذه المَعلمة، فإنّها تحتوي على قائمة بالنطاقات الممنوحة التي تتوافق مع الرمز المميّز الذي تم عرضه.

  لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

getProfileUserInfo()

Promise

chrome.identity.getProfileUserInfo(
  details?: ProfileDetails,
  callback?: function,
): Promise<ProfileUserInfo>

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

يتطلّب ذلك إذن بيان identity.email. وفي حال عدم عرض هذه البيانات، يتم عرض نتيجة فارغة.

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

المعلمات

• التفاصيل

  ‫ProfileDetails اختيارية

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

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

• callback

  function اختياري

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

  (userInfo: ProfileUserInfo) => void

  • userInfo

    ProfileUserInfo

المرتجعات

• Promise<ProfileUserInfo>

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

  تعرض هذه الدالة كائن Promise الذي يتم حله باستخدام ProfileUserInfo لحساب Chrome الأساسي، أو ProfileUserInfo فارغ إذا لم يكن الحساب الذي يتضمّن details المحدّد متوفّرًا.

  لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

getRedirectURL()

chrome.identity.getRedirectURL(
  path?: string,
): string

يتم إنشاء عنوان URL لإعادة التوجيه لاستخدامه في launchWebAuthFlow.

تتطابق عناوين URL التي تم إنشاؤها مع النمط https://<app-id>.chromiumapp.org/*.

المعلمات

• المسار

  string اختياري

  المسار الذي يتم إلحاقه بنهاية عنوان URL الذي تم إنشاؤه

المرتجعات

• سلسلة

launchWebAuthFlow()

Promise

chrome.identity.launchWebAuthFlow(
  details: WebAuthFlowDetails,
  callback?: function,
): Promise<string | undefined>

يبدأ هذا الإذن عملية مصادقة على عنوان URL المحدّد.

تتيح هذه الطريقة تفعيل مسارات المصادقة مع موفّري هوية غير تابعين لـ Google من خلال تشغيل عرض ويب والانتقال إلى عنوان URL الأول في مسار المصادقة الخاص بموفّر الهوية. عندما يعيد مقدّم الخدمة التوجيه إلى عنوان URL يطابق النمط https://<app-id>.chromiumapp.org/*، سيتم إغلاق النافذة، وسيتم تمرير عنوان URL النهائي لإعادة التوجيه إلى الدالة callback.

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

المعلمات

• التفاصيل

  WebAuthFlowDetails

  خيارات مسار WebAuth

• callback

  function اختياري

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

  (responseUrl?: string) => void

  • responseUrl

    string اختياري

المرتجعات

• Promise<string | undefined>

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

  تعرض هذه الطريقة كائن Promise يتم حله باستخدام عنوان URL الذي تمت إعادة توجيهه إلى تطبيقك.

  لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

removeCachedAuthToken()

Promise

chrome.identity.removeCachedAuthToken(
  details: InvalidTokenDetails,
  callback?: function,
): Promise<void>

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

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

المعلمات

• التفاصيل

  InvalidTokenDetails

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

• callback

  function اختياري

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

  () => void

المرتجعات

• وعد<فراغ>

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

  تعرض هذه الطريقة كائن Promise يتم حله عند إزالة الرمز المميّز من ذاكرة التخزين المؤقت.

  لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

الفعاليات

onSignInChanged

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

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

المعلمات

• callback

  دالة

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

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

  • حساب

    AccountInfo

  • signedIn

    قيمة منطقية