chrome.permissions

توضیحات

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

با استفاده از 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();
    }
  });
});

اگر اضافه کردن مجوزها منجر به پیام‌های هشداری متفاوت از آنچه کاربر قبلاً دیده و پذیرفته است، شود، کروم به کاربر اطلاع می‌دهد. برای مثال، کد قبلی ممکن است منجر به پیامی مانند این شود:

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

برای بررسی اینکه آیا افزونه شما مجوز خاص یا مجموعه‌ای از مجوزها را دارد، 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.
  }
});

مرحله ۵: حذف مجوزها

شما باید زمانی که دیگر به مجوزها نیازی ندارید، آنها را حذف کنید. پس از حذف یک مجوز، فراخوانی 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).
  }
});

chrome.permissions.addHostAccessRequest(
  request: object,
): Promise<void>

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

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

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

chrome.permissions.removeHostAccessRequest(
  request: object,
): Promise<void>

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

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

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