chrome.permissions

الوصف

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

نظرة عامة

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

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

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

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

تحذير بشأن إضافة topSites API

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

الخطوة 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 على أنّها اختيارية، باستثناء الحالات التالية:

الإذن الوصف
"debugger" تُستخدَم واجهة برمجة التطبيقات chrome.debugger كأحد بروتوكولات تصحيح الأخطاء عن بُعد البديلة في Chrome.
"declarativeNetRequest" منح الإضافة إذن الوصول إلى واجهة برمجة التطبيقات chrome.declarativeNetRequest
"devtools" السماح للإضافة بتوسيع نطاق وظائف أدوات مطوّري البرامج في Chrome
"experimental" قناة Canary وقناة المطوّرين فقط. منح الإضافة إذن الوصول إلى واجهات برمجة التطبيقات 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

أماكن إقامة

  • أصول

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

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

  • الأذون

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

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

الطُرق

addSiteAccessRequest()

الوعد في انتظار المراجعةMV3 والإصدارات الأحدث 
chrome.permissions.addSiteAccessRequest(
  request: object,
  callback?: function,
)

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

المعلمات

  • طلب

    عنصر

    • documentId

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

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

    • نمط

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

      نمط عنوان URL الذي يمكن أن تظهر فيه طلبات الوصول إلى الموقع الإلكتروني في حال توفّر هذا العنوان، لن يتم عرض طلبات الوصول إلى الموقع الإلكتروني إلا على عناوين URL التي تتطابق مع هذا النمط.

    • tabId

      رقم اختياري

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

  • ردّ الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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

contains()

الوعد 
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

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

المعلمات

  • الأذون

    الأذونات

  • ردّ الاتصال

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

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

    (result: boolean) => void

    • نتيجة

      قيمة منطقية

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

المرتجعات

  • Promise<boolean>

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

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

getAll()

الوعد 
chrome.permissions.getAll(
  callback?: function,
)

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

المعلمات

  • ردّ الاتصال

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

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

    (permissions: Permissions) => void

    • الأذون

      الأذونات

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

المرتجعات

  • Promise<Permissions>

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

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

remove()

الوعد 
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)

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

المعلمات

  • الأذون

    الأذونات

  • ردّ الاتصال

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

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

    (removed: boolean) => void

    • تمت الإزالة

      قيمة منطقية

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

المرتجعات

  • Promise<boolean>

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

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

removeSiteAccessRequest()

الوعد في انتظار المراجعةMV3 والإصدارات الأحدث 
chrome.permissions.removeSiteAccessRequest(
  request: object,
  callback?: function,
)

تزيل هذه القيمة طلب الوصول إلى الموقع الإلكتروني، في حال توفّره.

المعلمات

  • طلب

    عنصر

    • documentId

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

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

    • نمط

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

      نمط عنوان URL الذي ستتم إزالة طلب الوصول إلى الموقع الإلكتروني منه يجب أن يتطابق هذا النمط تمامًا مع نمط طلب وصول حالي إلى الموقع الإلكتروني، في حال توفّره.

    • tabId

      رقم اختياري

      رقم تعريف علامة التبويب التي ستتم إزالة طلب الوصول إلى الموقع الإلكتروني منها. يجب تحديد هذا الخيار أو documentId.

  • ردّ الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

    لا تتوفّر الوعود إلا في الإصدار 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>

    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