説明
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 の機能を拡張できるようにします。 |
"geolocation" |
拡張機能が HTML5 の 位置情報 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();
}
});
});
権限を追加すると、ユーザーがすでに表示して承認した警告メッセージとは異なるメッセージが表示される場合は、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[] 省略可
名前付き権限のリスト（ホストやオリジンは含まれません）。
メソッド
addHostAccessRequest()
chrome.permissions.addHostAccessRequest(
request: object,
callback?: function,
)
ホストアクセス リクエストを追加します。リクエストでホストへのアクセス権を拡張機能に付与できる場合にのみ、リクエストがユーザーに通知されます。クロスオリジン ナビゲーション時にリクエストがリセットされます。承認されると、サイトのトップオリジンへの永続的なアクセス権が付与されます
パラメータ
-
リクエスト
オブジェクト
-
documentId
文字列 省略可
ホストアクセス リクエストを表示できるドキュメントの ID。タブ内の最上位ドキュメントである必要があります。指定すると、リクエストは指定されたドキュメントのタブに表示され、ドキュメントが新しいオリジンに移動すると削除されます。新しいリクエストを追加すると、
tabIdの既存のリクエストがオーバーライドされます。この値またはtabIdを指定する必要があります。 -
パターン
文字列 省略可
ホストアクセス リクエストを表示できる URL パターン。指定した場合、ホストアクセス リクエストは、このパターンに一致する URL でのみ表示されます。
-
tabId
number（省略可）
ホストアクセス リクエストを表示できるタブの ID。指定すると、リクエストは指定したタブに表示され、タブが新しいオリジンに移動すると削除されます。新しいリクエストを追加すると、
documentIdの既存のリクエストがオーバーライドされます。この値またはdocumentIdを指定する必要があります。
-
-
callback
function 省略可
callbackパラメータは次のようになります。() => void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。
contains()
chrome.permissions.contains(
permissions: Permissions,
callback?: function,
)
拡張機能に指定された権限があるかどうかを確認します。
パラメータ
-
権限
-
callback
function 省略可
callbackパラメータは次のようになります。(result: boolean) => void
-
件の結果
ブール値
拡張機能に指定された権限がある場合は true。オリジンが省略可能な権限とコンテンツ スクリプトの一致パターンの両方として指定されている場合、両方の権限が付与されていない限り、
falseが返されます。
-
戻り値
-
Promise<boolean>
Chrome 96 以降Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。
getAll()
chrome.permissions.getAll(
callback?: function,
)
拡張機能の現在の権限セットを取得します。
パラメータ
-
callback
function 省略可
callbackパラメータは次のようになります。(permissions: Permissions) => void
-
権限
拡張機能の有効な権限。
originsプロパティには、マニフェストのpermissionsキーとoptional_permissionsキーで指定された生成元と、コンテンツ スクリプトに関連付けられた生成元の承認済み生成元が含まれます。
-
戻り値
-
Promise<Permissions>
Chrome 96 以降Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。
remove()
chrome.permissions.remove(
permissions: Permissions,
callback?: function,
)
指定した権限へのアクセス権を削除します。権限の削除に問題がある場合は、runtime.lastError が設定されます。
パラメータ
-
権限
-
callback
function 省略可
callbackパラメータは次のようになります。(removed: boolean) => void
-
削除済み
ブール値
権限が削除された場合は true。
-
戻り値
-
Promise<boolean>
Chrome 96 以降Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。
removeHostAccessRequest()
chrome.permissions.removeHostAccessRequest(
request: object,
callback?: function,
)
ホスト アクセス リクエストを削除します（存在する場合）。
パラメータ
-
リクエスト
オブジェクト
-
documentId
文字列 省略可
ホストのアクセス リクエストが削除されるドキュメントの ID。タブ内の最上位ドキュメントである必要があります。この値または
tabIdを指定する必要があります。 -
パターン
文字列 省略可
ホストのアクセス リクエストが削除される URL パターン。指定する場合は、既存のホストアクセス リクエストのパターンと完全に一致する必要があります。
-
tabId
number（省略可）
ホストのアクセス リクエストが削除されるタブの ID。この値または
documentIdを指定する必要があります。
-
-
callback
function 省略可
callbackパラメータは次のようになります。() => void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。
request()
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 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。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
-
権限
-