chrome.permissions

説明

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

コンセプトと使用方法

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

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

<ph type="x-smartling-placeholder">
</ph> 追加機能を有効にする拡張機能ボタン。 追加機能を有効にする拡張機能ボタン。

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

<ph type="x-smartling-placeholder">
</ph> topSites API の Axtension 警告。
topSites API の拡張機能に関する警告

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

ステップ 1: 必要な権限と任意の権限を決定する

拡張機能では、必要な権限と省略可能な権限の両方を宣言できます。一般的に、次の点に注意してください。

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

必須権限の利点は次のとおりです。

  • メッセージの表示数を減らす: 拡張機能では、すべての権限を許可するようユーザーに 1 回だけ確認することができます。
  • 開発の簡素化: 必要な権限が存在することが保証されています。

オプション権限のメリット:

  • セキュリティの強化: ユーザーは権限のみを有効にするため、拡張機能の実行権限は少なくなります 必要があります。
  • ユーザーにわかりやすい情報を提供: 拡張機能では、特定の権限が必要な理由を説明できます ユーザーが関連する機能を有効にしたとき。
  • アップグレードがより簡単に: 拡張機能をアップグレードすると、 アップグレードにより、必須ではなく任意の権限が追加されます。

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

拡張機能のマニフェストで optional_permissions キーを使用して、オプションの権限を宣言します。 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 を展開できるようにします 説明します。
"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();
    }
  });
});

権限を追加した結果として警告メッセージが 表示して承諾しました。たとえば、前述のコードでは、次のようなプロンプトが表示されます。 これを次のように使用します。

<ph type="x-smartling-placeholder">
</ph> 権限確認プロンプトの例。
権限確認プロンプトの例

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

プロパティ

  • オリジン

    文字列 [] 省略可

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

  • 権限

    文字列 [] 省略可

    名前付き権限のリスト（ホストや送信元は含まれません）。

メソッド

contains()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

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

パラメータ

  • 権限

    権限

  • callback

    関数（省略可）

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

    (result: boolean) => void

    • 件の結果

      ブール値

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

戻り値

  • Promise&lt;boolean&gt;

    Chrome 96 以降

    Promise は Manifest V3 以降でサポートされていますが、 下位互換性が確保されます同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

getAll()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.permissions.getAll(
  callback?: function,
)

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

パラメータ

  • callback

    関数（省略可）

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

    (permissions: Permissions) => void

    • 権限

      権限

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

戻り値

  • Promise&lt;Permissions&gt;

    Chrome 96 以降

    Promise は Manifest V3 以降でサポートされていますが、 下位互換性が確保されます同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

remove()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)

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

パラメータ

  • 権限

    権限

  • callback

    関数（省略可）

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

    (removed: boolean) => void

    • 削除済み

      ブール値

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

戻り値

  • Promise&lt;boolean&gt;

    Chrome 96 以降

    Promise は Manifest V3 以降でサポートされていますが、 下位互換性が確保されます同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

request()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
)

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

パラメータ

  • 権限

    権限

  • callback

    関数（省略可）

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

    (granted: boolean) => void

    • 許可

      ブール値

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

戻り値

  • Promise&lt;boolean&gt;

    Chrome 96 以降

    Promise は Manifest V3 以降でサポートされていますが、 下位互換性が確保されます同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

イベント

onAdded

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

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

パラメータ

  • callback

    関数

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

    (permissions: Permissions) => void

onRemoved

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

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

パラメータ

  • callback

    関数

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

    (permissions: Permissions) => void