chrome.permissions

説明

コンセプトと使用方法

権限の警告は、API によって付与される機能を説明するために存在しますが、一部の警告はわかりにくい場合があります。Permissions API を使用すると、デベロッパーは権限に関する警告を説明し、新機能を段階的に導入できます。これにより、ユーザーは拡張機能をリスクなしで試すことができます。これにより、ユーザーは付与するアクセス権の範囲と有効にする機能を指定できます。

たとえば、オプションの権限拡張機能のコア機能は、新しいタブページをオーバーライドすることです。1 つの機能は、ユーザーの 1 日の目標を表示します。この機能に必要なのは storage 権限のみで、警告は含まれません。この拡張機能には、次のボタンをクリックして有効にできる追加機能があります。

ユーザーのトップサイトを表示するには、topSites 権限が必要です。この権限には次の警告が表示されます。

オプションの権限を実装する

ステップ 1: 必須の権限とオプションの権限を決定する

拡張機能では、必須の権限とオプションの権限の両方を宣言できます。一般的には、次のように指定します。

• 拡張機能の基本機能に必要な場合は、必須の権限を使用します。
• 拡張機能のオプション機能に必要な場合は、オプションの権限を使用します。

必須権限のメリット:

• プロンプトの回数が少ない: 拡張機能は、すべての権限を承認するようユーザーに 1 回だけプロンプトを表示できます。
• 開発の簡素化: 必要な権限が必ず存在することが保証されます。

省略可の権限のメリット:

• セキュリティの向上: ユーザーが必要な権限のみを有効にするため、拡張機能はより少ない権限で実行されます。
• ユーザーにわかりやすい情報: ユーザーが関連機能を有効にしたときに、拡張機能が特定の権限を必要とする理由を説明できます。
• アップグレードが容易に: 拡張機能をアップグレードする際に、アップグレードで必須の権限ではなくオプションの権限が追加された場合、Chrome はユーザーの拡張機能を無効にしません。

ステップ 2: マニフェストでオプションの権限を宣言する

permissions フィールドと同じ形式で、optional_permissions キーを使用して、拡張機能のマニフェストでオプションの権限を宣言します。

{
  "name": "My extension",
  ...
  "optional_permissions": ["tabs"],
  "optional_host_permissions": ["https://www.google.com/"],
  ...
}

実行時にのみ検出されるホストをリクエストする場合は、拡張機能の optional_host_permissions フィールドに "https://*/*" を含めます。これにより、一致するスキームがある限り、"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.addHostAccessRequest(
  request: object,
): Promise<void>

chrome.permissions.contains(
  permissions: Permissions,
): Promise<boolean>

chrome.permissions.getAll(): Promise<Permissions>

chrome.permissions.remove(
  permissions: Permissions,
): Promise<boolean>

chrome.permissions.removeHostAccessRequest(
  request: object,
): Promise<void>

chrome.permissions.request(
  permissions: Permissions,
): Promise<boolean>

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

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