chrome.permissions

توضیحات

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

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

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

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

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

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

هشدار برنامه افزودنی برای topSites API

پیاده سازی مجوزهای اختیاری

مرحله 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 API به عنوان یک انتقال جایگزین برای پروتکل اشکال‌زدایی از راه دور Chrome عمل می‌کند.
"declarativeNetRequest"	به برنامه افزودنی اجازه دسترسی به chrome.declarativeNetRequest API می دهد.
"devtools"	به برنامه افزودنی اجازه می دهد تا عملکرد Chrome DevTools را گسترش دهد.
"geolocation"	به برنامه افزودنی اجازه می دهد از API مکان جغرافیایی HTML5 استفاده کند.
"mdns"	به برنامه افزودنی اجازه دسترسی به chrome.mdns API می دهد.
"proxy"	به برنامه افزودنی اجازه دسترسی به chrome.proxy API برای مدیریت تنظیمات پروکسی Chrome را می دهد.
"tts"	chrome.tts API متن به گفتار (TTS) سنتز شده را پخش می کند.
"ttsEngine"	chrome.ttsEngine API یک موتور تبدیل متن به گفتار (TTS) را با استفاده از یک برنامه افزودنی پیاده سازی می کند.
"wallpaper"	فقط ChromeOS از chrome.wallpaper API استفاده کنید، کاغذدیواری 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 در مانیفست مشخص شده‌اند، و موارد مرتبط با Content Scripts .

• مجوزها

  رشته[] اختیاری است

  فهرست مجوزهای نامگذاری شده (شامل میزبان یا مبدا نیست).

روش ها

addHostAccessRequest()

Promise Pending MV3+

chrome.permissions.addHostAccessRequest(
  request: object,
  callback?: function,
)

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

پارامترها

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

  شی

  • شناسه سند

    رشته اختیاری

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

  • الگوی

    رشته اختیاری

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

  • tabId

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

    شناسه برگه ای که درخواست های دسترسی میزبان را می توان نشان داد. در صورت ارائه، درخواست در برگه مشخص شده نشان داده می شود و زمانی که برگه به ​​مبدأ جدید هدایت می شود حذف می شود. افزودن یک درخواست جدید یک درخواست موجود برای documentId را لغو می کند. این یا documentId باید مشخص شود.

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  () => void

برمی گرداند

• قول<باطل>

  Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

contains()

قول بده

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

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

پارامترها

• مجوزها

  مجوزها

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  (result: boolean) => void

  • نتیجه

    بولی

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

برمی گرداند

• وعده<boolean>

  Chrome 96+

  Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

getAll()

قول بده

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

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

پارامترها

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  (permissions: Permissions) => void

  • مجوزها

    مجوزها

    مجوزهای فعال برنامه افزودنی توجه داشته باشید که ویژگی origins حاوی مبداهای اعطایی از موارد مشخص شده در permissions و کلیدهای optional_permissions در مانیفست و موارد مرتبط با Content Scripts خواهد بود.

برمی گرداند

• Promise< مجوزها >

  Chrome 96+

  Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

remove()

قول بده

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

دسترسی به مجوزهای مشخص شده را حذف می کند. اگر مشکلی در حذف مجوزها وجود داشته باشد، runtime.lastError تنظیم خواهد شد.

پارامترها

• مجوزها

  مجوزها

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  (removed: boolean) => void

  • حذف شده است

    بولی

    اگر مجوزها حذف شوند درست است.

برمی گرداند

• وعده<boolean>

  Chrome 96+

  Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

removeHostAccessRequest()

Promise Pending MV3+

chrome.permissions.removeHostAccessRequest(
  request: object,
  callback?: function,
)

در صورت وجود درخواست دسترسی میزبان را حذف می کند.

پارامترها

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

  شی

  • شناسه سند

    رشته اختیاری

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

  • الگوی

    رشته اختیاری

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

  • tabId

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

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

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  () => void

برمی گرداند

• قول<باطل>

  Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

request()

قول بده

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

دسترسی به مجوزهای مشخص شده را درخواست می کند و در صورت لزوم یک درخواست را به کاربر نمایش می دهد. این مجوزها یا باید در قسمت optional_permissions مانیفست تعریف شوند یا مجوزهای مورد نیازی باشند که توسط کاربر خودداری شده است. مسیرهای روی الگوهای مبدا نادیده گرفته خواهند شد. شما می توانید زیرمجموعه های مجوزهای مبدا اختیاری را درخواست کنید. برای مثال، اگر *://*\/* در بخش optional_permissions مانیفست مشخص کنید، می توانید http://example.com/ درخواست کنید. اگر مشکلی در درخواست مجوزها وجود داشته باشد، runtime.lastError تنظیم خواهد شد.

پارامترها

• مجوزها

  مجوزها

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  (granted: boolean) => void

  • اعطا شد

    بولی

    اگر کاربر مجوزهای مشخص شده را داده باشد درست است.

برمی گرداند

• وعده<boolean>

  Chrome 96+

  Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

رویدادها

onAdded

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

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

پارامترها

• پاسخ به تماس

  تابع

  پارامتر callback به نظر می رسد:

  (permissions: Permissions) => void

  • مجوزها

    مجوزها

onRemoved

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

زمانی فعال می شود که دسترسی به مجوزها از برنامه افزودنی حذف شود.

پارامترها

• پاسخ به تماس

  تابع

  پارامتر callback به نظر می رسد:

  (permissions: Permissions) => void

  • مجوزها

    مجوزها