chrome.permissions

الوصف

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

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

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

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

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

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

تحذير بشأن إضافة واجهة برمجة تطبيقات 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"	تعمل واجهة برمجة التطبيقات chrome.debugger كوسيلة نقل بديلة لبروتوكول تصحيح الأخطاء عن بُعد في Chrome.
"declarativeNetRequest"	لمنح الإضافة إمكانية الوصول إلى واجهة برمجة التطبيقات chrome.declarativeNetRequest.
"devtools"	تسمح هذه الإضافة بتوسيع وظائف أدوات مطوري البرامج في Chrome.
"geolocation"	يسمح للإضافة باستخدام واجهة برمجة تطبيقات geolocation في HTML5.
"mdns"	يمنح الإضافة إمكانية الوصول إلى واجهة برمجة التطبيقات chrome.mdns.
"proxy"	سيتم منح الإضافة الإذن بالوصول إلى واجهة برمجة التطبيقات chrome.proxy لإدارة إعدادات الخادم الوكيل في Chrome.
"tts"	تُشغّل واجهة برمجة التطبيقات chrome.tts ميزة "تحويل النص إلى كلام" (TTS) المركّبة.
"ttsEngine"	تنفّذ واجهة برمجة التطبيقات chrome.ttsEngine محرك تحويل النص إلى كلام باستخدام إضافة.
"wallpaper"	أجهزة ChromeOS فقط استخدِم واجهة برمجة التطبيقات chrome.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.
  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).
  }
});

الأنواع

Permissions

أماكن إقامة

• الأصول

  سلسلة[] اختيارية

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

• الأذونات

  سلسلة[] اختيارية

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

الطُرق

contains()

وعد

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

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

المَعلمات

• الأذونات

  الأذونات

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  (result: boolean)=>void

  • نتيجة

    boolean

    True إذا كانت الإضافة تحتوي على الأذونات المحددة. إذا تم تحديد مصدر كإذن اختياري ونمط مطابقة للنص البرمجي للمحتوى، سيعرض هذا الخطأ false ما لم يتم منح كلا الإذنَين.

المرتجعات

• Promise<boolean>

  Chrome 96 والإصدارات الأحدث

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

getAll()

وعد

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

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

المَعلمات

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  (permissions: Permissions)=>void

  • الأذونات

    الأذونات

    الأذونات النشطة للإضافة. يُرجى العِلم أنّ السمة origins ستحتوي على مصادر ممنوحة من تلك المحدّدة في مفتاحَي permissions وoptional_permissions في البيان وتلك المرتبطة بنصوص المحتوى البرمجية.

المرتجعات

• وعد<الأذونات>

  Chrome 96 والإصدارات الأحدث

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

remove()

وعد

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

يزيل إمكانية الوصول إلى الأذونات المحددة. وفي حال حدوث أي مشاكل أثناء إزالة الأذونات، سيتم ضبط runtime.lastError.

المَعلمات

• الأذونات

  الأذونات

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  (removed: boolean)=>void

  • مزال

    boolean

    صحيح في حال إزالة الأذونات.

المرتجعات

• Promise<boolean>

  Chrome 96 والإصدارات الأحدث

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

request()

وعد

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

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

المَعلمات

• الأذونات

  الأذونات

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  (granted: boolean)=>void

  • تم منحها

    boolean

    صحيح إذا منح المستخدم الأذونات المحددة.

المرتجعات

• Promise<boolean>

  Chrome 96 والإصدارات الأحدث

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

فعاليات

onAdded

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

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

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

  (permissions: Permissions)=>void

  • الأذونات

    الأذونات

onRemoved

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

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

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

  (permissions: Permissions)=>void

  • الأذونات

    الأذونات