mirror of
https://github.com/mdn/webextensions-examples.git
synced 2026-04-16 06:18:35 +02:00
Add declarativeNetRequest (DNR) + MV3 examples (#526)
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.
This commit is contained in:
Rob Wu
GitHub
@@ -8,12 +8,15 @@
|
||||
"es6": true,
|
||||
"webextensions": true
|
||||
},
|
||||
"globals": {
|
||||
"globalThis": false
|
||||
},
|
||||
"extends": [
|
||||
"eslint:recommended"
|
||||
],
|
||||
"rules": {
|
||||
"no-console": 0,
|
||||
"no-unused-vars": ["warn", { "vars": "all", "args": "all" } ],
|
||||
"no-unused-vars": ["warn", { "vars": "all", "args": "after-used" } ],
|
||||
"no-undef": ["warn"],
|
||||
"no-proto": ["error"],
|
||||
"prefer-arrow-callback": ["warn"],
|
||||
|
||||
42
dnr-block-only/README.md
Normal file
42
dnr-block-only/README.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# dnr-block-only
|
||||
|
||||
Demonstrates how to block network requests without host permissions using the
|
||||
declarativeNetRequest API with the `declarative_net_request` manifest key.
|
||||
|
||||
## What it does
|
||||
|
||||
This extension blocks:
|
||||
|
||||
- network requests to URLs containing "blocksub" (except for top-level
|
||||
navigations).
|
||||
- top-level navigation to URLs containing "blocktop".
|
||||
- all requests containing "blockall".
|
||||
|
||||
Load `testpage.html` to see the extension in action.
|
||||
This demo page does not need to be packaged with the extension.
|
||||
|
||||
# What it shows
|
||||
|
||||
This example shows how to:
|
||||
|
||||
- use the declarativeNetRequest API through the `declarative_net_request`
|
||||
manifest key.
|
||||
- use the "resourceTypes" and "excludedResourceTypes" conditions of a
|
||||
declarativeNetRequest rule.
|
||||
- block network requests without host permissions using the
|
||||
"declarativeNetRequest" permission, which triggers the "Block content on any
|
||||
page" permission warning at install time.
|
||||
|
||||
This example is the only cross-browser way to block network requests (at least
|
||||
in Firefox, Chrome, and Safari). The webRequest API is an alternative way to
|
||||
implement this functionality, but is only available in Firefox (MV2 and MV3)
|
||||
and in Chrome (MV2 only). Safari does not support the webRequest API.
|
||||
|
||||
## 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.
|
||||
16
dnr-block-only/manifest.json
Normal file
16
dnr-block-only/manifest.json
Normal file
@@ -0,0 +1,16 @@
|
||||
{
|
||||
"manifest_version": 3,
|
||||
"name": "Block only, without host_permissions",
|
||||
"description": "Blocks requests to 'blocksub', 'blocktop', and 'blockall'. Uses the 'declarativeNetRequest' permission, meaning that host_permissions in manifest.json are not needed.",
|
||||
"version": "0.1",
|
||||
"permissions": [
|
||||
"declarativeNetRequest"
|
||||
],
|
||||
"declarative_net_request": {
|
||||
"rule_resources": [{
|
||||
"id": "ruleset",
|
||||
"enabled": true,
|
||||
"path": "rules.json"
|
||||
}]
|
||||
}
|
||||
}
|
||||
31
dnr-block-only/rules.json
Normal file
31
dnr-block-only/rules.json
Normal file
@@ -0,0 +1,31 @@
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"condition": {
|
||||
"urlFilter": "blocksub"
|
||||
},
|
||||
"action": {
|
||||
"type": "block"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"condition": {
|
||||
"urlFilter": "blocktop",
|
||||
"resourceTypes": ["main_frame"]
|
||||
},
|
||||
"action": {
|
||||
"type": "block"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"condition": {
|
||||
"urlFilter": "blockall",
|
||||
"excludedResourceTypes": []
|
||||
},
|
||||
"action": {
|
||||
"type": "block"
|
||||
}
|
||||
}
|
||||
]
|
||||
97
dnr-block-only/testpage.html
Normal file
97
dnr-block-only/testpage.html
Normal file
@@ -0,0 +1,97 @@
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<style>
|
||||
div {
|
||||
margin: 2px 0;
|
||||
border: 1px solid black;
|
||||
}
|
||||
img {
|
||||
display: block;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<h2 id="blocksub">Block requests containing 'blocksub' (except main_frame)</h2>
|
||||
Given the following rule:
|
||||
<pre>
|
||||
{
|
||||
"id": 1,
|
||||
"condition": {
|
||||
"urlFilter": "blocksub"
|
||||
},
|
||||
"action": {
|
||||
"type": "block"
|
||||
}
|
||||
},
|
||||
</pre>
|
||||
<div>
|
||||
rule 1 will block this image (containing 'blocksub'):
|
||||
<img src="https://developer.mozilla.org/favicon.ico?blocksub">
|
||||
</div>
|
||||
<div>
|
||||
rule 1 will not block this image (does not contain 'blocksub'):
|
||||
<img src="https://developer.mozilla.org/favicon.ico">
|
||||
</div>
|
||||
<div>
|
||||
rule 1 will not block top-level navigations to
|
||||
<a href="https://developer.mozilla.org/favicon.ico?blocksub">https://developer.mozilla.org/favicon.ico?blocksub</a>
|
||||
because top-level navigation ("main_frame") requests are not matched
|
||||
when "resourceTypes" and "excludedResourceTypes" are not specified.
|
||||
</div>
|
||||
|
||||
<h2 id="blocktop">Block main_frame requests containing 'blocktop'</h2>
|
||||
Given the following rule:
|
||||
<pre>
|
||||
{
|
||||
"id": 2,
|
||||
"condition": {
|
||||
"urlFilter": "blocktop",
|
||||
"resourceTypes": ["main_frame"]
|
||||
},
|
||||
"action": {
|
||||
"type": "block"
|
||||
}
|
||||
},
|
||||
</pre>
|
||||
<div>
|
||||
rule 2 will block top-level navigation to
|
||||
<a href="https://developer.mozilla.org/favicon.ico?blocktop">https://developer.mozilla.org/favicon.ico?blocktop</a>
|
||||
because the "resourceTypes" array contains "main_frame".
|
||||
</div>
|
||||
<div>
|
||||
rule 2 will not block this image (containing 'blocktop')
|
||||
<img src="https://developer.mozilla.org/favicon.ico?blocktop">
|
||||
because "image" is not in the "resourceTypes" array.
|
||||
</div>
|
||||
|
||||
<h2 id="blockall">Block all requests containing 'blockall'</h2>
|
||||
Given the following rule:
|
||||
<pre>
|
||||
{
|
||||
"id": 3,
|
||||
"condition": {
|
||||
"urlFilter": "blockall",
|
||||
"excludedResourceTypes": []
|
||||
},
|
||||
"action": {
|
||||
"type": "block"
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
<div>
|
||||
rule 3 will block this image (containing 'blockall'):
|
||||
<img src="https://developer.mozilla.org/favicon.ico?blockall">
|
||||
</div>
|
||||
<div>
|
||||
rule 3 will block top-level navigation to
|
||||
<a href="https://developer.mozilla.org/favicon.ico?blockall">https://developer.mozilla.org/favicon.ico?blockall</a>
|
||||
because "excludedResourceTypes" is set to an empty array.
|
||||
<br>
|
||||
Note: not blocked in Chrome due to <a href="https://crbug.com/1432871">https://crbug.com/1432871</a>.
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
105
dnr-dynamic-with-options/README.md
Normal file
105
dnr-dynamic-with-options/README.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# 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.
|
||||
12
dnr-dynamic-with-options/manifest.json
Normal file
12
dnr-dynamic-with-options/manifest.json
Normal file
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"manifest_version": 3,
|
||||
"name": "DNR dynamic with options",
|
||||
"description": "Modify requests according to the rules specified by the user in the options page.",
|
||||
"version": "0.1",
|
||||
"permissions": ["declarativeNetRequestWithHostAccess"],
|
||||
"optional_host_permissions": ["*://*/"],
|
||||
"optional_permissions": ["*://*/"],
|
||||
"options_ui": {
|
||||
"page": "options.html"
|
||||
}
|
||||
}
|
||||
8
dnr-dynamic-with-options/options.css
Normal file
8
dnr-dynamic-with-options/options.css
Normal file
@@ -0,0 +1,8 @@
|
||||
.input-and-buttons legend {
|
||||
font-weight: bold;
|
||||
}
|
||||
.input-and-buttons textarea {
|
||||
display: block;
|
||||
width: 100%;
|
||||
min-height: 7em;
|
||||
}
|
||||
36
dnr-dynamic-with-options/options.html
Normal file
36
dnr-dynamic-with-options/options.html
Normal file
@@ -0,0 +1,36 @@
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width"> <!-- mobile-friendly -->
|
||||
<link rel="stylesheet" type="text/css" href="options.css">
|
||||
</head>
|
||||
<body>
|
||||
<fieldset class="input-and-buttons">
|
||||
<legend>Allowed host permissions</legend>
|
||||
Specify the JSON-formatted list of allowed host permissions (documentation: <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/permissions/Permissions#origins">origins</a>).
|
||||
<textarea id="input-host-permissions"></textarea>
|
||||
<button id="grant-host-permissions">Grant host permissions</button>
|
||||
<button id="reset-host-permissions">Reset host permissions</button>
|
||||
<output id="status-host-permissions"></output>
|
||||
</fieldset>
|
||||
|
||||
<fieldset class="input-and-buttons">
|
||||
<legend>Dynamic declarativeNetRequest rules (persists across restarts)</legend>
|
||||
Specify the JSON-formatted list of dynamic DNR rules (documentation: <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest#rules">declarativeNetRequest rules</a>).
|
||||
<textarea id="input-dynamic-rules"></textarea>
|
||||
<button id="save-dynamic-rules">Save</button>
|
||||
<output id="status-dynamic-rules"></output>
|
||||
</fieldset>
|
||||
|
||||
<fieldset class="input-and-buttons">
|
||||
<legend>Session-scoped declarativeNetRequest rules (cleared on extension unload/reload)</legend>
|
||||
Specify the JSON-formatted list of session DNR rules (documentation: <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest#rules">declarativeNetRequest rules</a>).
|
||||
<textarea id="input-session-rules"></textarea>
|
||||
<button id="save-session-rules">Save</button>
|
||||
<output id="status-session-rules"></output>
|
||||
</fieldset>
|
||||
|
||||
<script src="options.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
90
dnr-dynamic-with-options/options.js
Normal file
90
dnr-dynamic-with-options/options.js
Normal file
@@ -0,0 +1,90 @@
|
||||
"use strict";
|
||||
|
||||
if (typeof browser == "undefined") {
|
||||
// `browser` is not defined in Chrome, but Manifest V3 extensions in Chrome
|
||||
// also support promises in the `chrome` namespace, like Firefox. To easily
|
||||
// test the example without modifications, polyfill "browser" to "chrome".
|
||||
globalThis.browser = chrome;
|
||||
}
|
||||
|
||||
function initializePrefHandlerForHostPermissions() {
|
||||
const textarea = document.getElementById("input-host-permissions");
|
||||
const statusOutput = document.getElementById("status-host-permissions");
|
||||
document.getElementById("grant-host-permissions").onclick = async () => {
|
||||
try {
|
||||
let origins = JSON.parse(textarea.value);
|
||||
statusOutput.value = "Requesting permissions";
|
||||
let ok = await browser.permissions.request({ origins });
|
||||
statusOutput.value = ok ? "Permissions granted" : "Permissions denied";
|
||||
} catch (e) {
|
||||
statusOutput.value = `Failed to grant permissions: ${e}`;
|
||||
}
|
||||
};
|
||||
document.getElementById("reset-host-permissions").onclick = async () => {
|
||||
let permissions = await browser.permissions.getAll();
|
||||
await browser.permissions.remove({ origins: permissions.origins });
|
||||
statusOutput.value = `Removed: ${JSON.stringify(permissions.origins)}`;
|
||||
};
|
||||
|
||||
browser.permissions.getAll().then(
|
||||
permissions => {
|
||||
textarea.value = JSON.stringify(permissions.origins, null, 2);
|
||||
}
|
||||
);
|
||||
}
|
||||
|
||||
function serializeRules(rules) {
|
||||
// The getDynamicRules and getSessionRules APIs returns the rules, including
|
||||
// optional keys. For readability, we strip all optional keys.
|
||||
// JSON.stringify will drop keys if the replacer function returns undefined.
|
||||
const replacer = (key, value) => value === null ? undefined : value;
|
||||
return JSON.stringify(rules, replacer, 2);
|
||||
}
|
||||
|
||||
function initializePrefHandlerForDynamicDNR() {
|
||||
const textarea = document.getElementById("input-dynamic-rules");
|
||||
const statusOutput = document.getElementById("status-dynamic-rules");
|
||||
document.getElementById("save-dynamic-rules").onclick = async () => {
|
||||
try {
|
||||
let newRules = JSON.parse(textarea.value);
|
||||
let oldRules = await browser.declarativeNetRequest.getDynamicRules();
|
||||
await browser.declarativeNetRequest.updateDynamicRules({
|
||||
removeRuleIds: oldRules.map(rule => rule.id),
|
||||
addRules: newRules,
|
||||
});
|
||||
statusOutput.value = `Saved ${newRules.length} rules`;
|
||||
} catch (e) {
|
||||
statusOutput.value = `Failed to save rules: ${e}`;
|
||||
}
|
||||
};
|
||||
|
||||
browser.declarativeNetRequest.getDynamicRules().then(rules => {
|
||||
textarea.value = serializeRules(rules);
|
||||
});
|
||||
}
|
||||
|
||||
function initializePrefHandlerForSessionDNR() {
|
||||
const textarea = document.getElementById("input-session-rules");
|
||||
const statusOutput = document.getElementById("status-session-rules");
|
||||
document.getElementById("save-session-rules").onclick = async () => {
|
||||
try {
|
||||
let newRules = JSON.parse(textarea.value);
|
||||
let oldRules = await browser.declarativeNetRequest.getSessionRules();
|
||||
await browser.declarativeNetRequest.updateSessionRules({
|
||||
removeRuleIds: oldRules.map(rule => rule.id),
|
||||
addRules: newRules,
|
||||
});
|
||||
statusOutput.value = `Saved ${newRules.length} rules`;
|
||||
} catch (e) {
|
||||
statusOutput.value = `Failed to save rules: ${e}`;
|
||||
}
|
||||
};
|
||||
|
||||
browser.declarativeNetRequest.getSessionRules().then(rules => {
|
||||
textarea.value = serializeRules(rules);
|
||||
});
|
||||
}
|
||||
|
||||
initializePrefHandlerForHostPermissions();
|
||||
initializePrefHandlerForDynamicDNR();
|
||||
initializePrefHandlerForSessionDNR();
|
||||
64
dnr-redirect-url/README.md
Normal file
64
dnr-redirect-url/README.md
Normal file
@@ -0,0 +1,64 @@
|
||||
# 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.
|
||||
24
dnr-redirect-url/manifest.json
Normal file
24
dnr-redirect-url/manifest.json
Normal file
@@ -0,0 +1,24 @@
|
||||
{
|
||||
"manifest_version": 3,
|
||||
"name": "Redirect example.com requests",
|
||||
"description": "Redirects example.com requests. Redirects always require host_permissions.",
|
||||
"version": "0.1",
|
||||
"permissions": ["declarativeNetRequestWithHostAccess"],
|
||||
"host_permissions": ["*://*.example.com/"],
|
||||
"declarative_net_request": {
|
||||
"rule_resources": [
|
||||
{
|
||||
"id": "ruleset",
|
||||
"enabled": true,
|
||||
"path": "redirect-rules.json"
|
||||
}
|
||||
]
|
||||
},
|
||||
"action": {
|
||||
"default_popup": "popup.html"
|
||||
},
|
||||
"web_accessible_resources": [{
|
||||
"resources": ["redirectTarget.html"],
|
||||
"matches": ["*://example.com/*"]
|
||||
}]
|
||||
}
|
||||
29
dnr-redirect-url/popup.html
Normal file
29
dnr-redirect-url/popup.html
Normal file
@@ -0,0 +1,29 @@
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width"> <!-- mobile-friendly -->
|
||||
<base target="_blank"> <!-- Open links in new tab by default -->
|
||||
</head>
|
||||
<body>
|
||||
<h2>Host permission requirement</h2>
|
||||
To redirect requests, the extension needs host permissions.<br>
|
||||
While "Manage Extensions" (<code>about:addons</code>) offers a built-in UI to grant or revoke permissions, this extension uses the <code>permissions</code> API to build the request into the UI:
|
||||
<p>
|
||||
<label>
|
||||
<input type="checkbox" id="checkbox_host_permission">
|
||||
Allow access to example.com
|
||||
</label>
|
||||
|
||||
<h2>Test cases</h2>
|
||||
There are four rules in <a href="redirect-rules.json">redirect-rules.json</a>; each rule has a test case here.
|
||||
<ul>
|
||||
<li>1: <a href="https://example.com/">example.com/</a> should redirect to <a href="redirectTarget.html">redirectTarget.html</a> packaged in the extension.</li>
|
||||
<li>2: <a href="https://example.com/ew">example.com/ew</a> should redirect to <code>extensionworkshop.com</code></li>
|
||||
<li>3: <a href="https://www.example.com/anything">https://www.example.com/anything</a> should redirect to <code>https://example.com/anything?redirected_from_www=1</code>.</li>
|
||||
<li>4: <a href="http://example.com/no_question">http://example.com/no_question</a> should redirect to <code>https://example.com/no_question?redirected_by_regex</code>.</li>
|
||||
</ul>
|
||||
|
||||
<script src="popup.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
37
dnr-redirect-url/popup.js
Normal file
37
dnr-redirect-url/popup.js
Normal file
@@ -0,0 +1,37 @@
|
||||
"use strict";
|
||||
|
||||
if (typeof browser == "undefined") {
|
||||
// `browser` is not defined in Chrome, but Manifest V3 extensions in Chrome
|
||||
// also support promises in the `chrome` namespace, like Firefox. To easily
|
||||
// test the example without modifications, polyfill "browser" to "chrome".
|
||||
globalThis.browser = chrome;
|
||||
}
|
||||
|
||||
const permissions = {
|
||||
// This origin is listed in host_permissions:
|
||||
origins: ["*://*.example.com/"],
|
||||
};
|
||||
|
||||
const checkbox_host_permission = document.getElementById("checkbox_host_permission");
|
||||
checkbox_host_permission.onchange = async () => {
|
||||
if (checkbox_host_permission.checked) {
|
||||
let granted = await browser.permissions.request(permissions);
|
||||
if (!granted) {
|
||||
// Permission request was denied by the user.
|
||||
checkbox_host_permission.checked = false;
|
||||
}
|
||||
} else {
|
||||
try {
|
||||
await browser.permissions.remove(permissions);
|
||||
} catch (e) {
|
||||
// While Chrome allows granting of host_permissions that have manually
|
||||
// been revoked by the user, it fails when revoking them, with
|
||||
// "Error: You cannot remove required permissions."
|
||||
console.error(e);
|
||||
checkbox_host_permission.checked = true;
|
||||
}
|
||||
}
|
||||
};
|
||||
browser.permissions.contains(permissions).then(granted => {
|
||||
checkbox_host_permission.checked = granted;
|
||||
});
|
||||
65
dnr-redirect-url/redirect-rules.json
Normal file
65
dnr-redirect-url/redirect-rules.json
Normal file
@@ -0,0 +1,65 @@
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"priority": 4,
|
||||
"condition": {
|
||||
"urlFilter": "||example.com/|",
|
||||
"resourceTypes": ["main_frame"]
|
||||
},
|
||||
"action": {
|
||||
"type": "redirect",
|
||||
"redirect": {
|
||||
"extensionPath": "/redirectTarget.html"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"priority": 3,
|
||||
"condition": {
|
||||
"urlFilter": "||example.com/ew",
|
||||
"resourceTypes": ["main_frame"]
|
||||
},
|
||||
"action": {
|
||||
"type": "redirect",
|
||||
"redirect": {
|
||||
"url": "https://extensionworkshop.com/"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"priority": 2,
|
||||
"condition": {
|
||||
"urlFilter": "|https://www.example.com/",
|
||||
"resourceTypes": ["main_frame"]
|
||||
},
|
||||
"action": {
|
||||
"type": "redirect",
|
||||
"redirect": {
|
||||
"transform": {
|
||||
"host": "example.com",
|
||||
"queryTransform": {
|
||||
"addOrReplaceParams": [
|
||||
{ "key": "redirected_from_www", "value": "1" }
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"condition": {
|
||||
"regexFilter": "^https?://([^?]+)$",
|
||||
"requestDomains": ["example.com"],
|
||||
"resourceTypes": ["main_frame"]
|
||||
},
|
||||
"action": {
|
||||
"type": "redirect",
|
||||
"redirect": {
|
||||
"regexSubstitution": "https://\\1?redirected_by_regex"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
38
dnr-redirect-url/redirectTarget.html
Normal file
38
dnr-redirect-url/redirectTarget.html
Normal file
@@ -0,0 +1,38 @@
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width"> <!-- mobile-friendly -->
|
||||
<title>redirectTarget.html</title>
|
||||
</head>
|
||||
<body>
|
||||
This page is the redirect target of requests matching rule 1 from <a href="redirect-rules.json">redirect-rules.json</a>.<br>
|
||||
The pattern <code>||example.com/|</code> means: (sub)domain of <code>example.com</code>, with path "/" and nothing else before the end of the URL.
|
||||
<pre>
|
||||
{
|
||||
"id": 1,
|
||||
"priority": 4,
|
||||
"condition": {
|
||||
"urlFilter": "||example.com/|",
|
||||
"resourceTypes": ["main_frame"]
|
||||
},
|
||||
"action": {
|
||||
"type": "redirect",
|
||||
"redirect": {
|
||||
"extensionPath": "/redirectTarget.html"
|
||||
}
|
||||
}
|
||||
},
|
||||
</pre>
|
||||
|
||||
For the redirect to have succeeded, three conditions must be met:
|
||||
|
||||
<ul>
|
||||
<li> The declarativeNetRequest (DNR) rule should match the request.</li>
|
||||
<li> The extension must declare the pre-redirect URL in <code>host_permissions</code> (in manifest.json) and the user should grant the permission.</li>
|
||||
<li> The extension path in <code>extensionPath</code> must be declared in <code>web_accessible_resources</code> (in manifest.json), and the pre-redirect URL should match the pattern in <code>matches</code>.</li>
|
||||
</ul>
|
||||
|
||||
See <a href="popup.html">popup.html</a> for the permissions UI and examples.
|
||||
</body>
|
||||
</html>
|
||||
@@ -156,6 +156,43 @@
|
||||
"javascript_apis": [],
|
||||
"name": "discogs-search"
|
||||
},
|
||||
{
|
||||
"description": "Demonstrates how to block network requests without host permissions using the declarativeNetRequest API with the `declarative_net_request` manifest key.",
|
||||
"javascript_apis": [
|
||||
"declarativeNetRequest.Rule",
|
||||
"declarativeNetRequest.RuleAction",
|
||||
"declarativeNetRequest.RuleCondition"
|
||||
],
|
||||
"name": "dnr-block-only"
|
||||
},
|
||||
{
|
||||
"description": "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 DNR rules.",
|
||||
"javascript_apis": [
|
||||
"declarativeNetRequest.Rule",
|
||||
"declarativeNetRequest.getDynamicRules",
|
||||
"declarativeNetRequest.getSessionRules",
|
||||
"declarativeNetRequest.updateDynamicRules",
|
||||
"declarativeNetRequest.updateSessionRules",
|
||||
"permissions.getAll",
|
||||
"permissions.remove",
|
||||
"permissions.request"
|
||||
],
|
||||
"name": "dnr-dynamic-with-options"
|
||||
},
|
||||
{
|
||||
"description": "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, and includes a comparison with Manifest Version 2 (MV2).",
|
||||
"javascript_apis": [
|
||||
"declarativeNetRequest.Redirect",
|
||||
"declarativeNetRequest.Rule",
|
||||
"declarativeNetRequest.RuleAction",
|
||||
"declarativeNetRequest.RuleCondition",
|
||||
"declarativeNetRequest.URLTransform",
|
||||
"permissions.contains",
|
||||
"permissions.remove",
|
||||
"permissions.request"
|
||||
],
|
||||
"name": "dnr-redirect-url"
|
||||
},
|
||||
{
|
||||
"description": "Dynamic theme example",
|
||||
"javascript_apis": [
|
||||
|
||||
Reference in New Issue
Block a user