chrome.identity

refresh date: 2026-09-25 robots: noindex

الوصف

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

الأذونات

identity

الأنواع

AccountInfo

الخصائص

  • id

    سلسلة

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

AccountStatus

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

تعداد

"مزامنة"
تحدّد ما إذا كانت المزامنة مفعّلة للحساب الأساسي.

ANY
تحدّد هذه السمة ما إذا كان هناك حساب رئيسي، إن وجد.

GetAuthTokenResult

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

الخصائص

  • grantedScopes

    string[] اختياري

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

  • الرمز المميّز

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

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

InvalidTokenDetails

الخصائص

  • الرمز المميّز

    سلسلة

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

ProfileDetails

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

الخصائص

  • accountStatus

    AccountStatus اختياري

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

ProfileUserInfo

الخصائص

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

    سلسلة

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

  • id

    سلسلة

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

TokenDetails

الخصائص

  • حساب

    ‫AccountInfo اختياري

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

  • enableGranularPermissions

    boolean اختياري

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

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

  • تفاعلي

    boolean اختياري

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

  • النطاقات

    string[] اختياري

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

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

WebAuthFlowDetails

الخصائص

  • abortOnLoadForNonInteractive

    boolean اختياري

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

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

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

  • تفاعلي

    boolean اختياري

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

    بما أنّ بعض مسارات المصادقة قد تعيد التوجيه على الفور إلى عنوان 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

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

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

getAccounts()

Promise قناة مطوري البرامج 
chrome.identity.getAccounts(
  callback?: function,
): Promise<AccountInfo[]>

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

لا تتوافق قيمة getAccounts إلا مع قناة الإصدارات التجريبية.

المعلمات

  • callback

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

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

    (accounts: AccountInfo[]) => void

المرتجعات

  • Promise<AccountInfo[]>

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

getAuthToken()

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

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

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

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

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

المعلمات

  • التفاصيل

    ‫TokenDetails اختيارية

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

  • callback

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

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

    (result: GetAuthTokenResult) => void

المرتجعات

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

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

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

getProfileUserInfo()

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

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

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

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

المعلمات

  • التفاصيل

    ProfileDetails اختيارية

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

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

  • callback

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

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

    (userInfo: ProfileUserInfo) => void

المرتجعات

  • Promise<ProfileUserInfo>

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

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

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

getRedirectURL()

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

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

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

المعلمات

  • المسار

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

    المسار الذي تتم إضافته إلى نهاية عنوان URL الذي تم إنشاؤه

المرتجعات

  • سلسلة

launchWebAuthFlow()

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

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

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

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

المعلمات

  • التفاصيل

    WebAuthFlowDetails

    خيارات مسار WebAuth

  • callback

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

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

    (responseUrl?: string) => void

    • responseUrl

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

المرتجعات

  • Promise<string | undefined>

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

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

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

removeCachedAuthToken()

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

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

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

المعلمات

  • التفاصيل

    InvalidTokenDetails

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

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

الفعاليات

onSignInChanged

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

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

المعلمات

  • callback

    دالة

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

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