説明
chrome.contentSettings
API を使用して、ウェブサイトが Cookie、JavaScript、プラグインなどの機能を使用できるかどうかを制御する設定を変更します。大まかに言うと、コンテンツ設定では、Chrome の動作をグローバルではなくサイト単位でカスタマイズできます。
権限
contentSettings
API を使用するには、拡張機能のマニフェストで "contentSettings"
権限を宣言する必要があります。次に例を示します。
{
"name": "My extension",
...
"permissions": [
"contentSettings"
],
...
}
コンセプトと使用方法
コンテンツの設定パターン
各コンテンツ設定が影響を及ぼすウェブサイトをパターンを使って指定できます。たとえば、https://*.youtube.com/*
は youtube.com とそのすべてのサブドメインを指定します。コンテンツ設定パターンの構文は、マッチパターンの構文と同じですが、いくつかの違いがあります。
http
、https
、ftp
の URL の場合、パスはワイルドカード(/*
)にする必要があります。file
URL の場合、パスは完全に指定する必要があります。ワイルドカードは含めないでください。- 一致パターンとは異なり、コンテンツ設定パターンではポート番号を指定できます。ポート番号を指定した場合は、そのポートを持つウェブサイトのみがパターンに一致します。ポート番号を指定しない場合、このパターンはすべてのポートと一致します。
パターンの優先順位
1 つのサイトに対して複数のコンテンツ設定ルールが適用される場合は、より具体的なパターンのルールが優先されます。
たとえば、次のパターンは優先順位で並べ替えられています。
https://www.example.com/*
https://*.example.com/*
(example.com とすべてのサブドメインに一致)<all_urls>
(すべての URL に一致)
パターンの特定度には、次の 3 種類のワイルドカードが影響します。
- ポート内のワイルドカード(例:
https://www.example.com:*/*
) - スキーム内のワイルドカード(
*://www.example.com:123/*
など) - ホスト名にワイルドカードを使用する(例:
https://*.example.com:123/*
)
ある部分では別のパターンよりも具体的なパターンが、別の部分では具体的でないパターンの場合、各部分はホスト名、スキーム、ポートの順にチェックされます。たとえば、次のパターンは優先順位順に並んでいます。
https://www.example.com:*/*
ホスト名とスキームを指定します。*:/www.example.com:123/*
ホスト名は指定されているものの、スキームは指定されていないため、それほど高くありません。https://*.example.com:123/*
ポートとスキームは指定されているものの、ホスト名にワイルドカードが含まれているため、低くなります。
プライマリ パターンとセカンダリ パターン
適用するコンテンツ設定を決定する際に考慮される URL は、コンテンツの種類によって異なります。
たとえば、contentSettings.notifications
の場合、設定はアドレスバーに表示される URL に基づきます。この URL は「メイン」URL と呼ばれます。
コンテンツ タイプによっては、追加の URL を考慮できます。たとえば、サイトが contentSettings.cookies
を設定できるかどうかは、HTTP リクエストの URL(この場合はプライマリ URL)と、オムニボックスに表示される URL(「セカンダリ」URL)に基づいて決定されます。
複数のルールにプライマリ パターンとセカンダリ パターンがある場合は、より具体的なプライマリ パターンを持つルールが優先されます。同じプライマリ パターンを持つルールが複数ある場合は、より限定的なセカンダリ パターンのルールが優先されます。たとえば、次のプライマリ / セカンダリ パターンペアのリストは、優先順位で並べられています。
優先度 | メインのパターン | サブパターン |
---|---|---|
1 | https://www.moose.com/* | https://www.wombat.com/* |
2 | https://www.moose.com/* | <all_urls> |
3 | <all_urls> | https://www.wombat.com/* |
4 | <all_urls> | <all_urls> |
画像コンテンツの設定では、セカンダリ パターンはサポートされていません。
リソース識別子
リソース ID を使用すると、コンテンツ タイプの特定のサブタイプにコンテンツ設定を指定できます。現在、リソース ID をサポートするコンテンツ タイプは contentSettings.plugins
のみです。リソース ID は特定のプラグインを識別します。コンテンツの設定を適用するときは、まず特定のプラグインの設定が確認されます。特定のプラグインの設定が見つからない場合は、プラグインの一般的なコンテンツ設定がチェックされます。
たとえば、コンテンツ設定ルールにリソース識別子が adobe-flash-player
でパターンが <all_urls>
の場合、そのパターンがより具体的であっても、リソース識別子とパターン https://www.example.com/*
のないルールよりも優先されます。
コンテンツ タイプのリソース識別子のリストを取得するには、contentSettings.ContentSetting.getResourceIdentifiers()
メソッドを呼び出します。返されるリストは、ユーザーのマシンにインストールされているプラグインによって異なりますが、Chrome はプラグインの更新後も識別子が一定になるようにします。
例
この API を試すには、chrome-extension-samples リポジトリから contentSettings API の例をインストールします。
型
AutoVerifyContentSetting
列挙型
"allow"
「block」
CameraContentSetting
列挙型
"allow"
ClipboardContentSetting
列挙型
"allow"
ContentSetting
プロパティ
-
クリア
void
Promiseこの拡張機能で設定されたすべてのコンテンツ設定ルールを消去します。
clear
関数は次のようになります。(details: object, callback?: function) => {...}
-
詳細
オブジェクト
-
スコープ
範囲(省略可)
設定をクリアする場所(デフォルト: 標準)。
-
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
-
戻り値
約束 <void>
Chrome 96 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。
-
-
get
void
Promise指定された URL ペアの現在のコンテンツ設定を取得します。
get
関数は次のようになります。(details: object, callback?: function) => {...}
-
詳細
オブジェクト
-
シークレット モード
ブール値(省略可)
シークレット セッションのコンテンツ設定を確認するかどうかを指定します。(デフォルトは false)
-
primaryUrl
文字列
コンテンツ設定を取得するプライマリ URL。プライマリ URL の意味はコンテンツ タイプによって異なります。
-
resourceIdentifier
設定を取得するコンテンツの種類をより具体的に識別する ID。
-
secondaryUrl
文字列(省略可)
コンテンツ設定を取得するセカンダリ URL。デフォルトはプライマリ URL です。セカンダリ URL の意味はコンテンツ タイプによって異なり、すべてのコンテンツ タイプでセカンダリ URL が使用されるわけではありません。
-
-
callback
関数(省略可)
callback
パラメータは次のようになります。(details: object) => void
-
詳細
オブジェクト
-
設定
T
コンテンツの設定。設定可能な値については、個々の ContentSetting オブジェクトの説明をご覧ください。
-
-
-
戻り値
Promise <オブジェクト>
Chrome 96 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise はコールバックに渡された型と同じ型で解決されます。
-
-
getResourceIdentifiers
void
PromisegetResourceIdentifiers
関数は次のようになります。(callback?: function) => {...}
-
callback
関数(省略可)
callback
パラメータは次のようになります。(resourceIdentifiers?: ResourceIdentifier[]) => void
-
resourceIdentifiers
ResourceIdentifier[] 省略可
このコンテンツ タイプのリソース識別子のリスト。このコンテンツ タイプでリソース識別子を使用しない場合は
undefined
。
-
-
戻り値
Promise<ResourceIdentifier[]>
Chrome 96 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。
-
-
set
void
Promise新しいコンテンツ設定ルールを適用します。
set
関数は次のようになります。(details: object, callback?: function) => {...}
-
詳細
オブジェクト
-
primaryPattern
文字列
メインの URL のパターン。パターンの形式について詳しくは、コンテンツ設定パターンをご覧ください。
-
resourceIdentifier
ResourceIdentifier(省略可)
コンテンツ タイプのリソース ID。
-
スコープ
範囲(省略可)
設定を行う場所(デフォルト: 標準)。
-
secondaryPattern
文字列(省略可)
セカンダリ URL のパターン。デフォルトでは、すべての URL に一致します。パターンの形式について詳しくは、コンテンツ設定のパターンをご覧ください。
-
設定
任意
このルールによって適用される設定。設定可能な値については、個々の ContentSetting オブジェクトの説明をご覧ください。
-
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
-
戻り値
約束 <void>
Chrome 96 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。
-
CookiesContentSetting
列挙型
"allow"
"session_only"
FullscreenContentSetting
値
"allow"
ImagesContentSetting
列挙型
"allow"
「block」
JavascriptContentSetting
列挙型
"allow"
「block」
LocationContentSetting
列挙型
"allow"
MicrophoneContentSetting
列挙型
"allow"
MouselockContentSetting
値
"allow"
MultipleAutomaticDownloadsContentSetting
列挙型
"allow"
NotificationsContentSetting
列挙型
"allow"
PluginsContentSetting
値
PopupsContentSetting
列挙型
"allow"
「block」
PpapiBrokerContentSetting
値
「block」
ResourceIdentifier
リソース識別子を使用するコンテンツ タイプは contentSettings.plugins
のみです。詳細については、リソース識別子をご覧ください。
プロパティ
-
description
文字列(省略可)
リソースの説明(人が読める形式)。
-
id
文字列
指定されたコンテンツ タイプのリソース ID。
Scope
ContentSetting のスコープ。regular
のいずれか: 通常のプロファイルの設定(他の場所でオーバーライドされていない場合はシークレット モードのプロファイルに継承されます)、incognito\_session\_only
: シークレット セッション中にのみ設定でき、シークレット セッションが終了すると削除(通常の設定をオーバーライド)するシークレット プロファイルの設定。
列挙型
プロパティ
automaticDownloads
サイトが複数のファイルを自動的にダウンロードできるようにするかどうか。次のいずれか
allow
: サイトに複数のファイルの自動ダウンロードを許可する
block
: サイトによる複数のファイルの自動ダウンロードを許可しない
ask
: サイトが最初のファイルの後にあるファイルを自動的にダウンロードする必要があるときに確認します。
デフォルトは ask
です。プライマリ URL は、最上位フレームの URL です。セカンダリ URL は使用されません。
autoVerify
サイトに Private State Tokens API の使用を許可するかどうかを指定します。allow
のいずれか: サイトに Private State Tokens API の使用を許可します。block
: サイトによる Private State Tokens API の使用をブロックします。デフォルトは allow
です。プライマリ URL は、最上位フレームの URL です。セカンダリ URL は使用されません。注: set()
を呼び出す場合、プライマリ パターンは にする必要があります。
タイプ
camera
サイトにカメラへのアクセスを許可するかどうか。次のいずれか。
allow
: サイトがカメラにアクセスできるようにする
block
: サイトがカメラにアクセスできないようにする
ask
: サイトがカメラにアクセスする際に確認する
デフォルトは ask
です。プライマリ URL は、カメラへのアクセスをリクエストしたドキュメントの URL です。セカンダリ URL は使用されません。注: 両方のパターンが「」の場合、「許可」の設定は無効になります。
タイプ
clipboard
サイトが Async Clipboard API の高度な機能を使用してクリップボードにアクセスできるようにするかどうか。「高度な」機能には、ユーザーの操作後に組み込み形式の書き込み以外にもあらゆる機能が含まれます。たとえば、読み取り、カスタム形式の書き込み、ユーザー操作なしでの書き込みが可能になります。次のいずれか: allow
: サイトに高度なクリップボード機能の使用を許可する
block
: サイトによる高度なクリップボード機能の使用を許可しない
ask
: サイトが高度なクリップボード機能を使用する必要があるときに確認します。
デフォルトは ask
です。プライマリ URL はクリップボードへのアクセスをリクエストしたドキュメントの URL です。セカンダリ URL は使用されません。
cookies
Cookie などのローカルデータをウェブサイトが設定することを許可するかどうかを指定します。allow
: Cookie を受け入れる、block
: Cookie をブロックする、session\_only
: 現在のセッションでのみ Cookie を受け入れる、のいずれか。デフォルトは allow
です。プライマリ URL は Cookie 生成元を表す URL です。セカンダリ URL は、最上位フレームの URL です。
タイプ
fullscreen
非推奨。効果はありません。全画面の権限がすべてのサイトに自動的に付与されるようになりました。値は常に allow
です。
images
画像を表示するかどうか。次のいずれか: allow
: 画像を表示します。
block
: 画像を表示しません。デフォルトは allow
です。プライマリ URL は、最上位フレームの URL です。セカンダリ URL は画像の URL です。
javascript
JavaScript を実行するかどうか。allow
: JavaScript を実行、block
: JavaScript を実行しないのいずれか。デフォルトは allow
です。プライマリ URL は、最上位フレームの URL です。セカンダリ URL は使用されません。
location
位置情報を許可するかどうかを指定します。次のいずれか
allow
: サイトに物理的な現在地の追跡を許可する
block
: サイトに物理的な現在地の追跡を許可しない
ask
: サイトに物理的な現在地の追跡を許可する前に確認します。
デフォルトは ask
です。プライマリ URL は、位置情報をリクエストしたドキュメントの URL です。セカンダリ URL は最上位フレームの URL です(リクエスト URL と異なってもかまいません)。
タイプ
microphone
サイトにマイクへのアクセスを許可するかどうかを指定します。次のいずれか: allow
: サイトにマイクへのアクセスを許可する。
block
: サイトにマイクへのアクセスを許可しない
ask
: サイトがマイクへのアクセスを求められたときに確認する。
デフォルトは ask
です。プライマリ URL は、マイクへのアクセスをリクエストしたドキュメントの URL です。セカンダリ URL は使用されません。注: 両方のパターンが「''」の場合、「許可」の設定は無効です。
タイプ
mouselock
非推奨。効果はありません。すべてのサイトに対してマウスロックの権限が自動的に付与されるようになりました。値は常に allow
です。
タイプ
notifications
サイトにデスクトップ通知の表示を許可するかどうか。次のいずれか:
allow
: サイトにデスクトップ通知を表示することを許可する
block
: サイトにデスクトップ通知を表示することを許可しない
ask
: サイトにデスクトップ通知を表示するかどうかを尋ねる
デフォルトは ask
です。プライマリ URL は、通知を表示するドキュメントの URL です。セカンダリ URL は使用されません。
タイプ
plugins
非推奨。Chrome 88 で Flash のサポートが終了すると、この権限は無効になります。値は常に block
です。set()
と clear()
の呼び出しは無視されます。
タイプ
popups
サイトにポップアップの表示を許可するかどうか。次のいずれか: allow
: サイトにポップアップの表示を許可する、block
: サイトにポップアップの表示を許可しない。デフォルトは block
です。プライマリ URL は、最上位フレームの URL です。セカンダリ URL は使用されません。
タイプ
unsandboxedPlugins
非推奨。これまでは、サンドボックスなしでプラグインの実行をサイトに許可するかどうかを指定していましたが、Chrome 88 で Flash ブローカー プロセスが削除されたため、この権限は無効になります。値は常に block
です。set()
と clear()
の呼び出しは無視されます。