mirror of
https://github.com/mdn/webextensions-examples.git
synced 2026-04-16 06:18:35 +02:00
112 lines
3.8 KiB
Markdown
112 lines
3.8 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.
|
|
|
|
# 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) (this example)
|
|
- [dnr-redirect-url](https://github.com/mdn/webextensions-examples/tree/main/dnr-redirect-url)
|