Описание
Используйте API chrome.permissions
для запроса объявленных дополнительных разрешений во время выполнения, а не во время установки, чтобы пользователи понимали, зачем нужны разрешения, и предоставляли только те, которые необходимы.
Концепции и использование
Предупреждения о разрешениях существуют для описания возможностей, предоставляемых API, но некоторые из этих предупреждений могут быть неочевидными. API разрешений позволяет разработчикам объяснять предупреждения о разрешениях и постепенно вводить новые функции, что дает пользователям возможность без риска познакомиться с расширением. Таким образом, пользователи могут указать, какой объем доступа они готовы предоставить и какие функции они хотят включить.
Например, основная функциональность дополнительного расширения разрешений переопределяет страницу новой вкладки. Одна из функций — отображение цели пользователя на день. Для этой функции требуется только разрешение на хранение , которое не включает предупреждение. Расширение имеет дополнительную функцию, которую пользователи могут включить, нажав следующую кнопку:
![Кнопка расширения, которая включает дополнительные функции.](https://developer.chrome.com/static/docs/extensions/reference/api/permissions/images/extension-button-enables-c53fe17733b8f.png?authuser=5&hl=ru)
Для отображения самых популярных сайтов пользователя требуется разрешение topSites , которое имеет следующее предупреждение.
![Предупреждение о расширении API topSites.](https://developer.chrome.com/static/docs/extensions/reference/api/permissions/images/extension-warning-topsit-8927d6b7cb863.png?authuser=5&hl=ru)
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 уведомляет пользователя, если добавление разрешений приводит к появлению предупреждающих сообщений , отличных от тех, которые пользователь уже видел и принял. Например, предыдущий код может привести к появлению такого приглашения:
![Пример запроса подтверждения разрешения.](https://developer.chrome.com/static/docs/extensions/reference/api/permissions/images/perms-optional.png?authuser=5&hl=ru)
Шаг 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
- разрешения