chrome.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.
  chrome.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():

chrome.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() عادةً إلى إعادة إضافة الإذن بدون مطالبة المستخدم بذلك.

chrome.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,
)