mirror of
https://github.com/mdn/webextensions-examples.git
synced 2026-04-19 15:54:00 +02:00
Rob Wu
71 lines
3.2 KiB
Markdown
71 lines
3.2 KiB
Markdown
# dnr-redirect-url
|
|
|
|
Demonstrates multiple ways to redirect requests using the declarativeNetRequest
|
|
API through the `declarative_net_request` manifest key. Demonstrates aspects of
|
|
Manifest Version 3 (MV3): `action`, `host_permissions`, and
|
|
`web_accessible_resources`.
|
|
|
|
## What it does
|
|
|
|
This extension redirects requests from the example.com domain to other
|
|
destinations:
|
|
|
|
- example.com/ to `redirectTarget.html` packaged with the extension.
|
|
- example.com/ew to extensionworkshop.com
|
|
- https://www.example.com/[anything] to the same URL but the domain changed to
|
|
example.com and `?redirected_from_www=1` appended to the URL.
|
|
- example.com URLs matching regular expression `^https?://([^?]+)$` to the same
|
|
URL but with the scheme set to `https:` (if it was `http:` before), and with
|
|
`?redirected_by_regex` appended.
|
|
|
|
Redirecting requires host permissions for the pre-redirect URLs. In Firefox
|
|
(and Safari), Manifest V3 extensions do not have access to these by default.
|
|
The permission to these can be granted from the extension action popup.
|
|
|
|
# What it shows
|
|
|
|
This extension shows how to:
|
|
|
|
- use the declarativeNetRequest API through the `declarative_net_request`
|
|
manifest key, along with the "declarativeNetRequestWithHostAccess"
|
|
permission. This permission does not trigger a permission warning. (Compared
|
|
to the "declarativeNetRequest" permission, which has the same effect but
|
|
displays the "Block content on any page" permission warning.)
|
|
- use the `action` API to offer a UI surface with which the user can interact.
|
|
- use the `permissions.contains` API to check whether an extension is granted
|
|
host permissions.
|
|
- use the `permissions.request` API to request host permissions as needed.
|
|
- redirect requests to another website.
|
|
- redirect requests to a page packaged in the extension and listed in
|
|
`web_accessible_resources`.
|
|
- redirect requests and transform the URL with the `transform` and
|
|
`queryTransform` options.
|
|
- redirect a URL matching a regular expression in `regexFilter` to a
|
|
destination composed from `regexSubstitution` and the matched URL.
|
|
- use "priority" to establish a guaranteed order of precedence between rules.
|
|
This results in a predictable redirect outcome when there are multiple
|
|
matching rule conditions for a given request.
|
|
|
|
## Comparison with Manifest Version 2
|
|
|
|
While this example uses `"manifest_version": 3`, the functionality is not
|
|
specific to Manifest Version 3.
|
|
|
|
To create a MV2 version of the extension, modify `manifest.json` as follows:
|
|
|
|
- Set `manifest_version` to 2.
|
|
- Rename `host_permissions` to `optional_permissions`.
|
|
- Rename `action` to `browser_action`.
|
|
- Set `web_accessible_resources` to `["redirectTarget.html"]`
|
|
|
|
As an alternative to renaming `host_permissions` to `optional_permissions`,
|
|
add the match patterns in the `host_permissions` array to the
|
|
`permissions` key of the MV2 manifest. Then the user does not need to opt in to
|
|
the host permission, and the extension works immediately after installation.
|
|
|
|
# Index of DNR examples
|
|
|
|
- [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) (this example)
|