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.contains(
  permissions: Permissions,
  callback?: function,
): Promise<boolean>

chrome.permissions.getAll(
  callback?: function,
): Promise<Permissions>

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

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

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

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