browser.permissions

Описание

Основные понятия и использование

Предупреждения о разрешениях описывают возможности, предоставляемые API, но некоторые из этих предупреждений могут быть неочевидными. Permissions API позволяет разработчикам объяснять предупреждения о разрешениях и постепенно вводить новые функции, чтобы пользователи могли безопасно ознакомиться с расширением. Это позволяет пользователям указывать, какой уровень доступа они готовы предоставить и какие функции хотят включить.

Например, основная функция расширения с необязательными разрешениями – переопределение страницы быстрого доступа. Одна из функций – отображение цели пользователя на день. Для работы этой функции требуется только разрешение storage, которое не включает предупреждение. У расширения есть дополнительная функция, которую пользователи могут включить, нажав следующую кнопку:

Для показа самых популярных сайтов пользователя требуется разрешение topSites, которое сопровождается следующим предупреждением:

Как реализовать необязательные разрешения

Шаг 1. Определите, какие разрешения являются обязательными, а какие – необязательными

Расширение может запрашивать как обязательные, так и необязательные разрешения. В общем случае нужно выполнить следующие действия:

• Используйте обязательные разрешения, когда они необходимы для работы основных функций расширения.
• Используйте необязательные разрешения, когда они нужны для дополнительных функций расширения.

Преимущества обязательных разрешений:

• Меньше запросов. Расширение может запросить у пользователя разрешение на все действия один раз.
• Простая разработка. Необходимые разрешения гарантированно будут предоставлены.

Преимущества необязательных разрешений:

• Повышенная безопасность. Расширения запускаются с меньшим количеством разрешений, поскольку пользователи включают только необходимые.
• Более подробная информация для пользователей. Расширение может объяснить, почему ему требуется определенное разрешение, когда пользователь включает соответствующую функцию.
• Простое обновление. Если при обновлении расширения вы добавляете необязательные разрешения, Chrome не будет отключать его для пользователей.

Шаг 2. Объявите необязательные разрешения в манифесте

Объявите необязательные разрешения в манифесте расширения с помощью ключа optional_permissions, используя тот же формат, что и для поля 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.
  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 запросит подтверждение. Например, приведенный выше код может привести к следующему запросу:

Шаг 4. Проверьте текущие разрешения расширения

Чтобы проверить, есть ли у расширения определенное разрешение или набор разрешений, используйте 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.
  }
});

Шаг 5. Удалите разрешения

Если разрешения больше не нужны, их следует удалить. После удаления разрешения вызов 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).
  }
});

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

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

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

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

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

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

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

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