browser.permissions

شرح

از chrome.permissions API برای درخواست اجازه‌های اختیاری اعلام‌شده در زمان اجرا به‌جای زمان نصب استفاده کنید تا کاربران متوجه شوند چرا این اجازه‌ها لازم است و فقط اجازه‌های ضروری را اعطا کنند.

مفاهیم و کاربرد

هشدارهای اجازه برای توصیف قابلیت‌های اعطاشده توسط میانای برنامه‌سازی کاربردی (API) وجود دارند، اما برخی‌از این هشدارها ممکن است واضح نباشند. «میانای برنامه‌سازی کاربردی اجازه‌ها» به توسعه‌دهندگان اجازه می‌دهد هشدارهای اجازه را توضیح دهند و ویژگی‌های جدید را به‌تدریج معرفی کنند که این امر باعث می‌شود کاربران بدون ریسک با افزونه آشنا شوند. به‌این‌ترتیب، کاربران می‌توانند مشخص کنند که مایلند چه مقدار دسترسی اعطا کنند و کدام ویژگی‌ها را می‌خواهند فعال کنند.

برای مثال، عملکرد اصلی افزونه اجازه‌های اختیاری لغو کردن صفحه زبانه جدید است. یکی از ویژگی‌ها نمایش هدف روزانه کاربر است. این ویژگی فقط به اجازه فضای ذخیره‌سازی نیاز دارد که شامل هشدار نمی‌شود. این افزونه ویژگی دیگری دارد که کاربران می‌توانند با کلیک کردن روی دکمه زیر آن را فعال کنند:

دکمه افزونه‌ای که ویژگی‌های اضافی را فعال می‌کند.
دکمه افزونه‌ای که ویژگی‌های اضافی را فعال می‌کند.

نمایش سایت‌های برتر کاربر به اجازه topSites نیاز دارد که هشدار زیر را دارد.

Axtension warning for topSites API.
هشدار افزونه برای میانای برنامه‌سازی کاربردی topSites

اجرای اجازه‌های اختیاری

مرحله ۱: تصمیم بگیرید کدام اجازه‌ها الزامی و کدام اختیاری هستند

افزونه می‌تواند هم اجازه‌های الزامی و هم اجازه‌های اختیاری را اعلام کند. به‌طورکلی، باید:

  • از اجازه‌های لازم زمانی استفاده کنید که برای عملکرد اصلی افزونه‌تان موردنیاز باشند.
  • از اجازه‌های اختیاری زمانی استفاده کنید که برای ویژگی‌های اختیاری در افزونه‌تان لازم باشد.

مزایای اجازه‌های موردنیاز:

  • پیام‌واره‌های کمتر: افزونه می‌تواند یک‌بار از کاربر بخواهد همه اجازه‌ها را بپذیرد.
  • توسعه ساده‌تر: تضمین می‌شود که اجازه‌های لازم وجود داشته باشند.

مزایای اجازه‌های اختیاری:

  • امنیت بهتر: افزونه‌ها با اجازه‌های کمتری اجرا می‌شوند زیرا کاربران فقط اجازه‌هایی را فعال می‌کنند که لازم است.
  • اطلاعات بهتر برای کاربران: افزونه می‌تواند توضیح دهد که چرا به اجازه خاصی نیاز دارد وقتی کاربر ویژگی مربوطه را فعال می‌کند.
  • ارتقای آسان‌تر: وقتی افزونه‌تان را ارتقا می‌دهید، اگر ارتقا اجازه‌های اختیاری را به‌جای اجازه‌های الزامی اضافه کند، Chrome آن را برای کاربران غیرفعال نخواهد کرد.

مرحله ۲: اعلام اجازه‌های اختیاری در مانیفست

اجازه‌های اختیاری را در مانیفست افزونه با کلید optional_permissions، بااستفاده از همان قالب فیلد اجازه‌ها اعلام کنید:

{
  "name": "My extension",
  ...
  "optional_permissions": ["tabs"],
  "optional_host_permissions": ["https://www.google.com/"],
  ...
}

اگر می‌خواهید میزبان‌هایی را درخواست کنید که فقط در زمان اجرا کشف می‌کنید، "https://*/*" را در فیلد optional_host_permissions افزونه‌تان اضافه کنید. این به شما امکان می‌دهد هر مبدأیی را در "Permissions.origins" مشخص کنید، به‌شرطی که طرح تطابقی داشته باشد.

اجازه‌هایی که نمی‌توانند به‌عنوان اختیاری مشخص شوند

اکثر اجازه‌های افزونه Chrome را می‌توان به‌عنوان اختیاری مشخص کرد، به‌جز موارد زیر.

اجازه شرح
"debugger" browser.debugger API به‌عنوان انتقال جایگزین برای پروتکل اشکال‌زدایی از راه دور Chrome عمل می‌کند.
"declarativeNetRequest" به افزونه اجازه می‌دهد به میانای برنامه‌سازی کاربردی browser.declarativeNetRequest دسترسی داشته باشد.
"devtools" به افزونه اجازه می‌دهد عملکرد Chrome DevTools را گسترش دهد.
"geolocation" به افزونه اجازه می‌دهد از میانای برنامه‌سازی کاربردی مکان‌یابی جغرافیایی HTML5 استفاده کند.
"mdns" دسترسی افزونه به browser.mdns API را اعطا می‌کند.
"proxy" به افزونه اجازه می‌دهد به میانای برنامه‌سازی کاربردی browser.proxy دسترسی داشته باشد تا تنظیمات پراکسی Chrome را مدیریت کند.
"tts" browser.tts API نوشتار به گفتار (TTS) ترکیبی را پخش می‌کند.
"ttsEngine" میانای برنامه‌سازی کاربردی browser.ttsEngine موتور نوشتار به گفتار (TTS) را بااستفاده از افزونه پیاده‌سازی می‌کند.
"wallpaper" فقط ChromeOS. از browser.wallpaper API برای تغییر کاغذدیواری ChromeOS استفاده کنید.

برای اطلاعات بیشتر درباره اجازه‌های دردسترس و هشدارهای آن‌ها، اعلام اجازه‌ها را مشاهده کنید.

مرحله ۳: درخواست اجازه‌های اختیاری

اجازه‌ها را از درون اشاره کاربر بااستفاده از permissions.request() درخواست کنید:

document.querySelector('#my-button').addEventListener('click', (event) => {
  // Permissions must be requested from inside a user gesture, like a button's
  // click handler.
  browser.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 از کاربر درخواست می‌کند. برای مثال، کد قبلی ممکن است منجر به پیام‌واره‌ای مانند این شود:

نمونه پیام‌واره تأیید اجازه.
نمونه پیام‌واره تأیید اجازه.

مرحله ۴: اجازه‌های فعلی افزونه را بررسی کنید

برای بررسی اینکه آیا افزونه شما اجازه یا مجموعه‌ای از اجازه‌های خاص را دارد، از permission.contains() استفاده کنید:

browser.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.
  }
});

مرحله ۵: برداشتن اجازه‌ها

وقتی دیگر به اجازه‌ها نیاز ندارید، باید آن‌ها را بردارید. پس‌از برداشته شدن اجازه، فراخوانی permissions.request() معمولاً اجازه را بدون درخواست از کاربر دوباره اضافه می‌کند.

browser.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()

Chrome نسخه ۱۳۳ و بالاتر browser.* از Chrome نسخه ۱۴۸ MV3 و بالاتر 
browser.permissions.addHostAccessRequest(
  request: object,
): Promise<void>

درخواست دسترسی میزبان را اضافه می‌کند. درخواست فقط زمانی به کاربر علامت داده می‌شود که افزونه بتواند در درخواست به میزبان دسترسی پیدا کند. درخواست در پیمایش بین‌مبدائی بازنشانی خواهد شد. درصورت پذیرفته شدن، دسترسی دائمی به مبدأ برتر سایت اعطا می‌کند

پارامترها

  • درخواست کردن

    شیء

    • documentId

      رشته اختیاری

      شناسه سندی که درخواست‌های دسترسی میزبان می‌تواند در آن نشان داده شود. باید سند سطح بالا در برگه باشد. اگر ارائه شود، درخواست در برگه سند مشخص‌شده نشان داده می‌شود و وقتی سند به مبدأ جدیدی پیمایش کند برداشته می‌شود. افزودن درخواست جدید، هرگونه درخواست موجود برای tabId را لغو می‌کند. این یا tabId باید مشخص شود.

    • الگو

      رشته اختیاری

      الگوی نشانی وبی که درخواست‌های دسترسی میزبان می‌تواند در آن نشان داده شود. اگر ارائه شود، درخواست‌های دسترسی میزبان فقط در نشانی‌های وبی نشان داده می‌شود که با این الگو مطابقت داشته باشند.

    • tabId

      شماره اختیاری

      شناسه برگه‌ای که درخواست‌های دسترسی میزبان می‌تواند در آن نشان داده شود. اگر ارائه شود، درخواست در برگه مشخص‌شده نشان داده می‌شود و وقتی برگه به مبدأ جدیدی پیمایش می‌کند برداشته می‌شود. افزودن درخواست جدید، درخواست موجود برای documentId را لغو می‌کند. این یا documentId باید مشخص شود.

بازگشتی‌ها

  • Promise<void>

contains()

browser.permissions.contains(
  permissions: Permissions,
): Promise<boolean>

بررسی می‌کند که آیا افزونه اجازه‌های مشخص‌شده را دارد یا نه.

پارامترها

بازگشتی‌ها

  • Promise<boolean>

    Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

getAll()

browser.permissions.getAll(): Promise<Permissions>

مجموعه اجازه‌های فعلی افزونه را دریافت می‌کند.

بازگشتی‌ها

  • Promise<Permissions>

    Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

remove()

browser.permissions.remove(
  permissions: Permissions,
): Promise<boolean>

دسترسی به اجازه‌های مشخص‌شده را برمی‌دارد. اگر مشکلی در برداشتن اجازه‌ها وجود داشته باشد، وعده رد خواهد شد.

پارامترها

بازگشتی‌ها

  • Promise<boolean>

    Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

removeHostAccessRequest()

Chrome نسخه ۱۳۳ و بالاتر browser.* از Chrome نسخه ۱۴۸ MV3 و بالاتر 
browser.permissions.removeHostAccessRequest(
  request: object,
): Promise<void>

درخواست دسترسی میزبان را (درصورت وجود) برمی‌دارد.

پارامترها

  • درخواست کردن

    شیء

    • documentId

      رشته اختیاری

      شناسه سندی که درخواست دسترسی میزبان از آن برداشته خواهد شد. باید سند سطح بالا در برگه باشد. این یا tabId باید مشخص شود.

    • الگو

      رشته اختیاری

      الگوی نشانی وب که درخواست دسترسی میزبان از آن برداشته خواهد شد. اگر ارائه شده باشد، باید دقیقاً با الگوی درخواست دسترسی میزبان موجود مطابقت داشته باشد.

    • tabId

      شماره اختیاری

      شناسه برگه‌ای که درخواست دسترسی میزبان از آن برداشته خواهد شد. این یا documentId باید مشخص شود.

بازگشتی‌ها

  • Promise<void>

request()

browser.permissions.request(
  permissions: Permissions,
): Promise<boolean>

دسترسی به اجازه‌های مشخص‌شده را درخواست می‌کند و درصورت لزوم، پیام‌واره‌ای به کاربر نمایش می‌دهد. این اجازه‌ها باید در فیلد optional_permissions مانیفست تعریف شده باشند یا اجازه‌های الزامی باشند که کاربر از اعطای آن‌ها خودداری کرده است. مسیرهای الگوهای مبدأ نادیده گرفته خواهند شد. می‌توانید زیرمجموعه‌هایی از اجازه‌های اختیاری مبدأ را درخواست کنید؛ برای مثال، اگر *://*\/* را در بخش optional_permissions مانیفست مشخص کنید، می‌توانید http://example.com/ را درخواست کنید. اگر مشکلی در درخواست اجازه‌ها وجود داشته باشد، وعده رد خواهد شد.

پارامترها

بازگشتی‌ها

  • Promise<boolean>

    Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

رویدادها

onAdded

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

وقتی افزونه اجازه‌های جدیدی دریافت می‌کند، فعال می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (permissions: Permissions) => void

onRemoved

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

وقتی دسترسی به اجازه‌ها از افزونه برداشته شود، فعال می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (permissions: Permissions) => void