permissions

Тип Массив
Обязателен Нет
Пример
json;

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

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

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

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

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

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

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

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

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

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

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

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

js
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 полномочия выдадутся для вкладки, по которой было произведено нажатие, несмотря на то, что она могла бы не является активной (Firefox bug 1446956 начиная с Firefox версии 63).

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

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

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

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

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

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

Примеры

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

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

json
  "permissions": ["tabs"]

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

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

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

Совместимость с браузерами

BCD tables only load in the browser