permissions

Тип Массив
Обязателен Нет
Пример
"permissions": [
  "*://developer.mozilla.org/*",
  "webRequest"
]

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

При объявлении запросов полномочий с помощью этого ключа, браузер проинформирует пользователей, о том какие полномочия необходимы расширению во время его установки, и задаст вопрос, согласны ли они выдать их расширению. Браузер так же даёт пользователям возможность изучить полномочия расширения уже после установки. Так как требование дополнительных полномочий может повлиять на желание пользователя использовать ваше расширение, решение использования конкретного функционала может стоить тщательного рассмотрения. К примеру, есть смысл избегать запрашивания необязательных полномочий, и предоставлять информацию о том, зачем вашему расширению нужны какие-либо полномочия в описании расширения. Более подробная информация о проблемах, которые вам стоит рассмотреть касательно этой темы, предоставлена в статье Запрашивание правильных полномочий.

Значение ключа может содержать три вида запросов полномочий:

  • Запрос на полномочия для хоста
  • Запрос на API полномочия
  • Запрос на activeTab полномочия

Запрос полномочий для хоста

Запрос на полномочия для хоста объявляется через шаблоны совпадения, где каждый шаблон определяет группу URL, при посещении которых расширение будет иметь эти дополнительные полномочия. Например, запрос на полномочия для хоста может быть задан подобной строкой "*://developer.mozilla.org/*".

Полномочия для хоста включают:

  • Возможность выполнять XMLHttpRequest и fetch запросы на ресурсы, которые имеют заданный origin, не испытывая cross-origin ограничений (даже для запросов, выполняемых из встраиваемого скрипта)
  • Возможность встраивать скрипты программным путём, используя tabs.executeScript, на веб-страницах загруженных с заданного origin
  • Возможность обрабатывать события из webRequest API для заданных хостов
  • Доступ к сookies на заданных хостах, используя cookies API, при условии получения дополнительного "cookies" API полномочия.
  • Возможность обходить защиту от слежения, при условии полностью указанного хоста, без использования универсального символа *. Не будет работать с <all_urls>.

В Firefox, начиная с версии 56, расширения автоматически получают полномочия для своего собственного хоста, который имеет вид:

moz-extension://60a20a9b-1ad4-af49-9b6c-c64c98c37920/

где 60a20a9b-1ad4-af49-9b6c-c64c98c37920 - внутреннее ID расширения. Расширение может получить это URL программным путём, через вызов метода extension.getURL():

browser.extension.getURL("");
// moz-extension://60a20a9b-1ad4-af49-9b6c-c64c98c37920/

Запрос на API полномочия

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

Следующие ключевые слова доступны на данный момент:

  • activeTab
  • alarms
  • background
  • bookmarks
  • browserSettings
  • browsingData
  • clipboardRead
  • clipboardWrite
  • contentSettings
  • contextMenus
  • contextualIdentities
  • cookies
  • debugger
  • dns
  • downloads
  • downloads.open
  • find
  • geolocation
  • history
  • identity
  • idle
  • management
  • menus
  • menus.overrideContext
  • nativeMessaging
  • notifications
  • pageCapture
  • pkcs11
  • privacy
  • proxy
  • search
  • sessions
  • storage
  • tabHide
  • tabs
  • theme
  • topSites
  • unlimitedStorage
  • webNavigation
  • webRequest
  • webRequestBlocking

В большинстве случаев полномочие просто делает возможным доступ к определённому API, за исключением следующих ситуаций:

  • tabs предоставляет доступ к привилегированным частям tabs API: Tab.url, Tab.title, and Tab.faviconUrl. В Firefox, вам так же понадобятся tabs полномочия, если вы собираетесь использовать url ключ в параметре queryInfo для tabs.query() метода. Весь остальной tabs API доступен без запрашивания каких-либо полномочий.
  • webRequestBlocking позволяет вам использовать "blocking" аргумент, для возможности изменять и отменять запросы.
  • downloads.open позволяет использовать downloads.open() API.
  • tabHide позволяет использовать tabs.hide() API.

Запрос на activeTab полномочия

Этот вид запроса объявляется через ключевое слово "activeTab". activeTab полномочия предоставляются расширению на активной в данный момент вкладке, и вступают в эффект только в момент, когда пользователь взаимодействует с расширением.

"Взаимодействие пользователя" включает:

  • Пользователь нажимает на кнопку расширения на панели инструментов или адресной строке
  • Пользователь взаимодействует с контекстным меню расширения
  • Пользователь нажимает комбинацию клавиш, ассоциированную с расширением

activeTab полномочия включают:

  • Возможность программно встраивать JavaScript или CSS на страницу, используя browser.tabs.executeScript и browser.tabs.insertCSS
  • Получение доступа к привилегированным частям tabs API для активной вкладки: Tab.url, Tab.title и Tab.faviconUrl.

Цель этих полномочий – позволить расширению выполнять наиболее распространенные сценарии работы, без необходимости выдавать ему более серьёзные привилегии, так как большинство расширений задумано для выполнения какой-либо работы на активной вкладке после взаимодействия с пользователем. Например, представьте расширение, которое встраивает скрипт на текущую страницу, после того как пользователь нажимает на кнопку расширения на панели инструментов. Если бы activeTab полномочий не существовало, расширению бы пришлось запрашивать <all_urls>. Но они бы давали расширению намного больше привилегий, чем ему было бы необходимо: расширение могло бы встраивать скрипты на любую вкладку и в любой момент, когда пожелает.

Заметьте, что вы сможете иметь доступ к привилегированному tab API, только на момент взаимодействия расширения с пользователем, и пока вкладка не изменила своё состояние. То есть расширение перестанет иметь данные привилегии при изменении адреса страницы или каком-либо другом событии с вкладкой.

Обычно вкладкой, получающей activeTab полномочия, является активная в данный момент вкладка, за исключением одного случая. menus API позволяет расширению создавать элементы контекстного меню, которые будут появляться непосредственно при нажатии на вкладку (элемент на панели вкладок, при нажатии на который изменяется активная вкладка). Если пользователь вызывает контекстное меню на этом элементе, тогда activeTab полномочия выдадутся для вкладки, по которой было произведено нажатие, несмотря на то, что она могла бы не является активной (баг 1446956 начиная с Firefox версии 63).

Доступ к буферу обмена

Два полномочия предоставляют расширению привилегии для взаимодействия с буфером обмена:

Смотрите Взаимодействие с буфером обмена для более подробной информации.

Неограниченное хранилище

Полномочие unlimitedStorage:

  • Позволяет расширению превышать любые ограничения размера хранимой информации для storage.local API
  • В Firefox, позволяет расширению создавать "persistent" базу данных IndexedDB, не запрашивая разрешения у пользователя в момент её создания.

Примеры

 "permissions": ["*://developer.mozilla.org/*"]

Запрашивает полномочия для хостов, имеющих developer.mozilla.org в их URL.

  "permissions": ["tabs"]

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

  "permissions": ["*://developer.mozilla.org/*", "tabs"]

Запрашивает несколько типов полномочий из примеров выше.

Browser compatibility

Update compatibility data on GitHub
КомпьютерыМобильные
ChromeEdgeFirefoxOperaFirefox для Android
permissionsChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 48Opera Полная поддержка ДаFirefox Android Полная поддержка 48
activeTabChrome Полная поддержка ДаEdge Нет поддержки НетFirefox Полная поддержка 48Opera Полная поддержка ДаFirefox Android Полная поддержка 48
alarmsChrome Полная поддержка ДаEdge Нет поддержки НетFirefox Полная поддержка 48Opera Полная поддержка ДаFirefox Android Полная поддержка 48
backgroundChrome Полная поддержка 10Edge Нет поддержки НетFirefox Нет поддержки НетOpera Нет поддержки НетFirefox Android Нет поддержки Нет
bookmarksChrome Полная поддержка ДаEdge Полная поддержка 15Firefox Полная поддержка 48Opera Полная поддержка ДаFirefox Android Нет поддержки Нет
browserSettingsChrome Нет поддержки НетEdge Нет поддержки НетFirefox Полная поддержка 56Opera Нет поддержки НетFirefox Android Полная поддержка 56
browsingDataChrome Полная поддержка ДаEdge Нет поддержки НетFirefox Полная поддержка 53Opera Полная поддержка ДаFirefox Android Полная поддержка 56
clipboardReadChrome Полная поддержка ДаEdge Нет поддержки НетFirefox Полная поддержка 54Opera Полная поддержка ДаFirefox Android Полная поддержка 54
clipboardWriteChrome Полная поддержка ДаEdge Нет поддержки НетFirefox Полная поддержка 51Opera Полная поддержка ДаFirefox Android Полная поддержка 51
contentSettingsChrome Полная поддержка ДаEdge Нет поддержки НетFirefox Нет поддержки НетOpera Полная поддержка ДаFirefox Android Нет поддержки Нет
contextMenusChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 55
Замечания
Полная поддержка 55
Замечания
Замечания Available as an alias to the menus permission.
Opera Полная поддержка ДаFirefox Android Нет поддержки Нет
contextualIdentitiesChrome Нет поддержки НетEdge Нет поддержки НетFirefox Полная поддержка 53Opera Нет поддержки НетFirefox Android Полная поддержка 53
cookiesChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 48Opera Полная поддержка ДаFirefox Android Полная поддержка 48
debuggerChrome Полная поддержка ДаEdge Нет поддержки НетFirefox Нет поддержки НетOpera Полная поддержка ДаFirefox Android Нет поддержки Нет
dnsChrome Нет поддержки НетEdge Нет поддержки НетFirefox Полная поддержка 60Opera Нет поддержки НетFirefox Android Полная поддержка 60
downloadsChrome Полная поддержка ДаEdge Нет поддержки НетFirefox Полная поддержка 48Opera Полная поддержка ДаFirefox Android Полная поддержка 48
downloads.openChrome Полная поддержка ДаEdge Нет поддержки НетFirefox Полная поддержка 48Opera Полная поддержка ДаFirefox Android Полная поддержка 48
findChrome Нет поддержки НетEdge Нет поддержки НетFirefox Полная поддержка 57Opera Нет поддержки НетFirefox Android Нет поддержки Нет
geolocationChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 54Opera Полная поддержка ДаFirefox Android Полная поддержка 54
historyChrome Полная поддержка ДаEdge Нет поддержки НетFirefox Полная поддержка 49Opera Полная поддержка ДаFirefox Android Нет поддержки Нет
identityChrome Полная поддержка ДаEdge Нет поддержки НетFirefox Полная поддержка 53Opera Полная поддержка ДаFirefox Android Нет поддержки Нет
idleChrome Полная поддержка ДаEdge Полная поддержка 15Firefox Полная поддержка 48Opera Полная поддержка ДаFirefox Android Полная поддержка 48
managementChrome Полная поддержка ДаEdge Нет поддержки НетFirefox Полная поддержка 51Opera Полная поддержка ДаFirefox Android Полная поддержка 51
menusChrome Нет поддержки НетEdge Нет поддержки НетFirefox Полная поддержка 53Opera Нет поддержки НетFirefox Android Нет поддержки Нет
nativeMessagingChrome Полная поддержка 29Edge Полная поддержка 15Firefox Полная поддержка 50Opera Полная поддержка 16Firefox Android Нет поддержки Нет
notificationsChrome Полная поддержка 5Edge Нет поддержки НетFirefox Полная поддержка 48Opera Полная поддержка 25Firefox Android Полная поддержка 48
pageCaptureChrome Полная поддержка ДаEdge Нет поддержки НетFirefox Нет поддержки НетOpera Полная поддержка ДаFirefox Android Нет поддержки Нет
pkcs11Chrome Нет поддержки НетEdge Нет поддержки НетFirefox Полная поддержка 58Opera Нет поддержки НетFirefox Android Нет поддержки Нет
privacyChrome Полная поддержка ДаEdge Нет поддержки НетFirefox Полная поддержка 54Opera Полная поддержка ДаFirefox Android Полная поддержка 54
proxyChrome Нет поддержки НетEdge Нет поддержки НетFirefox Полная поддержка 55Opera Нет поддержки НетFirefox Android Полная поддержка 55
sessionsChrome Полная поддержка ДаEdge Нет поддержки НетFirefox Полная поддержка 52Opera Полная поддержка ДаFirefox Android Нет поддержки Нет
storageChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 48Opera Полная поддержка ДаFirefox Android Полная поддержка 48
tabsChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 48Opera Полная поддержка ДаFirefox Android Полная поддержка 54
themeChrome Нет поддержки НетEdge Нет поддержки НетFirefox Полная поддержка 55Opera Нет поддержки НетFirefox Android Нет поддержки Нет
topSitesChrome Полная поддержка ДаEdge Нет поддержки НетFirefox Полная поддержка 52Opera Полная поддержка ДаFirefox Android Полная поддержка 52
unlimitedStorageChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 56Opera Нет поддержки НетFirefox Android Полная поддержка 56
webNavigationChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 48Opera Полная поддержка 17Firefox Android Полная поддержка 48
webRequestChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 48Opera Полная поддержка ДаFirefox Android Полная поддержка 48
webRequestBlockingChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 48Opera Полная поддержка ДаFirefox Android Полная поддержка 48

Легенда

Полная поддержка  
Полная поддержка
Нет поддержки  
Нет поддержки
Смотрите замечания реализации.
Смотрите замечания реализации.