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 بالمللي ثانية. لن يكون لهذه السياسة أي تأثير إلّا إذا كانت قيمة interactive هي false.

• url

  سلسلة

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

الطُرق

clearAllCachedAuthTokens()

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

chrome.identity.clearAllCachedAuthTokens(): Promise<void>

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

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

المرتجعات

• Promise<void>

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

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

getAccounts()

قناة الإصدار التجريبي

chrome.identity.getAccounts(): Promise<AccountInfo[]>

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

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

المرتجعات

• Promise<AccountInfo[]>

getAuthToken()

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

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

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

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

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

المعلمات

• التفاصيل

  ‫TokenDetails اختياري

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

المرتجعات

• Promise<GetAuthTokenResult>

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

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

getProfileUserInfo()

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

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

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

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

المعلمات

• التفاصيل

  ProfileDetails اختياري

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

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

المرتجعات

• Promise<ProfileUserInfo>

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

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

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.

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

المعلمات

• التفاصيل

  WebAuthFlowDetails

  خيارات عملية WebAuth

المرتجعات

• Promise<string | undefined>

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

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

removeCachedAuthToken()

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

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

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

المعلمات

• التفاصيل

  InvalidTokenDetails

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

المرتجعات

• Promise<void>

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

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

الفعاليات

onSignInChanged

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

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

المعلمات

• callback

  دالة

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

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

  • حساب

    AccountInfo

  • signedIn

    قيمة منطقية