chrome.permissions

Описание

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

Обзор

Предупреждения о разрешениях существуют для описания возможностей, предоставляемых API, но некоторые из этих предупреждений могут быть неочевидными. 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 .
"experimental"	Только Canary и канал Dev . Предоставляет расширению доступ к API chrome.experimental .
"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 в манифесте, а также те, которые связаны со сценариями содержимого .

• разрешения

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

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

Методы

addHostAccessRequest()

Обещание в ожидании MV3+

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

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

Параметры

• запрос

  объект

  • идентификатор документа

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

    Идентификатор документа, в котором могут быть показаны запросы доступа к хосту. Должен быть документом верхнего уровня на вкладке. Если этот параметр предоставлен, запрос отображается на вкладке указанного документа и удаляется, когда документ переходит к новому источнику. Добавление нового запроса переопределит любой существующий запрос для tabId . Необходимо указать этот или tabId .

  • шаблон

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

    Шаблон URL-адреса, в котором могут отображаться запросы доступа к хосту. Если этот параметр указан, запросы доступа к хосту будут отображаться только по URL-адресам, соответствующим этому шаблону.

  • идентификатор табуляции

    номер необязательно

    Идентификатор вкладки, на которой могут отображаться запросы доступа к хосту. Если этот параметр указан, запрос отображается на указанной вкладке и удаляется, когда вкладка переходит к новому источнику. Добавление нового запроса переопределит существующий запрос для documentId . Необходимо указать этот или documentId .

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

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

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

  () => void

Возврат

• Обещание<void>

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

contains()

Обещать

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

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

Параметры

• разрешения

  Разрешения

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

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

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

  (result: boolean) => void

  • результат

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

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

Возврат

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

  Хром 96+

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

getAll()

Обещать

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

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

Параметры

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

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

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

  (permissions: Permissions) => void

  • разрешения

    Разрешения

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

Возврат

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

  Хром 96+

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

remove()

Обещать

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

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

Параметры

• разрешения

  Разрешения

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

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

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

  (removed: boolean) => void

  • удаленный

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

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

Возврат

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

  Хром 96+

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

removeHostAccessRequest()

Обещание в ожидании MV3+

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

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

Параметры

• запрос

  объект

  • идентификатор документа

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

    Идентификатор документа, из которого будет удален запрос на доступ к хосту. Должен быть документом верхнего уровня на вкладке. Необходимо указать этот или tabId .

  • шаблон

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

    Шаблон URL-адреса, по которому будет удален запрос доступа к хосту. Если это предусмотрено, оно должно точно соответствовать шаблону существующего запроса доступа к хосту.

  • идентификатор табуляции

    номер необязательно

    Идентификатор вкладки, на которой будет удален запрос на доступ к хосту. Необходимо указать этот или documentId .

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

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

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

  () => void

Возврат

• Обещание<void>

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

request()

Обещать

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

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

Параметры

• разрешения

  Разрешения

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

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

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

  (granted: boolean) => void

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

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

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

Возврат

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

  Хром 96+

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

События

onAdded

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

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

Параметры

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

  функция

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

  (permissions: Permissions) => void

  • разрешения

    Разрешения

onRemoved

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

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

Параметры

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

  функция

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

  (permissions: Permissions) => void

  • разрешения

    Разрешения