chrome.permissions

Описание

Используйте API chrome.permissions для запроса объявленных дополнительных разрешений во время выполнения, а не во время установки, чтобы пользователи понимали, зачем нужны разрешения, и предоставляли только те, которые необходимы.

Концепции и использование

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

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

Кнопка расширения, которая включает дополнительные функции.
Кнопка расширения, которая включает дополнительные функции.

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

Предупреждение о расширении API topSites.
Предупреждение о расширении для 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 можно указать как необязательные, за следующими исключениями.

Разрешение Описание
"debugger" API chrome.debugger служит альтернативным транспортом для протокола удаленной отладки Chrome.
"declarativeNetRequest" Предоставляет расширению доступ к API chrome.declarativeNetRequest .
"devtools" Позволяет расширению расширять функциональность Chrome DevTools .
"geolocation" Позволяет расширению использовать API геолокации HTML5.
"mdns" Предоставляет расширению доступ к API chrome.mdns .
"proxy" Предоставляет расширению доступ к API chrome.proxy для управления настройками прокси-сервера Chrome.
"tts" API chrome.tts воспроизводит синтезированную речь (TTS).
"ttsEngine" API chrome.ttsEngine реализует механизм преобразования текста в речь (TTS) с использованием расширения.
"wallpaper" Только ChromeOS . Используйте API chrome.wallpaper , чтобы изменить обои 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 в манифесте, а также те, которые связаны со сценариями содержимого .

  • разрешения

    строка[] необязательно

    Список именованных разрешений (не включает хосты и источники).

Методы

contains()

Обещать
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

Проверяет, имеет ли расширение указанные разрешения.

Параметры

  • разрешения
  • перезвонить

    функция необязательна

    Параметр callback выглядит так:

    (result: boolean) => void

    • результат

      логическое значение

      True, если расширение имеет указанные разрешения. Если источник указан как необязательное разрешение, так и шаблон соответствия сценария содержимого, это вернет false , если не предоставлены оба разрешения.

Возврат

  • Обещание <логическое значение>

    Хром 96+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

getAll()

Обещать
chrome.permissions.getAll(
  callback?: function,
)

Получает текущий набор разрешений расширения.

Параметры

  • перезвонить

    функция необязательна

    Параметр callback выглядит так:

    (permissions: Permissions) => void

    • разрешения

      Активные разрешения расширения. Обратите внимание, что свойство origins будет содержать предоставленные источники из тех, которые указаны в ключах permissions и optional_permissions в манифесте, а также те, которые связаны с Content Scripts .

Возврат

  • Обещание < Разрешения >

    Хром 96+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

remove()

Обещать
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)

Удаляет доступ к указанным разрешениям. Если возникнут проблемы с удалением разрешений, будет установлен runtime.lastError .

Параметры

  • разрешения
  • перезвонить

    функция необязательна

    Параметр callback выглядит так:

    (removed: boolean) => void

    • удаленный

      логическое значение

      True, если разрешения были удалены.

Возврат

  • Обещание <логическое значение>

    Хром 96+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

request()

Обещать
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
)

Запрашивает доступ к указанным разрешениям, при необходимости отображая запрос пользователю. Эти разрешения должны быть либо определены в поле optional_permissions манифеста, либо быть обязательными разрешениями, которые были скрыты пользователем. Пути в исходных шаблонах будут игнорироваться. Вы можете запросить подмножество дополнительных разрешений источника; например, если вы укажете *://*\/* в разделе optional_permissions манифеста, вы можете запросить http://example.com/ . Если возникнут какие-либо проблемы с запросом разрешений, будет установлен runtime.lastError .

Параметры

  • разрешения
  • перезвонить

    функция необязательна

    Параметр callback выглядит так:

    (granted: boolean) => void

    • предоставленный

      логическое значение

      True, если пользователь предоставил указанные разрешения.

Возврат

  • Обещание <логическое значение>

    Хром 96+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

События

onAdded

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

Запускается, когда расширение получает новые разрешения.

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так:

    (permissions: Permissions) => void

onRemoved

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

Вызывается, когда доступ к разрешениям удален из расширения.

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так:

    (permissions: Permissions) => void