Описание
Используйте 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в манифесте, а также те, которые связаны со сценариями содержимого . - разрешения
строка[] необязательно
Список именованных разрешений (не включает хосты и источники).
Методы
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 и более поздних версий, на других платформах необходимо использовать обратные вызовы.
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
- разрешения