説明
chrome.permissions
API を使用すると、宣言されたオプションの権限をインストール時ではなく実行時にリクエストできます。これにより、ユーザーは権限が必要な理由を理解し、必要な権限のみを��与することができます。
コンセプトと使用方法
権限に関する警告は、API によって付与される機能を説明するものですが、わかりにくい場合もあります。Permissions API を使用することで、デベロッパーは権限に関する警告について説明し、新しい機能を段階的に導入できるため、ユーザーはリスクなく拡張機能を体験できます。このようにして、ユーザーは付与するアクセス権の範囲と有効にする機能を指定できます。
たとえば、オプションの権限拡張機能のコア機能は新しいタブページをオーバーライドします。一つは、その日のユーザーの目標を表示する機能です。この機能に必要なのは storage 権限のみです(警告は表示されません)。この拡張機能には追加機能があり、ユーザーは次のボタンをクリックして有効にできます。
ユーザーの上位のサイトを表示するには topSites 権限が必要です。この場合、次の警告が表示されます。
オプションの権限を実装する
ステップ 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.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
プロパティ
-
オリジン
string[] 省略可
ホスト権限のリスト。マニフェストの
optional_permissions
キーまたはpermissions
キーで指定された権限と、コンテンツ スクリプトに関連付けられている権限が含まれます。 -
権限
string[] 省略可
名前付き権限のリスト(ホストやオリジンは含まれません)。
Methods
contains()
chrome.permissions.contains(
permissions: Permissions,
callback?: function,
)
指定された権限が拡張機能にあるかどうかを確認します。
パラメータ
-
権限
-
callback
関数(省略可)
callback
パラメータは次のようになります。(result: boolean) => void
-
件の結果
boolean
指定された権限が拡張機能に付与されている場合は true。オリジンがオプションの権限とコンテンツ スクリプトの一致パターンの両方として指定されている場合、両方の権限が付与されない限り、
false
が返されます。
-
戻り値
-
Promise<boolean>
Chrome 96 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
getAll()
chrome.permissions.getAll(
callback?: function,
)
拡張機能の現在の権限セットを取得します。
パラメータ
-
callback
関数(省略可)
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
関数(省略可)
callback
パラメータは次のようになります。(removed: boolean) => void
-
削除
boolean
権限が削除された場合は true。
-
戻り値
-
Promise<boolean>
Chrome 96 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
request()
chrome.permissions.request(
permissions: Permissions,
callback?: function,
)
指定された権限へのアクセスを要求し、必要に応じてユーザーにプロンプトを表示します。これらの権限は、マニフェストの optional_permissions
フィールドで定義するか、ユーザーが非表示にした必要な権限である必要があります。オリジンのパターンのパスは無視されます。省略可能な元の権限のサブセットをリクエストできます。たとえば、マニフェストの optional_permissions
セクションで *://*\/*
を指定した場合は、http://example.com/
をリクエストできます。権限のリクエストに問題がある場合は、runtime.lastError
が設定されます。
パラメータ
-
権限
-
callback
関数(省略可)
callback
パラメータは次のようになります。(granted: boolean) => void
-
許可
boolean
ユーザーが指定した権限を付与した場合は 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
-
権限
-