chrome.permissions

説明

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

概要

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

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

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

ユーザーのトップサイトを表示するには、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.proxy API へのアクセス権を付与して、Chrome のプロキシ設定を管理します。
"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();
    }
  });
});

権限を追加した結果、ユーザーがすでに表示して承認した警告メッセージとは異なるメッセージが表示された場合は、ユーザーにプロンプトが表示されます。たとえば、上記のコードでは次のようなプロンプトが表示されます。

権限確認プロンプトの例

ステップ 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

プロパティ

  • 送信元

    string[] 省略可

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

  • 権限

    string[] 省略可

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

メソッド

addHostAccessRequest()

Promise 保留中MV3 以降 
chrome.permissions.addHostAccessRequest(
  request: object,
  callback?: function,
)

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

パラメータ

  • request

    オブジェクト

    • documentId

      文字列（省略可）

      ホストアクセス リクエストを表示できるドキュメントの ID。タブ内の最上位のドキュメントである必要があります。指定すると、リクエストは指定されたドキュメントのタブに表示され、ドキュメントが新しいオリジンに移動すると削除されます。新しいリクエストを追加すると、tabId の既存のリクエストがオーバーライドされます。この値または tabId を指定する必要があります。

    • パターン

      文字列（省略可）

      ホストアクセス リクエストを表示できる URL パターン。指定した場合、ホストアクセス リクエストは、このパターンに一致する URL でのみ表示されます。

    • tabId

      number（省略可）

      ホストアクセス リクエストを表示できるタブの ID。指定すると、リクエストは指定されたタブに表示され、タブが新しいオリジンに移動すると削除されます。新しいリクエストを追加すると、documentId の既存のリクエストがオーバーライドされます。この値または documentId を指定する必要があります。

  • callback

    function 省略可

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

    () => void

戻り値

  • Promise<void>

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

contains()

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

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

パラメータ

  • 権限

    権限

  • callback

    function 省略可

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

    (result: boolean) => void

    • 件の結果

      ブール値

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

戻り値

  • Promise<boolean>

    Chrome 96 以降

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

getAll()

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

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

パラメータ

  • 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,
)

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

パラメータ

  • 権限

    権限

  • callback

    function 省略可

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

    (removed: boolean) => void

    • 削除済み

      ブール値

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

戻り値

  • Promise<boolean>

    Chrome 96 以降

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

removeHostAccessRequest()

Promise 保留中MV3 以降 
chrome.permissions.removeHostAccessRequest(
  request: object,
  callback?: function,
)

ホスト アクセス リクエストを削除します（存在する場合）。

パラメータ

  • request

    オブジェクト

    • documentId

      文字列（省略可）

      ホストのアクセス リクエストが削除されるドキュメントの ID。タブ内の最上位のドキュメントである必要があります。この値または tabId を指定する必要があります。

    • パターン

      文字列（省略可）

      ホスト アクセス リクエストが削除される URL パターン。指定する場合は、既存のホストアクセス リクエストのパターンと完全に一致する必要があります。

    • tabId

      number（省略可）

      ホストのアクセス リクエストが削除されるタブの ID。この値または documentId を指定する必要があります。

  • callback

    function 省略可

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

    () => void

戻り値

  • Promise<void>

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

request()

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

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

パラメータ

  • 権限

    権限

  • 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