Chrome で標準化された browser.* 名前空間がサポートされるようになりました（Chrome 148 以降で利用可能）。ドキュメントは順次更新されます。詳しくは、移行ガイドをご覧ください。

Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

browser.permissions

説明

chrome.permissions API を使用して、インストール時ではなく実行時に宣言されたオプションの権限をリクエストします。これにより、ユーザーは権限が必要な理由を理解し、必要な権限のみを付与できます。

コンセプトと使用方法

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

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

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

topSites API の拡張機能の警告。 — `topSites` API の拡張機能の警告

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

ステップ 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 拡張機能の権限のほとんどは、次の例外を除き、オプションとして指定できます。

権限	説明
`"debugger"`	browser.debugger API は、Chrome のリモートデバッグプロトコルの代替トランスポートとして機能します。
`"declarativeNetRequest"`	拡張機能に browser.declarativeNetRequest API へのアクセス権を付与します。
`"devtools"`	拡張機能で Chrome DevTools の機能を拡張できるようにします。
`"geolocation"`	拡張機能が HTML5 の geolocation API を使用できるようにします。
`"mdns"`	拡張機能に browser.mdns API へのアクセス権を付与します。
`"proxy"`	Chrome のプロキシ設定を管理するための browser.proxy API へのアクセスを拡張機能に付与します。
`"tts"`	browser.tts API は、合成されたテキスト読み上げ（TTS）を再生します。
`"ttsEngine"`	browser.ttsEngine API は、拡張機能を使用してテキスト読み上げ（TTS）エンジンを実装します。
`"wallpaper"`	ChromeOS のみ。browser.wallpaper API を使用して 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.
  browser.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() を使用します。

browser.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() を呼び出すと、通常はユーザーにプロンプトを表示せずに権限が再度追加されます。

browser.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

プロパティ

origins

string[] 省略可

ホスト権限のリスト。マニフェストの optional_permissions キーまたは permissions キーで指定された権限と、コンテンツスクリプトに関連付けられた権限が含まれます。
権限

string[] 省略可

名前付き権限のリスト（ホストやオリジンは含まれません）。

メソッド

addHostAccessRequest()

Chrome 133 以降 Chrome 148 以降の browser.* MV3 以降

browser.permissions.addHostAccessRequest(
  request: object,
): Promise<void>

ホストアクセスリクエストを追加します。リクエストは、リクエスト内のホストへのアクセス権を拡張機能に付与できる場合にのみ、ユーザーに通知されます。リクエストはクロスオリジンナビゲーションでリセットされます。承認されると、サイトのトップオリジンへの永続的なアクセス権が付与されます

パラメータ

リクエスト

オブジェクト
- documentId
  
  文字列省略可
  
  ホストアクセスリクエストを表示できるドキュメントの ID。タブ内の最上位のドキュメントである必要があります。指定すると、リクエストは指定されたドキュメントのタブに表示され、ドキュメントが新しいオリジンに移動すると削除されます。新しいリクエストを追加すると、tabId の既存のリクエストはオーバーライドされます。これまたは tabId を指定する必要があります。
- パターン
  
  文字列省略可
  
  ホストアクセスリクエストを表示できる URL パターン。指定した場合、ホストアクセスリクエストは、このパターンに一致する URL にのみ表示されます。
- tabId
  
  number 省略可
  
  ホストアクセスリクエストを表示できるタブの ID。指定した場合、リクエストは指定されたタブに表示され、タブが新しいオリジンに移動すると削除されます。新しいリクエストを追加すると、documentId の既存のリクエストがオーバーライドされます。これまたは documentId を指定する必要があります。

戻り値

Promise<void>

contains()

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

拡張機能に指定された権限があるかどうかを確認します。

パラメータ

権限

権限

戻り値

Promise<boolean>

Chrome 96 以降 Chrome 148 以降の browser.*

getAll()

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

拡張機能の現在の権限セットを取得します。

戻り値

Promise<Permissions>

Chrome 96 以降 Chrome 148 以降の browser.*

remove()

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

指定した権限へのアクセス権を削除します。権限の削除に問題がある場合、Promise は拒否されます。

パラメータ

権限

権限

戻り値

Promise<boolean>

Chrome 96 以降 Chrome 148 以降の browser.*

removeHostAccessRequest()

Chrome 133 以降 Chrome 148 以降の browser.* MV3 以降

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

ホストアクセスリクエストが存在する場合は削除します。

パラメータ

リクエスト

オブジェクト
- documentId
  
  文字列省略可
  
  ホストアクセスリクエストが削除されるドキュメントの ID。タブ内の最上位のドキュメントである必要があります。これまたは tabId を指定する必要があります。
- パターン
  
  文字列省略可
  
  ホストアクセスリクエストが削除される URL パターン。指定する場合、既存のホストアクセスリクエストのパターンと完全に一致する必要があります。
- tabId
  
  number 省略可
  
  ホストアクセスリクエストが削除されるタブの ID。これまたは documentId を指定する必要があります。

戻り値

Promise<void>

request()

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

指定された権限へのアクセスをリクエストし、必要に応じてユーザーにプロンプトを表示します。これらの権限は、マニフェストの optional_permissions フィールドで定義されているか、ユーザーによって保留された必須の権限である必要があります。オリジンパターンのパスは無視されます。オプションのオリジン権限のサブセットをリクエストできます。たとえば、マニフェストの optional_permissions セクションで *://*\/* を指定すると、http://example.com/ をリクエストできます。権限のリクエストに問題がある場合、Promise は拒否されます。

パラメータ

権限

権限

戻り値

Promise<boolean>

Chrome 96 以降 Chrome 148 以降の browser.*

イベント

onAdded

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

拡張機能が新しい権限を取得したときに呼び出されます。

パラメータ

callback

関数

callback パラメータは次のようになります。
```
(permissions: Permissions) => void
```
- 権限
  
  権限

onRemoved

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

拡張機能から権限へのアクセスが削除されたときに呼び出されます。

パラメータ

callback

関数

callback パラメータは次のようになります。
```
(permissions: Permissions) => void
```
- 権限
  
  権限

browser.permissions コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

説明

コンセプトと使用方法

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

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

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

ステップ 3: オプションの権限をリクエストする

ステップ 4: 拡張機能の現在の権限を確認する

ステップ 5: 権限を削除する

型

Permissions

プロパティ

メソッド

addHostAccessRequest()

パラメータ

戻り値

contains()

パラメータ

戻り値

getAll()

戻り値

remove()

パラメータ

戻り値

removeHostAccessRequest()

パラメータ

戻り値

request()

パラメータ

戻り値

イベント

onAdded

パラメータ

onRemoved

パラメータ

browser.permissions