chrome.permissions

الوصف

يمكنك استخدام واجهة برمجة التطبيقات 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 كخيار، مع الاستثناءات التالية.

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

أماكن إقامة

• الأصول

  string[] اختيارية

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

• الأذون

  string[] اختيارية

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

الطُرق

contains()

وعود

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

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

المعلمات

• الأذون

  الأذونات

• رد الاتصال

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

  تظهر المَعلمة callback على النحو التالي:

  (result: boolean) => void

  • نتيجة

    منطقي

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

المرتجعات

• Promise<boolean>

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

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

getAll()

وعود

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

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

المعلمات

• رد الاتصال

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

  تظهر المَعلمة callback على النحو التالي:

  (permissions: Permissions) => void

  • الأذون

    الأذونات

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

المرتجعات

• Promise<Permissions>

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

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

remove()

وعود

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

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

المعلمات

• الأذون

  الأذونات

• رد الاتصال

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

  تظهر المَعلمة callback على النحو التالي:

  (removed: boolean) => void

  • تمت الإزالة

    منطقي

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

المرتجعات

• Promise<boolean>

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

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

request()

وعود

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

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

المعلمات

• الأذون

  الأذونات

• رد الاتصال

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

  تظهر المَعلمة callback على النحو التالي:

  (granted: boolean) => void

  • تم منحها

    منطقي

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

المرتجعات

• Promise<boolean>

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

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

فعاليات

onAdded

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

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

المعلمات

• رد الاتصال

  دالة

  تظهر المَعلمة callback على النحو التالي:

  (permissions: Permissions) => void

  • الأذون

    الأذونات

onRemoved

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

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

المعلمات

• رد الاتصال

  دالة

  تظهر المَعلمة callback على النحو التالي:

  (permissions: Permissions) => void

  • الأذون

    الأذونات