chrome.identity

الوصف

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

الأذونات

identity

الأنواع

AccountInfo

الخصائص

  • id

    سلسلة

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

AccountStatus

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

Enum

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

‫"ANY"
تحدّد هذه السمة ما إذا كان هناك حساب أساسي أم لا.

GetAuthTokenResult

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

الخصائص

  • grantedScopes

    string[] اختياري

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

  • رمز مميز

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

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

InvalidTokenDetails

الخصائص

  • رمز مميز

    سلسلة

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

ProfileDetails

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

الخصائص

  • accountStatus

    AccountStatus اختياري

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

ProfileUserInfo

الخصائص

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

    سلسلة

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

  • id

    سلسلة

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

TokenDetails

الخصائص

  • حساب

    AccountInfo اختياري

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

  • enableGranularPermissions

    boolean اختياري

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

    تسمح العلامة 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 خلالها في الوضع غير التفاعلي هو launchWebAuthFlow مللي ثانية. لن يكون لهذه السياسة أي تأثير إلّا إذا كانت قيمة interactive هي false.

  • url

    سلسلة

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

الطُرق

clearAllCachedAuthTokens()

الإصدار 87 من Chrome والإصدارات الأحدث 
chrome.identity.clearAllCachedAuthTokens(): Promise<void>

تعيد هذه الطريقة ضبط حالة Identity API:

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

المرتجعات

  • Promise<void>

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

getAccounts()

قناة الإصدار التجريبي 
chrome.identity.getAccounts(): Promise<AccountInfo[]>

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

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

المرتجعات

getAuthToken()

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

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

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

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

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

المعلمات

  • التفاصيل

    ‫TokenDetails اختياري

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

المرتجعات

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

getProfileUserInfo()

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

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

يتطلّب إذن بيان identity.email. بخلاف ذلك، تعرض نتيجة فارغة.

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

المعلمات

  • التفاصيل

    ProfileDetails اختياري

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

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

المرتجعات

  • Promise<ProfileUserInfo>

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

getRedirectURL()

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

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

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

المعلمات

  • المسار

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

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

المرتجعات

  • سلسلة

launchWebAuthFlow()

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

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

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

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

المعلمات

المرتجعات

  • Promise<string | undefined>

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

removeCachedAuthToken()

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

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

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

المعلمات

المرتجعات

  • Promise<void>

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

الفعاليات

onSignInChanged

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

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

المعلمات

  • callback

    دالة

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

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