الوصف
يمكنك استخدام واجهة برمجة التطبيقات chrome.permissions
API لطلب الأذونات الاختيارية المعلَن عنها في وقت التشغيل بدلاً من وقت التثبيت، لكي يفهم المستخدمون سبب الحاجة إلى الأذونات ولا تمنحهم سوى الأذونات اللازمة.
المفاهيم والاستخدام
هناك تحذيرات بشأن الأذونات لوصف الإمكانات التي تمنحها واجهة برمجة التطبيقات، إلا أنّ بعض هذه التحذيرات قد لا تكون واضحة. تسمح واجهة برمجة التطبيقات Permissions API للمطوّرين بشرح التحذيرات المتعلّقة بالأذونات وتقديم ميزات جديدة تدريجيًا، ما يمنح المستخدمين مقدّمة خالية من المخاطر حول الإضافة. وبهذه الطريقة، يمكن للمستخدمين تحديد مقدار الوصول الذي يريدون منحه والميزات التي يريدون تفعيلها.
على سبيل المثال، تلغي الوظيفة الأساسية لإضافة الأذونات الاختيارية صفحة علامة التبويب الجديدة. إحدى الميزات هي عرض هدف المستخدم اليوم. لا تتطلّب هذه الميزة سوى إذن مساحة التخزين الذي لا يتضمّن تحذيرًا. تشتمل الإضافة على ميزة إضافية يمكن للمستخدمين تفعيلها من خلال النقر على الزر التالي:
![زر الإضافة الذي يتيح ميزات إضافية.](https://developer.chrome.com/static/docs/extensions/reference/api/permissions/images/extension-button-enables-c53fe17733b8f.png?authuser=6&hl=ar)
يتطلب عرض أهم المواقع الإلكترونية للمستخدم الحصول على إذن topSites، الذي يتضمّن التحذير التالي.
![تحذير بشأن التشتيت في واجهة برمجة التطبيقات TopSites.](https://developer.chrome.com/static/docs/extensions/reference/api/permissions/images/extension-warning-topsit-8927d6b7cb863.png?authuser=6&hl=ar)
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 من المستخدم إذا كانت إضافة الأذونات تؤدي إلى رسائل تحذير مختلفة عن تلك التي قد رآها المستخدم وقبلها. على سبيل المثال، قد تؤدي التعليمة البرمجية السابقة إلى طلب مثل هذا:
![مثال على طلب تأكيد الإذن](https://developer.chrome.com/static/docs/extensions/reference/api/permissions/images/perms-optional.png?authuser=6&hl=ar)
الخطوة 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
-
الأذونات
-