chrome.permissions

الوصف

المفاهيم وطريقة الاستخدام

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

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

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

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

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

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

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

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

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

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

• أمان أفضل: يتم تشغيل الإضافات باستخدام أذونات أقل لأنّ المستخدمين يفعّلون فقط الأذونات التي يحتاجون إليها.
• معلومات أفضل للمستخدمين: يمكن أن توضّح الإضافة سبب احتياجها إلى إذن معيّن عندما يفعّل المستخدم الميزة ذات الصلة.
• عمليات الترقية الأسهل: عند ترقية إضافتك، لن يوقف 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.addSiteAccessRequest(
  request: object,
  callback?: function,
)

chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

chrome.permissions.getAll(
  callback?: function,
)

chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)

chrome.permissions.removeSiteAccessRequest(
  request: object,
  callback?: function,
)

chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
)

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

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