ブロックしているウェブ リクエスト リスナーを置き換える

Manifest V3 でのネットワーク リクエストの変更

Manifest V3 では、拡張機能がネットワーク リクエストの変更を処理する方法が変更されています。ネットワーク リクエストをインターセプトして chrome.webRequest で実行時に変更するのではなく、拡張機能で、特定の条件が満たされたときに実行するアクションを記述するルールを指定します。これを行うには、Declarative Net Request API を使用します。

Web Request API と Declarative Net Request API は大きく異なります。1 つの関数呼び出しを別の関数呼び出しに置き換えるのではなく、ユースケースに基づいてコードを書き直す必要があります。このセクションでは、そのプロセスについて説明します。

Manifest V2 では、ウェブリクエストをブロックすると、拡張機能のパフォーマンスと、拡張機能が動作するページのパフォーマンスの両方が大幅に低下する可能性があります。webRequest 名前空間は、ブロックが発生する可能性のある 9 つのイベントをサポートしています。これらのイベントはそれぞれ、無制限の数のイベント ハンドラを受け取ります。さらに悪いことに、各ウェブページは複数の拡張機能によってブロックされる可能性があり、これに必要な権限が侵襲的です。マニフェスト V3 では、コールバックを宣言型ルールに置き換えることで、この問題を防ぎます。

これは、拡張機能サービス ワーカーに含まれないコードに必要な変更について説明する 3 つのセクションの 2 番目です。Manifest V2 で使用されるブロック ウェブリクエストを、Manifest V3 で使用される宣言型ネットリクエストに変換する方法について説明します。他の 2 つのセクションでは、Manifest V3 への移行に必要なコードの更新とセキュリティの強化について説明します。

許可を更新

manifest.json の "permissions" フィールドを次のように変更します。

  • ネットワーク リクエストのモニタリングが不要になった場合は、"webRequest" 権限を削除します。
  • マッチパターンを "permissions" から "host_permissions" に移動しました。

ユースケースに応じて、他の権限を追加する必要があります。これらの権限は、サポートするユースケースとともに説明されています。

宣言型ネット リクエスト ルールを作成する

宣言型ネット リクエスト ルールを作成するには、manifest.json に "declarative_net_request" オブジェクトを追加する必要があります。"declarative_net_request" ブロックには、ルールファイルを指す "rule_resource" オブジェクトの配列が含まれています。ルールファイルには、操作を指定するオブジェクトの配列と、それらの操作を呼び出す条件が含まれます。

一般的なユースケース

以降のセクションでは、宣言型ネット リクエストの一般的なユースケースについて説明します。以下の手順は概要のみを説明しています。ここに記載されているすべての情報の詳細については、API リファレンスの chrome.declarativeNetRequest をご覧ください。

単一の URL をブロックする

Manifest V2 の一般的なユースケースは、バックグラウンド スクリプトで onBeforeRequest イベントを使用してウェブリクエストをブロックすることでした。

Manifest V2 のバックグラウンド スクリプト
chrome.webRequest.onBeforeRequest.addListener((e) => {
    return { cancel: true };
}, { urls: ["https://www.example.com/*"] }, ["blocking"]);

Manifest V3 の場合は、"block" アクション タイプを使用して新しい declarativeNetRequest ルールを作成します。サンプルルールの "condition" オブジェクトに注目してください。"urlFilter" は、webRequest リスナーに渡される urls オプションに代わるものです。"resourceTypes" 配列は、ブロックするリソースのカテゴリを指定します。この例ではメインの HTML ページのみをブロックしていますが、フォントのみなど、任意の要素をブロックすることもできます。

Manifest V3 ルールファイル
[
  {
    "id" : 1,
    "priority": 1,
    "action" : { "type" : "block" },
    "condition" : {
      "urlFilter" : "||example.com",
      "resourceTypes" : ["main_frame"]
    }
  }
]

これを実現するには、拡張機能の権限を更新する必要があります。manifest.json で、"webRequestBlocking" 権限を "declarativeNetRequest" 権限に置き換えます。コンテンツのブロックにはホスト権限が必要ないため、"permissions" フィールドから URL が削除されます。上記のように、ルールファイルには、宣言型ネットリクエストが適用されるホストが指定されています。

試してみたい場合は、サンプル リポジトリで以下のコードをご利用ください。

Manifest V2
  "permissions": [
    "webRequestBlocking",
    "https://*.example.com/*"
  ]
Manifest V3
  "permissions": [
    "declarativeNetRequest",
  ]

複数の URL をリダイレクトする

Manifest V2 のもう 1 つの一般的なユースケースは、BeforeRequest イベントを使用してウェブ リクエストをリダイレクトすることでした。

Manifest V2 のバックグラウンド スクリプト
chrome.webRequest.onBeforeRequest.addListener((e) => {
    console.log(e);
    return { redirectUrl: "https://developer.chrome.com/docs/extensions/mv3/intro/" };
  }, { 
    urls: [
      "https://developer.chrome.com/docs/extensions/mv2/"
    ]
  }, 
  ["blocking"]
);

Manifest V3 の場合は、"redirect" アクション タイプを使用します。前述のように、"urlFilter" は webRequest リスナーに渡される url オプションに代わるものです。この例では、ルールファイルの "action" オブジェクトに、フィルタされる URL ではなく、返される URL を含む "redirect" フィールドが含まれています。

Manifest V3 ルールファイル
[
  {
    "id" : 1,
    "priority": 1,
    "action": {
      "type": "redirect",
      "redirect": { "url": "https://developer.chrome.com/docs/extensions/mv3/intro/" }
    },
    "condition": {
      "urlFilter": "https://developer.chrome.com/docs/extensions/mv2/",
      "resourceTypes": ["main_frame"]
    }
  }

このシナリオでは、拡張機能の権限の変更も必要です。前と同様に、"webRequestBlocking" 権限を "declarativeNetRequest" 権限に置き換えます。URL が再び manifest.json からルールファイルに移動します。リダイレクトには、ホスト権限に加えて "declarativeNetRequestWithHostAccess" 権限も必要です。

試してみたい場合は、サンプル リポジトリで以下のコードをご利用ください。

Manifest V2
  "permissions": [
    "webRequestBlocking",
    "https://developer.chrome.com/docs/extensions/*",
    "https://developer.chrome.com/docs/extensions/reference"
  ]
Manifest V3
  "permissions": [
    "declarativeNetRequestWithHostAccess"
  ],
  "host_permissions": [
    "https://developer.chrome.com/*"
  ]

Cookie をブロックする

Manifest V2 で Cookie をブロックするには、ウェブ リクエスト ヘッダーを送信前にインターセプトし、特定のヘッダーを削除する必要があります。

Manifest V2 バックグラウンド スクリプト
chrome.webRequest.onBeforeSendHeaders.addListener(
  function(details) {
    removeHeader(details.requestHeaders, 'cookie');
    return {requestHeaders: details.requestHeaders};
  },
  // filters
  {urls: ['https://*/*', 'http://*/*']},
  // extraInfoSpec
  ['blocking', 'requestHeaders', 'extraHeaders']);

Manifest V3 でも、ルールファイル内のルールを使用してこの処理を行います。今回はアクション タイプは "modifyHeaders" です。このファイルは、変更するヘッダーとその変更方法を指定する "requestHeaders" オブジェクトの配列を受け取ります。"condition" オブジェクトには "resourceTypes" 配列のみが含まれています。前の例と同じ値をサポートします。

試してみたい場合は、サンプル リポジトリで以下のコードをご利用ください。

Manifest V3 manifest.json
[
  {
    "id": 1,
    "priority": 1,
    "action": {
      "type": "modifyHeaders",
      "requestHeaders": [
        { "header": "cookie", "operation": "remove" }
      ]
    },
    "condition": {
      "urlFilter": "|*?no-cookies=1",
      "resourceTypes": ["main_frame"]
    }
  }
]

このシナリオでは、拡張機能の権限も変更する必要があります。以前と同様に、"webRequestBlocking" 権限を "declarativeNetRequest" 権限に置き換えます。

Manifest V2
  "permissions": [
    "webRequest",
    "webRequestBlocking",
    "https://*/*",
    "http://*/*"
  ],
Manifest V3
  "permissions": [
    "declarativeNetRequest",
  ],
  "host_permissions": [
    ""
  ]