diff --git a/files/en-us/mozilla/add-ons/webextensions/intercept_http_requests/browser_console_show_content_messages.png b/files/en-us/mozilla/add-ons/webextensions/intercept_http_requests/browser_console_show_content_messages.png deleted file mode 100644 index 4c73025d2c5a2d9..000000000000000 Binary files a/files/en-us/mozilla/add-ons/webextensions/intercept_http_requests/browser_console_show_content_messages.png and /dev/null differ diff --git a/files/en-us/mozilla/add-ons/webextensions/intercept_http_requests/browser_console_url_from_extension.png b/files/en-us/mozilla/add-ons/webextensions/intercept_http_requests/browser_console_url_from_extension.png index 66fb5a496611da4..42d7dd20af9ccfd 100644 Binary files a/files/en-us/mozilla/add-ons/webextensions/intercept_http_requests/browser_console_url_from_extension.png and b/files/en-us/mozilla/add-ons/webextensions/intercept_http_requests/browser_console_url_from_extension.png differ diff --git a/files/en-us/mozilla/add-ons/webextensions/intercept_http_requests/index.md b/files/en-us/mozilla/add-ons/webextensions/intercept_http_requests/index.md index 367848c98e2c1c7..acd32263c63e72c 100644 --- a/files/en-us/mozilla/add-ons/webextensions/intercept_http_requests/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/intercept_http_requests/index.md @@ -5,21 +5,23 @@ page-type: guide sidebar: addonsidebar --- -To intercept HTTP requests, use the {{WebExtAPIRef("webRequest")}} API. -This API enables you to add listeners for various stages of making an HTTP request. -In the listeners, you can: +Two APIs are available for intercepting HTTP requests: {{WebExtAPIRef("webRequest")}} and {{WebExtAPIRef("declarativeNetRequest")}}. -- Get access to request headers and bodies and response headers. -- Cancel and redirect requests. -- Modify request and response headers. +The {{WebExtAPIRef("webRequest")}} API intercepts requests by adding event listeners to the various stages of an HTTP request. The extension's listeners can inspect and modify requests programmatically: getting access to request and response headers and bodies, canceling requests, and redirecting them. Use `webRequest` when your extension needs to handle requests in ways that you can't determine in advance, such as when the logic depends on the content of a prior request or on dynamic extension state. -This article looks at three different uses for the `webRequest` module: +The {{WebExtAPIRef("declarativeNetRequest")}} API intercepts requests using declarative rules that specify conditions and actions. The browser evaluates these rules and handles requests directly, without notifying the extension about individual requests. This behavior makes `declarativeNetRequest` more performant and privacy-preserving than `webRequest`, as extensions don't have access to the content of individual requests. `declarativeNetRequest` also doesn't require a background page and can block or upgrade requests without [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions). Use `declarativeNetRequest` when your extension's request-handling logic can be expressed as a fixed set of rules, for example, in content blockers. -- Logging request URLs as they are made. -- Redirecting requests. -- Modifying request headers. +This article looks at examples of using both APIs. -## Logging request URLs +## Using the webRequest API + +This section includes examples that use the `webRequest` API to: + +- Log request URLs. +- Redirect requests. +- Modify request headers. + +### Logging request URLs To see how you can use `webRequest` to log requests, create a new directory called "requests". In that directory, create a file called "manifest.json" and add: @@ -27,11 +29,12 @@ In that directory, create a file called "manifest.json" and add: ```json { "description": "Demonstrating webRequests", - "manifest_version": 2, + "manifest_version": 3, "name": "webRequest-demo", "version": "1.0", - "permissions": ["webRequest", ""], + "permissions": ["webRequest"], + "host_permissions": [""], "background": { "scripts": ["background.js"] @@ -57,36 +60,27 @@ The `{urls: [""]}` [pattern](/en-US/docs/Mozilla/Add-ons/WebExtensions To test it: - [Install the extension](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/) -- Open the [Browser Console](https://firefox-source-docs.mozilla.org/devtools-user/browser_console/) (use Ctrl + Shift + J) -- Enable _Show Content Messages_ in the menu: - - ![Browser console menu: Show Content Messages](browser_console_show_content_messages.png) - +- In `about:debugging`, **This Firefox** (or **This Nightly**), click **Inspect** next to the extension. - Open some web pages. -In the Browser Console, you should see the URLs for any resources the browser requests. +In the Developer Tools console, you see the URLs for any resources the browser requests. For example, this screenshot shows the URLs from loading a Wikipedia page: -![Browser console menu: URLs from extension](browser_console_url_from_extension.png) - - +![The Developer Tools console showing logged call URLs.](browser_console_url_from_extension.png) -## Redirecting requests +### Redirecting requests Now use `webRequest` to redirect HTTP requests. First, replace "manifest.json" with this: ```json { "description": "Demonstrating webRequests", - "manifest_version": 2, + "manifest_version": 3, "name": "webRequest-demo", "version": "1.0", - "permissions": [ - "webRequest", - "webRequestBlocking", - "https://developer.mozilla.org/" - ], + "permissions": ["webRequest", "webRequestBlocking"], + "host_permissions": ["https://developer.mozilla.org/"], "background": { "scripts": ["background.js"] @@ -138,7 +132,7 @@ To test it out, open a page on MDN that contains images (for example, [the page ![Images on a page replaced with a frog image](beastify_by_redirect.png) -## Modifying request headers +### Modifying request headers Finally, use `webRequest` to modify request headers. In this example, you change the "User-Agent" header so the browser identifies itself as Opera 12.16, but only when visiting pages under "https\://useragentstring.com/". @@ -148,15 +142,12 @@ Update the "manifest.json" to include `https://useragentstring.com/` like this: ```json { "description": "Demonstrating webRequests", - "manifest_version": 2, + "manifest_version": 3, "name": "webRequest-demo", "version": "1.0", - "permissions": [ - "webRequest", - "webRequestBlocking", - "https://useragentstring.com/" - ], + "permissions": ["webRequest", "webRequestBlocking"], + "host_permissions": ["https://useragentstring.com/"], "background": { "scripts": ["background.js"] @@ -202,6 +193,157 @@ Then reload the extension, reload [useragentstring.com](https://useragentstring. ![useragentstring.com showing details of the modified user agent string](modified_request_header.png) +## Using the declarativeNetRequest API + +To illustrate the use of the `declarativeNetRequest` API, this section includes examples showing how to redirect requests and modify request headers using declarative rules. + +Unlike `webRequest`, `declarativeNetRequest` doesn't notify the extension about individual network requests, so there is no equivalent to the [logging example](#logging_request_urls). + +### Redirecting requests + +Use `declarativeNetRequest` to redirect HTTP requests. Create a directory called "requests". In that directory, create a file called "manifest.json" and add: + +```json +{ + "description": "Demonstrating declarativeNetRequest", + "manifest_version": 3, + "name": "declarativeNetRequest-demo", + "version": "1.0", + + "permissions": ["declarativeNetRequest"], + "host_permissions": ["https://developer.mozilla.org/"], + + "declarative_net_request": { + "rule_resources": [ + { + "id": "ruleset_1", + "enabled": true, + "path": "rules.json" + } + ] + } +} +``` + +The `"declarativeNetRequest"` permission enables the API. The `"host_permissions"` entry is required because the rules redirect requests. The `"declarative_net_request"` manifest key registers the ruleset file, which defines how to handle requests. + +Next, create a file called "rules.json" and add: + +```json +[ + { + "id": 1, + "priority": 1, + "action": { + "type": "redirect", + "redirect": { + "url": "https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Your_second_WebExtension/frog.jpg" + } + }, + "condition": { + "urlFilter": "||developer.mozilla.org", + "resourceTypes": ["image"] + } + }, + { + "id": 2, + "priority": 2, + "action": { "type": "allow" }, + "condition": { + "urlFilter": "frog.jpg", + "resourceTypes": ["image"] + } + } +] +``` + +This ruleset has two rules: + +- Rule 1 redirects all image requests to URLs under `https://developer.mozilla.org/` to the frog image from the [your second extension tutorial](/en-US/docs/Mozilla/Add-ons/WebExtensions/Your_second_WebExtension). +- Rule 2 uses the "allow" action with a higher priority to prevent the frog image itself from being redirected, which would otherwise cause an infinite redirect loop. + +See {{WebExtAPIRef("declarativeNetRequest.RuleCondition")}} and {{WebExtAPIRef("declarativeNetRequest.RuleAction")}} for more on conditions and actions, and [Matching precedence](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest#matching_precedence) for details on how rule priority works. + +Unlike the `webRequest` version of this example, the extension doesn't need a background script. The browser evaluates the rules directly. + +To test it out, open a page on MDN that contains images (for example, [the page listing extension user interface components](/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface)), [install the extension](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/), and then load the MDN page. You see something like this: + +![Images on a page replaced with a frog image](beastify_by_redirect.png) + +### Modifying request headers + +Use `declarativeNetRequest` to modify request headers. In this example, you change the "User-Agent" header so the browser identifies itself as Opera 12.16, but only for requests to "https\://useragentstring.com/". + +Replace "manifest.json" with this: + +```json +{ + "description": "Demonstrating declarativeNetRequest", + "manifest_version": 3, + "name": "declarativeNetRequest-demo", + "version": "1.0", + + "permissions": ["declarativeNetRequest"], + "host_permissions": ["https://useragentstring.com/"], + + "declarative_net_request": { + "rule_resources": [ + { + "id": "ruleset_1", + "enabled": true, + "path": "rules.json" + } + ] + } +} +``` + +Replace "rules.json" with this: + +```json +[ + { + "id": 1, + "priority": 1, + "action": { + "type": "modifyHeaders", + "requestHeaders": [ + { + "header": "User-Agent", + "operation": "set", + "value": "Opera/9.80 (X11; Linux i686; Ubuntu/14.10) Presto/2.12.388 Version/12.16" + } + ] + }, + "condition": { + "urlFilter": "||useragentstring.com", + "resourceTypes": ["main_frame"] + } + } +] +``` + +The rule's `condition` matches `main_frame` requests to `useragentstring.com`. The `action` uses `"modifyHeaders"` with an `"operation"` of `"set"` to replace the value of the `User-Agent` header. See {{WebExtAPIRef("declarativeNetRequest.ModifyHeaderInfo")}} for the full set of header modification options. + +Host permissions for `useragentstring.com` are required to modify headers on requests to that domain. + +To test it out, [reload the extension](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/#reloading_a_temporary_add-on), open [useragentstring.com](https://useragentstring.com/) and check that it identifies the browser as Firefox. Then reload [useragentstring.com](https://useragentstring.com/), and see that the site now identifies the browser as Opera. + +![useragentstring.com showing details of the modified user agent string](modified_request_header.png) + ## Learn more -To learn about all the things you can do with the `webRequest` API, see its [reference documentation](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/webRequest). +To learn more about these APIs, see the {{WebExtAPIRef("webRequest")}} and {{WebExtAPIRef("declarativeNetRequest")}} reference documentation. + +For `webRequest` examples, see: + +- [http-response](https://github.com/mdn/webextensions-examples/tree/main/http-response) +- [root-cert-stats](https://github.com/mdn/webextensions-examples/tree/main/root-cert-stats) +- [stored-credentials](https://github.com/mdn/webextensions-examples/tree/main/stored-credentials) +- [user-agent-rewriter](https://github.com/mdn/webextensions-examples/tree/main/user-agent-rewriter) + +For `declarativeNetRequest` examples, see: + +- [dnr-block-only](https://github.com/mdn/webextensions-examples/tree/main/dnr-block-only) +- [dnr-dynamic-with-options](https://github.com/mdn/webextensions-examples/tree/main/dnr-dynamic-with-options) +- [dnr-redirect-url](https://github.com/mdn/webextensions-examples/tree/main/dnr-redirect-url)