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

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

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

拡張機能がポリシーによってインストールされている場合は、これらの変更を行う必要はありません。ポリシーでインストールされた拡張機能の場合、Manifest V3 でも webRequestBlocking 権限は引き続き使用できます。

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

はじめに

Manifest V2 では、ウェブ リクエストをブロックすると、拡張機能のパフォーマンスと、拡張機能が動作するページのパフォーマンスの両方が大幅に低下する可能性があります。webRequest 名前空間は、9 つの潜在的にブロックされるイベントをサポートしています。各イベントは、無制限の数のイベント ハンドラを受け取ります。さらに、各ウェブページは複数の拡張機能によってブロックされる可能性があり、そのために必要な権限はプライバシーを侵害するものです。マニフェスト 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 イベントを使用してウェブ リクエストをブロックすることでした。

chrome.webRequest.onBeforeRequest.addListener((e) => {
    return { cancel: true };
}, { urls: ["https://www.example.com/*"] }, ["blocking"]);

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

[
  {
    "id" : 1,
    "priority": 1,
    "action" : { "type" : "block" },
    "condition" : {
      "urlFilter" : "||example.com",
      "resourceTypes" : ["main_frame"]
    }
  }
]

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

この機能を試す場合は、以下のコードをサンプル リポジトリで入手できます。

  "permissions": [
    "webRequestBlocking",
    "https://*.example.com/*"
  ]

  "permissions": [
    "declarativeNetRequest",
  ]

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

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

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" フィールドが含まれています。

[
  {
    "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" 権限も必要です。

この機能を試す場合は、以下のコードをサンプル リポジトリで入手できます。

  "permissions": [
    "webRequestBlocking",
    "https://developer.chrome.com/docs/extensions/*",
    "https://developer.chrome.com/docs/extensions/reference"
  ]

  "permissions": [
    "declarativeNetRequestWithHostAccess"
  ],
  "host_permissions": [
    "https://developer.chrome.com/*"
  ]

Cookie をブロックする

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

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" 配列のみが含まれています。前の例と同じ値をサポートします。

この機能を試す場合は、以下のコードをサンプル リポジトリで入手できます。

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

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

  "permissions": [
    "webRequest",
    "webRequestBlocking",
    "https://*/*",
    "http://*/*"
  ],

  "permissions": [
    "declarativeNetRequest",
  ],
  "host_permissions": [
    ""
  ]