chrome.permissions

更新日: 2026-09-25 robots: noindex

説明

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

概要

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

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

追加機能を有効にする拡張機能ボタン

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

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

型

Permissions

プロパティ

  • origins

    string[] 省略可

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

  • 権限

    string[] 省略可

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

メソッド

contains()

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

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

パラメータ

  • 権限

    権限

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    (result: boolean) => void

    • 件の結果

      ブール値

      拡張機能に指定された権限がある場合は true。オリジンがオプションの権限とコンテンツ スクリプトの一致パターンの両方として指定されている場合、両方の権限が付与されていない限り、false が返されます。

戻り値

  • Promise<boolean>

    Chrome 96 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

getAll()

Promise 
chrome.permissions.getAll(
  callback?: function,
): Promise<Permissions>

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

パラメータ

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    (permissions: Permissions) => void

    • 権限

      権限

      拡張機能のアクティブな権限。origins プロパティには、マニフェストの permissions キーと optional_permissions キーで指定されたオリジンと、コンテンツ スクリプトに関連付けられたオリジンが含まれます。

戻り値

  • Promise<Permissions>

    Chrome 96 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

remove()

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

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

パラメータ

  • 権限

    権限

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    (removed: boolean) => void

    • 削除済み

      ブール値

      権限が削除された場合は true。

戻り値

  • Promise<boolean>

    Chrome 96 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

request()

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

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

パラメータ

  • 権限

    権限

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    (granted: boolean) => void

    • 許可

      ブール値

      ユーザーが指定された権限を付与している場合は true。

戻り値

  • Promise<boolean>

    Chrome 96 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

イベント

onAdded

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

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

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (permissions: Permissions) => void

onRemoved

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

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

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (permissions: Permissions) => void