説明
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> |
リソース識別子
リソース識別子を使用すると、コンテンツ タイプの特定のサブタイプに対してコンテンツ設定を指定できます。現在、リソース識別子をサポートしているコンテンツ タイプは contentSettings.plugins
のみです。リソース識別子は特定のプラグインを識別します。コンテンツの設定を適用する際は、まず特定のプラグインの設定を確認します。特定のプラグインに対する設定が見つからない場合は、プラグインの一般的なコンテンツ設定を確認します。
たとえば、リソース ID が adobe-flash-player
でパターンが <all_urls>
のコンテンツ設定ルールがある場合、パターンがより具体的であっても、リソース ID とパターン https://www.example.com/*
のないルールよりも優先されます。
コンテンツ タイプのリソース識別子のリストを取得するには、contentSettings.ContentSetting.getResourceIdentifiers
メソッドを呼び出します。返されるリストは、ユーザーのマシンにインストールされているプラグインのセットに応じて変わる可能性がありますが、Chrome はプラグインの更新全体で識別子の安定性を維持しようとします。
例
この API を試すには、chrome-extension-samples リポジトリから contentSettings API の例をインストールしてください。
型
AutoVerifyContentSetting
Enum
"block"
CameraContentSetting
Enum
"block"
ClipboardContentSetting
Enum
"block"
ContentSetting
プロパティ
-
消去
void
Promiseこの拡張機能で設定されたコンテンツ設定ルールをすべてクリアします。
clear
関数は次のようになります。(details: object, callback?: function) => {...}
-
詳細
オブジェクト
-
スコープ
範囲(省略可)
設定をクリアする場所(デフォルト: 標準)。
-
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
-
戻り値
Promise<void>
Chrome 96 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
-
-
get
void
Promise指定した URL ペアの現在のコンテンツ設定を取得します。
get
関数は次のようになります。(details: object, callback?: function) => {...}
-
詳細
オブジェクト
-
シークレット モード
ブール値(省略可)
シークレット セッションのコンテンツ設定を確認するかどうかを指定します。(デフォルトは false)
-
primaryUrl
文字列
コンテンツ設定を取得するプライマリ URL。プライマリ URL の意味は、コンテンツ タイプによって異なります。
-
resourceIdentifier
設定を取得するコンテンツ タイプの、より具体的な識別子。
-
secondaryUrl
string(省略可)
コンテンツ設定を取得するセカンダリ URL。デフォルトはプライマリ URL です。サブ URL の意味はコンテンツ タイプによって異なります。また、すべてのコンテンツ タイプでサブ URL が使用されるわけではありません。
-
-
callback
関数(省略可)
callback
パラメータは次のようになります。(details: object) => void
-
詳細
オブジェクト
-
設定
T
コンテンツの設定。設定可能な値については、個々の ContentSetting オブジェクトの説明をご覧ください。
-
-
-
戻り値
Promise<object>
Chrome 96 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
-
-
getResourceIdentifiers
void
PromisegetResourceIdentifiers
関数は次のようになります。(callback?: function) => {...}
-
callback
関数(省略可)
callback
パラメータは次のようになります。(resourceIdentifiers?: ResourceIdentifier[]) => void
-
resourceIdentifiers
ResourceIdentifier[] 省略可
このコンテンツ タイプのリソース識別子のリスト。このコンテンツ タイプがリソース識別子を使用しない場合は
undefined
。
-
-
戻り値
Promise<ResourceIdentifier[]>
Chrome 96 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
-
-
set
void
Promise新しいコンテンツ設定ルールを適用します。
set
関数は次のようになります。(details: object, callback?: function) => {...}
-
詳細
オブジェクト
-
primaryPattern
文字列
プライマリ URL のパターン。パターンの形式について詳しくは、コンテンツ設定パターンをご覧ください。
-
resourceIdentifier
コンテンツ タイプのリソース ID。
-
スコープ
範囲(省略可)
設定を行う場所(デフォルト: 標準)。
-
secondaryPattern
string(省略可)
セカンダリ URL のパターン。デフォルトではすべての URL に一致します。パターンの形式について詳しくは、コンテンツ設定のパターンをご覧ください。
-
設定
任意
このルールによって適用される設定。設定可能な値については、個々の ContentSetting オブジェクトの説明をご覧ください。
-
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
-
戻り値
Promise<void>
Chrome 96 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
-
CookiesContentSetting
Enum
"block"
FullscreenContentSetting
値
ImagesContentSetting
Enum
"block"
JavascriptContentSetting
Enum
"block"
LocationContentSetting
Enum
"block"
MicrophoneContentSetting
Enum
"block"
MouselockContentSetting
値
MultipleAutomaticDownloadsContentSetting
Enum
"block"
NotificationsContentSetting
Enum
"block"
PluginsContentSetting
値
"block"
PopupsContentSetting
Enum
"block"
PpapiBrokerContentSetting
値
"block"
ResourceIdentifier
リソース ID を使用するコンテンツ タイプは contentSettings.plugins
のみです。詳細については、リソース ID をご覧ください。
プロパティ
-
description
string(省略可)
人が読める形式のリソースの説明。
-
id
文字列
指定されたコンテンツ タイプのリソース ID。
Scope
ContentSetting のスコープ。いずれか
regular
: 通常のプロファイルの設定(他の場所でオーバーライドされなければシークレット プロファイルに継承される)
incognito\_session\_only
: シークレット プロファイルの設定。シークレット セッション中にのみ設定でき、シークレット セッションが終了すると削除されます(通常の設定をオーバーライドします)。
Enum
プロパティ
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 は使用されません。
注: 両方のパターンが '' の場合、「allow」の設定は無効になります。
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 は使用されません。
注: 両方のパターンが '' の場合、「allow」の設定は無効になります。
mouselock
非推奨。効果がなくなりました。すべてのサイトに対して、マウスロックの権限が自動的に付与されます。値は常に allow
です。
notifications
サイトにデスクトップ通知の表示を許可するかどうかを指定します。次のいずれか
allow
: サイトにデスクトップ通知の表示を許可する
block
: サイトにデスクトップ通知の表示を許可しない
ask
: サイトがデスクトップ通知を表示しようとしたときに確認します。
デフォルトは ask
です。プライマリ URL は、通知を表示するドキュメントの URL です。サブ URL は使用されません。
plugins
非推奨。Flash のサポートは Chrome 88 で終了するため、この権限は機能しなくなります。値は常に block
です。set()
と clear()
の呼び出しは無視されます。
popups
サイトにポップアップの表示を許可するかどうかを指定します。次のいずれか
allow
: サイトにポップアップの表示を許可する
block
: サイトにポップアップの表示を許可しない
デフォルトは block
です。プライマリ URL は、最上位フレームの URL です。サブ URL は使用されません。
unsandboxedPlugins
非推奨。以前は、サンドボックスなしでプラグインを実行することをサイトに許可するかどうかを指定していましたが、Chrome 88 で Flash ブローカー プロセスが削除されると、この権限は機能しなくなります。値は常に block
です。set()
と clear()
の呼び出しは無視されます。