chrome.permissions

توضیحات

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

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

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

نمایش سایت های برتر کاربر به مجوز 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 را می توان به عنوان اختیاری، با استثنائات زیر، تعیین کرد.

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

مرحله 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).
  }
});

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

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

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

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

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

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

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

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

توضیحات

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

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

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

نمایش سایت های برتر کاربر به مجوز 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 را می توان به عنوان اختیاری، با استثنائات زیر، تعیین کرد.

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

مرحله 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).
  }
});

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

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

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

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

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

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

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

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