browser.permissions

الوصف

استخدِم واجهة برمجة التطبيقات chrome.permissions لطلب الأذونات الاختيارية المُعلَن عنها في وقت التشغيل بدلاً من وقت التثبيت، لكي يفهم المستخدمون سبب الحاجة إلى الأذونات ويمنحوا الأذونات الضرورية فقط.

المفاهيم والاستخدام

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

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

زر إضافة يتيح ميزات إضافية
زرّ إضافة يتيح ميزات إضافية

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

تحذير بشأن إضافة لواجهة برمجة التطبيقات topSites API
تحذير بشأن إضافة لواجهة برمجة التطبيقات topSites

تنفيذ الأذونات الاختيارية

الخطوة 1: تحديد الأذونات المطلوبة والأذونات الاختيارية

يمكن أن تطلب الإضافة أذونات مطلوبة واختيارية. بشكل عام، عليك إجراء ما يلي:

  • استخدِم الأذونات المطلوبة عندما تكون ضرورية لوظائف الإضافة الأساسية.
  • استخدِم الأذونات الاختيارية عندما تكون مطلوبة للميزات الاختيارية في الإضافة.

مزايا الأذونات المطلوبة:

  • طلبات أقل: يمكن أن تطلب الإضافة من المستخدم مرة واحدة قبول جميع الأذونات.
  • تطوير أبسط: نضمن لك توفُّر الأذونات المطلوبة.

مزايا الأذونات الاختيارية:

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

الخطوة 2: الإعلان عن الأذونات الاختيارية في ملف البيان

يمكنك الإعلان عن الأذونات الاختيارية في ملف بيان الإضافة باستخدام المفتاح optional_permissions، مع استخدام التنسيق نفسه المستخدَم في حقل الأذونات:

{
  "name": "My extension",
  ...
  "optional_permissions": ["tabs"],
  "optional_host_permissions": ["https://www.google.com/"],
  ...
}

إذا أردت طلب مضيفين تكتشفهم فقط في وقت التشغيل، يمكنك تضمين "https://*/*" في حقل optional_host_permissions الخاص بالإضافة. يتيح لك ذلك تحديد أي مصدر في "Permissions.origins" طالما أنّه يتضمّن مخططًا مطابقًا.

الأذونات التي لا يمكن تحديدها على أنّها اختيارية

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

الإذن الوصف
"debugger" تُستخدَم واجهة برمجة التطبيقات browser.debugger كطريقة بديلة لنقل البيانات في بروتوكول تصحيح الأخطاء عن بُعد في Chrome.
"declarativeNetRequest" يمنح الإضافة إذن الوصول إلى واجهة برمجة التطبيقات browser.declarativeNetRequest.
"devtools" تسمح هذه الإضافة بتوسيع وظائف أدوات مطوّري البرامج في Chrome.
"geolocation" يسمح هذا الإذن للإضافة باستخدام واجهة برمجة التطبيقات الموقع الجغرافي في HTML5.
"mdns" يمنح الإضافة إذن الوصول إلى واجهة برمجة التطبيقات browser.mdns.
"proxy" يمنح الإضافة إذن الوصول إلى واجهة برمجة التطبيقات browser.proxy لإدارة إعدادات الخادم الوكيل في Chrome.
"tts" تُشغِّل واجهة برمجة التطبيقات browser.tts ميزة "تحويل النص إلى كلام" (TTS) المُركَّبة.
"ttsEngine" تنفِّذ واجهة برمجة التطبيقات browser.ttsEngine محرّك تحويل النص إلى كلام (TTS) باستخدام إضافة.
"wallpaper" نظام التشغيل Chrome فقط: استخدِم واجهة برمجة التطبيقات browser.wallpaper لتغيير خلفية نظام التشغيل ChromeOS.

يمكنك الاطّلاع على الإفصاح عن الأذونات لمزيد من المعلومات حول الأذونات المتاحة وتحذيراتها.

الخطوة 3: طلب الأذونات الاختيارية

اطلب الأذونات من خلال إجراء تفاعلي من المستخدم باستخدام permissions.request():

document.querySelector('#my-button').addEventListener('click', (event) => {
  // Permissions must be requested from inside a user gesture, like a button's
  // click handler.
  browser.permissions.request({
    permissions: ['tabs'],
    origins: ['https://www.google.com/']
  }, (granted) => {
    // The callback argument will be true if the user granted the permissions.
    if (granted) {
      doSomething();
    } else {
      doSomethingElse();
    }
  });
});

يطلب Chrome من المستخدم إذا كانت إضافة الأذونات تؤدي إلى ظهور رسائل تحذير مختلفة عن تلك التي رآها المستخدم وقبلها من قبل. على سبيل المثال، قد ينتج عن الرمز السابق طلب مثل هذا:

مثال على طلب تأكيد الإذن
مثال على طلب تأكيد الإذن

الخطوة 4: التحقّق من الأذونات الحالية للإضافة

للتحقّق مما إذا كانت الإضافة تتضمّن إذنًا معيّنًا أو مجموعة من الأذونات، استخدِم permission.contains():

browser.permissions.contains({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (result) => {
  if (result) {
    // The extension has the permissions.
  } else {
    // The extension doesn't have the permissions.
  }
});

الخطوة 5: إزالة الأذونات

يجب إزالة الأذونات عندما لا تعود بحاجة إليها. بعد إزالة أحد الأذونات، يؤدي استدعاء permissions.request() عادةً إلى إعادة إضافة الإذن بدون مطالبة المستخدم بذلك.

browser.permissions.remove({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (removed) => {
  if (removed) {
    // The permissions have been removed.
  } else {
    // The permissions have not been removed (e.g., you tried to remove
    // required permissions).
  }
});

الأنواع

Permissions

الخصائص

  • المصادر

    string[] اختياري

    قائمة أذونات المضيف، بما في ذلك الأذونات المحدّدة في مفتاحَي optional_permissions أو permissions في البيان، وتلك المرتبطة بنصوص المحتوى البرمجية.

  • أذونات

    string[] اختياري

    قائمة بالأذونات المُسمّاة (لا تتضمّن المضيفين أو المصادر).

الطُرق

addHostAccessRequest()

الإصدار 133 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome MV3 والإصدارات الأحدث 
browser.permissions.addHostAccessRequest(
  request: object,
): Promise<void>

يضيف طلب وصول إلى المضيف. لن يتم إرسال الطلب إلى المستخدم إلا إذا كان من الممكن منح الإضافة إذن الوصول إلى المضيف في الطلب. ستتم إعادة ضبط الطلب عند التنقّل بين مصادر متعددة. عند قبول الطلب، يتم منح إذن وصول دائم إلى المصدر الرئيسي للموقع الإلكتروني

المعلمات

  • طلب

    عنصر

    • documentId

      string اختياري

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

    • نقش

      string اختياري

      نمط عنوان URL الذي يمكن عرض طلبات الوصول إلى المضيف فيه في حال توفيره، لن تظهر طلبات الوصول إلى المضيف إلا على عناوين URL التي تتطابق مع هذا النمط.

    • tabId

      number اختيارية

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

المرتجعات

  • وعد<فراغ>

contains()

browser.permissions.contains(
  permissions: Permissions,
): Promise<boolean>

يتحقّق هذا الإذن مما إذا كانت الإضافة تملك الأذونات المحدّدة.

المعلمات

المرتجعات

  • Promise<boolean>

    الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

getAll()

browser.permissions.getAll(): Promise<Permissions>

للحصول على مجموعة الأذونات الحالية للإضافة

المرتجعات

  • Promise<Permissions>

    الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

remove()

browser.permissions.remove(
  permissions: Permissions,
): Promise<boolean>

لإزالة إمكانية الوصول إلى الأذونات المحدّدة إذا كانت هناك أي مشاكل في إزالة الأذونات، سيتم رفض الوعد.

المعلمات

المرتجعات

  • Promise<boolean>

    الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

removeHostAccessRequest()

الإصدار 133 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome MV3 والإصدارات الأحدث 
browser.permissions.removeHostAccessRequest(
  request: object,
): Promise<void>

لإزالة طلب وصول المضيف، في حال توفّره

المعلمات

  • طلب

    عنصر

    • documentId

      string اختياري

      رقم تعريف المستند الذي ستتم إزالة طلب الوصول إلى المضيف منه يجب أن يكون المستند ذو المستوى الأعلى ضمن علامة تبويب. يجب تحديد هذه السمة أو tabId.

    • نقش

      string اختياري

      نمط عنوان URL الذي ستتم إزالة طلب الوصول إلى المضيف منه إذا تم توفير هذه القيمة، يجب أن تتطابق تمامًا مع نمط طلب حالي للوصول إلى المضيف.

    • tabId

      number اختيارية

      رقم تعريف علامة التبويب التي ستتم إزالة طلب الوصول إلى المضيف منها يجب تحديد هذه السمة أو documentId.

المرتجعات

  • وعد<فراغ>

request()

browser.permissions.request(
  permissions: Permissions,
): Promise<boolean>

يطلب هذا الإجراء الوصول إلى الأذونات المحدّدة، ويعرض رسالة للمستخدم إذا لزم الأمر. يجب تحديد هذه الأذونات في حقل optional_permissions في ملف البيان أو أن تكون أذونات مطلوبة حجبها المستخدم. وسيتم تجاهل المسارات في أنماط المصدر. يمكنك طلب مجموعات فرعية من أذونات المصدر الاختيارية، على سبيل المثال، إذا حدّدت *://*\/* في قسم optional_permissions من البيان، يمكنك طلب http://example.com/. في حال حدوث أي مشاكل في طلب الأذونات، سيتم رفض الوعد.

المعلمات

المرتجعات

  • Promise<boolean>

    الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الفعاليات

onAdded

browser.permissions.onAdded.addListener(
  callback: function,
)

يتم تنشيط هذا الحدث عندما تحصل الإضافة على أذونات جديدة.

المعلمات

  • callback

    دالة

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

    (permissions: Permissions) => void

onRemoved

browser.permissions.onRemoved.addListener(
  callback: function,
)

يتم تنشيطه عند إزالة إذن الوصول إلى الأذونات من الإضافة.

المعلمات

  • callback

    دالة

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

    (permissions: Permissions) => void