browser.permissions

الوصف

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

تتوفّر تحذيرات الأذونات لوصف الإمكانات التي يمنحها أحد واجهات برمجة التطبيقات، ولكن قد لا تكون بعض هذه التحذيرات واضحة. تسمح واجهة Permissions 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 على أنّها اختيارية، باستثناء ما يلي.

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

الخطوة 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).
  }
});

chrome.permissions.addHostAccessRequest(
  request: object,
): Promise<void>

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

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

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

chrome.permissions.removeHostAccessRequest(
  request: object,
): Promise<void>

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

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

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