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 можно указать как необязательные, за следующими исключениями.

Просмотрите «Объявить разрешения» для получения дополнительной информации о доступных разрешениях и предупреждениях о них.

Шаг 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).
  }
});

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

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

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

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

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

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

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

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

Описание

Концепции и использование

Предупреждения о разрешениях существуют для описания возможностей, предоставляемых 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 можно указать как необязательные, за следующими исключениями.

Просмотрите «Объявить разрешения» для получения дополнительной информации о доступных разрешениях и предупреждениях о них.

Шаг 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).
  }
});

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

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

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

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

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

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

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

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