Chrome теперь поддерживает стандартизированное пространство имен browser.* (доступно начиная с Chrome 148). Мы постепенно обновляем документацию. Подробнее читайте в нашем руководстве по переходу .

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

browser.permissions

Описание

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

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

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

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

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

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

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

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

Типы

Permissions

Свойства

источники

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

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

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

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

Методы

addHostAccessRequest()

Chrome 133+ browser.* начиная с Chrome 148 MV3+

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

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

Параметры

запрос

Объект
- documentId
  
  Строка (необязательно)
  
  Идентификатор документа, в котором могут показываться запросы на доступ к хосту. Должен быть документом верхнего уровня на вкладке. Если он указан, запрос показывается на вкладке с этим документом и удаляется, когда документ переходит к новому источнику. Новый запрос переопределит все существующие запросы для tabId. Необходимо указать значение этого свойства или свойства tabId.
- узор
  
  Строка (необязательно)
  
  Шаблон URL, для которого могут показываться запросы на доступ к хосту. Если указать шаблон, запросы на доступ к хосту будут показываться только на URL, соответствующих этому шаблону.
- tabId
  
  number (необязательно)
  
  Идентификатор вкладки, на которой могут показываться запросы на доступ к хосту. Если он указан, запрос показывается на заданной вкладке и удаляется, когда пользователь переходит на другой сайт. Новый запрос переопределит существующий запрос для documentId. Необходимо указать значение этого атрибута или атрибута documentId.

Возвраты

Promise<void>

contains()

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

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

Параметры

разрешения

Разрешения

Возвраты

Promise<boolean>

Chrome 96 и более поздние версии browser.* начиная с Chrome 148

getAll()

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

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

Возвраты

Promise<Permissions>

Chrome 96 и более поздние версии browser.* начиная с Chrome 148

remove()

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

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

Параметры

разрешения

Разрешения

Возвраты

Promise<boolean>

Chrome 96 и более поздние версии browser.* начиная с Chrome 148

removeHostAccessRequest()

Chrome 133+ browser.* начиная с Chrome 148 MV3+

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

Удаляет запрос на доступ к хосту, если он существует.

Параметры

запрос

Объект
- documentId
  
  Строка (необязательно)
  
  Идентификатор документа, из которого будет удален запрос на доступ к хосту. Должен быть документом верхнего уровня на вкладке. Необходимо указать значение этого свойства или свойства tabId.
- узор
  
  Строка (необязательно)
  
  Шаблон URL, для которого будет удален запрос на доступ к хосту. Если указано, должно точно соответствовать шаблону существующего запроса на доступ к хосту.
- tabId
  
  number (необязательно)
  
  Идентификатор вкладки, на которой будет удален запрос на доступ к хосту. Необходимо указать значение этого атрибута или атрибута documentId.

Возвраты

Promise<void>

request()

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

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

Параметры

разрешения

Разрешения

Возвраты

Promise<boolean>

Chrome 96 и более поздние версии browser.* начиная с Chrome 148

События

onAdded

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

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

Параметры

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

function

Параметр callback выглядит следующим образом:
```
(permissions: Permissions) => void
```
- разрешения
  
  Разрешения

onRemoved

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

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

Параметры

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

function

Параметр callback выглядит следующим образом:
```
(permissions: Permissions) => void
```
- разрешения
  
  Разрешения

browser.permissions Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Описание

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

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

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

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

Шаг 3. Запросите необязательные разрешения

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

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

Типы

Permissions

Свойства

Методы

addHostAccessRequest()

Параметры

Возвраты

contains()

Параметры

Возвраты

getAll()

Возвраты

remove()

Параметры

Возвраты

removeHostAccessRequest()

Параметры

Возвраты

request()

Параметры

Возвраты

События

onAdded

Параметры

onRemoved

Параметры

browser.permissions