mirror of
https://github.com/mdn/webextensions-examples.git
synced 2026-05-05 07:07:46 +02:00
Rob Wu
06330a69c2
These examples are designed to be cross-browser compatible. In particular, these extensions do not use `background` because there is currently no single manifest that can support both Firefox and Chrome, due to the lack of event page support in Chrome, and the lack of service worker support in Firefox. Three examples demonstrating the use of the declarativeNetRequest API: - dnr-block-only: One minimal example demonstrating the use of static DNR rules to block requests. - dnr-redirect-url: One minimal example demonstrating the use of static DNR rules to redirect requests. - dnr-dynamic-with-options: A generic example demonstrating how host permissions can be requested and free forms to input DNR rules.
106 lines
3.5 KiB
Markdown
106 lines
3.5 KiB
Markdown
# dnr-dynamic-with-options
|
|
|
|
Demonstrates a generic way to request host permissions and register
|
|
declarativeNetRequest rules to modify network requests, without any
|
|
install-time permission warnings. The `options_ui` page offers a way to request
|
|
permissions and register declarative net request (DNR) rules.
|
|
|
|
## What it does
|
|
|
|
After loading the extension, visit the extension options page:
|
|
|
|
1. Visit `about:addons`.
|
|
2. Go to the extension at "DNR Dynamic with options".
|
|
3. Click on Preferences to view its options page (options.html).
|
|
|
|
On the options page:
|
|
|
|
1. Input the list of host permissions and click on "Grant host permissions".
|
|
2. Input the list of declarativeNetRequest rules and click "Save".
|
|
3. Trigger a network request to verify that the rule matched.
|
|
|
|
### Example for options page
|
|
|
|
Host permissions:
|
|
|
|
```json
|
|
["*://example.com/"]
|
|
```
|
|
|
|
DNR rules:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"id": 1,
|
|
"priority": 1,
|
|
"condition": {
|
|
"urlFilter": "|https://example.com/",
|
|
"resourceTypes": [
|
|
"main_frame"
|
|
]
|
|
},
|
|
"action": {
|
|
"type": "block"
|
|
}
|
|
}
|
|
]
|
|
```
|
|
|
|
Manual test case: Visit https://example.com/ and verify that it is blocked.
|
|
|
|
# What it shows
|
|
|
|
How to create an extension with no install-time permission warnings and
|
|
request (host) permissions as needed:
|
|
|
|
- declares the "declarativeNetRequestWithHostAccess" permission, which
|
|
unlocks the declarativeNetRequest API without install-time warning.
|
|
In contrast, the "declarativeNetRequest" permission has the same effect,
|
|
but has the "Block content on any page" permission warning.
|
|
- declares the most permissive match pattern in `optional_host_permissions`.
|
|
- calls `permissions.request` to request host permissions.
|
|
- uses `permissions.getAll` and `permissions.remove` to reset permissions.
|
|
|
|
How to retrieve and dynamically register declarativeNetRequest rules, using:
|
|
|
|
- `declarativeNetRequest.getDynamicRules` and
|
|
`declarativeNetRequest.updateDynamicRules` to manage DNR rules that persist
|
|
across extension restarts. These rules also persist across browser restarts,
|
|
unless the extension is loaded temporarily or unloaded.
|
|
- `declarativeNetRequest.getSessionRules` and
|
|
`declarativeNetRequest.updateSessionRules` to manage DNR rules that are
|
|
session-scoped, that is, cleared when an extension unloads or the browser
|
|
quits.
|
|
|
|
How these registered DNR rules can modify network requests without requiring an
|
|
active extension script in the background, in a cross-browser way (at least in
|
|
Firefox, Chrome, and Safari).
|
|
|
|
## Note on `optional_host_permissions` and `optional_permissions`
|
|
|
|
Firefox does not support `optional_host_permissions` permissions, it
|
|
supports host permissions in `optional_permissions`
|
|
(https://bugzilla.mozilla.org/show_bug.cgi?id=1766026).
|
|
|
|
Chrome recognizes `optional_host_permissions` but does not support host
|
|
permissions in `optional_permissions`.
|
|
|
|
To support both, include `optional_host_permissions` and `optional_permissions`
|
|
in your manifest.json.
|
|
|
|
## 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.
|
|
- Use `optional_permissions` instead of `optional_host_permissions` to list
|
|
optional host permissions.
|
|
- In this example, `optional_permissions` is present with
|
|
the same value as `optional_host_permissions` for the reasons explained in
|
|
the previous section. The latter is MV3-only and can be removed from a MV2
|
|
manifest.
|