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
"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 في البيان، وتلك المرتبطة ببرامج نصية للمحتوى

• الأذون

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

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

الطُرق

addHostAccessRequest()

الوعد في انتظار المراجعةMV3 والإصدارات الأحدث

chrome.permissions.addHostAccessRequest(
  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 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى دالة الاستدعاء.

removeHostAccessRequest()

الوعد في انتظار المراجعةMV3 والإصدارات الأحدث

chrome.permissions.removeHostAccessRequest(
  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

  • الأذون

    الأذونات