chrome.contentSettings

説明

chrome.contentSettings API を使用して、ウェブサイトが Cookie、JavaScript、プラグインなどの機能を使用できるかどうかを制御する設定を変更します。大まかに言うと、コンテンツ設定では、Chrome の動作をグローバルではなくサイト単位でカスタマイズできます。

権限

contentSettings

API を使用するには、拡張機能のマニフェストで "contentSettings" 権限を宣言する必要があります。次に例を示します。

{
  "name": "My extension",
  ...
  "permissions": [
    "contentSettings"
  ],
  ...
}

コンセプトと使用方法

コンテンツの設定パターン

各コンテンツ設定が影響を及ぼすウェブサイトをパターンを使って指定できます。たとえば、https://*.youtube.com/* は youtube.com とそのすべてのサブドメインを指定します。コンテンツ設定パターンの構文は、マッチパターンの構文と同じですが、いくつかの違いがあります。

  • httphttpsftp の URL の場合、パスはワイルドカード(/*)にする必要があります。file URL の場合、パスは完全に指定する必要があります。ワイルドカードは含めないでください
  • 一致パターンとは異なり、コンテンツ設定パターンではポート番号を指定できます。ポート番号を指定した場合は、そのポートを持つウェブサイトのみがパターンに一致します。ポート番号を指定しない場合、このパターンはすべてのポートと一致します。

パターンの優先順位

1 つのサイトに対して複数のコンテンツ設定ルールが適用される場合は、より具体的なパターンのルールが優先されます。

たとえば、次のパターンは優先順位で並べ替えられています。

  1. https://www.example.com/*
  2. https://*.example.com/*(example.com とすべてのサブドメインに一致)
  3. <all_urls>(すべての URL に一致)

パターンの特定度には、次の 3 種類のワイルドカードが影響します。

  • ポート内のワイルドカード(例: https://www.example.com:*/*
  • スキーム内のワイルドカード(*://www.example.com:123/* など)
  • ホスト名にワイルドカードを使用する(例: https://*.example.com:123/*

ある部分では別のパターンよりも具体的なパターンが、別の部分では具体的でないパターンの場合、各部分はホスト名、スキーム、ポートの順にチェックされます。たとえば、次のパターンは優先順位順に並んでいます。

  1. https://www.example.com:*/*ホスト名とスキームを指定します。
  2. *:/www.example.com:123/*ホスト名は指定されているものの、スキームは指定されていないため、それほど高くありません。
  3. https://*.example.com:123/* ポートとスキームは指定されているものの、ホスト名にワイルドカードが含まれているため、低くなります。

プライマリ パターンとセカンダリ パターン

適用するコンテンツ設定を決定する際に考慮される URL は、コンテンツの種類によって異なります。 たとえば、contentSettings.notifications の場合、設定はアドレスバーに表示される URL に基づきます。この URL は「メイン」URL と呼ばれます。

コンテンツ タイプによっては、追加の URL を考慮できます。たとえば、サイトが contentSettings.cookies を設定できるかどうかは、HTTP リクエストの URL(この場合はプライマリ URL)と、オムニボックスに表示される URL(「セカンダリ」URL)に基づいて決定されます。

複数のルールにプライマリ パターンとセカンダリ パターンがある場合は、より具体的なプライマリ パターンを持つルールが優先されます。同じプライマリ パターンを持つルールが複数ある場合は、より限定的なセカンダリ パターンのルールが優先されます。たとえば、次のプライマリ / セカンダリ パターンペアのリストは、優先順位で並べられています。

優先度メインのパターンサブパターン
1https://www.moose.com/*https://www.wombat.com/*
2https://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

Chrome 113 以降

列挙型

"allow"

「block」

CameraContentSetting

Chrome 46 以降

列挙型

"allow"

ClipboardContentSetting

Chrome 121 以降

列挙型

"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

    Promise

    getResourceIdentifiers 関数は次のようになります。

    (callback?: function) => {...}

    • callback

      関数(省略可)

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

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ResourceIdentifier[] 省略可

        このコンテンツ タイプのリソース識別子のリスト。このコンテンツ タイプでリソース識別子を使用しない場合は undefined

    • 戻り値

      Promise&lt;ResourceIdentifier[]&gt;

      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

Chrome 44 以降

列挙型

"allow"

"session_only"

FullscreenContentSetting

Chrome 44 以降

"allow"

ImagesContentSetting

Chrome 44 以降

列挙型

"allow"

「block」

JavascriptContentSetting

Chrome 44 以降

列挙型

"allow"

「block」

LocationContentSetting

Chrome 44 以降

列挙型

"allow"

MicrophoneContentSetting

Chrome 46 以降

列挙型

"allow"

MouselockContentSetting

Chrome 44 以降

"allow"

MultipleAutomaticDownloadsContentSetting

Chrome 44 以降

列挙型

"allow"

NotificationsContentSetting

Chrome 44 以降

列挙型

"allow"

PluginsContentSetting

Chrome 44 以降

PopupsContentSetting

Chrome 44 以降

列挙型

"allow"

「block」

PpapiBrokerContentSetting

Chrome 44 以降

「block」

ResourceIdentifier

リソース識別子を使用するコンテンツ タイプは contentSettings.plugins のみです。詳細については、リソース識別子をご覧ください。

プロパティ

  • description

    文字列(省略可)

    リソースの説明(人が読める形式)。

  • id

    文字列

    指定されたコンテンツ タイプのリソース ID。

Scope

Chrome 44 以降

ContentSetting のスコープ。regular のいずれか: 通常のプロファイルの設定(他の場所でオーバーライドされていない場合はシークレット モードのプロファイルに継承されます)、incognito\_session\_only: シークレット セッション中にのみ設定でき、シークレット セッションが終了すると削除(通常の設定をオーバーライド)するシークレット プロファイルの設定。

列挙型

プロパティ

automaticDownloads

サイトが複数のファイルを自動的にダウンロードできるようにするかどうか。次のいずれか allow: サイトに複数のファイルの自動ダウンロードを許可する block: サイトによる複数のファイルの自動ダウンロードを許可しない ask: サイトが最初のファイルの後にあるファイルを自動的にダウンロードする必要があるときに確認します。 デフォルトは ask です。プライマリ URL は、最上位フレームの URL です。セカンダリ URL は使用されません。

autoVerify

Chrome 113 以降

サイトに Private State Tokens API の使用を許可するかどうかを指定します。allow のいずれか: サイトに Private State Tokens API の使用を許可します。block: サイトによる Private State Tokens API の使用をブロックします。デフォルトは allow です。プライマリ URL は、最上位フレームの URL です。セカンダリ URL は使用されません。注: set() を呼び出す場合、プライマリ パターンは にする必要があります。

camera

Chrome 46 以降

サイトにカメラへのアクセスを許可するかどうか。次のいずれか。 allow: サイトがカメラにアクセスできるようにする block: サイトがカメラにアクセスできないようにする ask: サイトがカメラにアクセスする際に確認する デフォルトは ask です。プライマリ URL は、カメラへのアクセスをリクエストしたドキュメントの URL です。セカンダリ URL は使用されません。注: 両方のパターンが「」の場合、「許可」の設定は無効になります。

clipboard

Chrome 121 以降

サイトが 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

Chrome 46 以降

サイトにマイクへのアクセスを許可するかどうかを指定します。次のいずれか: allow: サイトにマイクへのアクセスを許可する。 block: サイトにマイクへのアクセスを許可しない ask: サイトがマイクへのアクセスを求められたときに確認する。 デフォルトは ask です。プライマリ URL は、マイクへのアクセスをリクエストしたドキュメントの URL です。セカンダリ URL は使用されません。注: 両方のパターンが「&#39;&#39;」の場合、「許可」の設定は無効です。

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() の呼び出しは無視されます。