chrome.permissions

refresh date: 2026-09-25 robots: noindex

Описание

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

Обзор

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

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

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

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

Предупреждение о расширении для topSites API

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

Шаг 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 можно указать как необязательные, за исключением перечисленных ниже.

Разрешение Описание
"debugger" API chrome.debugger служит альтернативным транспортом для протокола удаленной отладки Chrome.
"declarativeNetRequest" Предоставляет расширению доступ к API chrome.declarativeNetRequest.
"devtools" Позволяет расширению дополнять функциональность инструментов разработчика Chrome.
"experimental" Только в версиях Canary и для разработчиков. Предоставляет расширению доступ к API chrome.experimental.
"geolocation" Разрешает расширению использовать API геолокации HTML5.
"mdns" Предоставляет расширению доступ к API chrome.mdns.
"proxy" Предоставляет расширению доступ к API chrome.proxy для управления настройками прокси-сервера Chrome.
"tts" API chrome.tts воспроизводит синтезированную речь.
"ttsEngine" chrome.ttsEngine API реализует механизм преобразования текста в речь (TTS) с помощью расширения.

Дополнительную информацию о доступных разрешениях и предупреждениях можно найти в статье Объявление разрешений и предупреждение пользователей.

Шаг 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

Свойства

  • источники

    string[] необязательно

    Список разрешений хоста, включая указанные в ключах optional_permissions или permissions в манифесте, а также связанные со скриптами контента.

  • разрешения

    string[] необязательно

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

Методы

contains()

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

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

Параметры

  • разрешения

    Разрешения

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    (result: boolean) => void

    • Результат

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

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

Возвраты

  • Promise<boolean>

    Chrome 96 и более поздних версий.

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getAll()

Promise 
chrome.permissions.getAll(
  callback?: function,
): Promise<Permissions>

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

Параметры

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    (permissions: Permissions) => void

    • разрешения

      Разрешения

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

Возвраты

  • Promise<Permissions>

    Chrome 96 и более поздних версий.

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

remove()

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

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

Параметры

  • разрешения

    Разрешения

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    (removed: boolean) => void

    • удалено

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

      Возвращает значение "истина", если разрешения были удалены.

Возвраты

  • Promise<boolean>

    Chrome 96 и более поздних версий.

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

request()

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

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

Параметры

  • разрешения

    Разрешения

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    (granted: boolean) => void

    • granted

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

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

Возвраты

  • Promise<boolean>

    Chrome 96 и более поздних версий.

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

События

onAdded

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

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

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

    (permissions: Permissions) => void

onRemoved

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

Срабатывает, когда у расширения отзываются разрешения.

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

    (permissions: Permissions) => void