diff --git a/dnr-block-only/README.md b/dnr-block-only/README.md index aa2e5d8e..94916c3d 100644 --- a/dnr-block-only/README.md +++ b/dnr-block-only/README.md @@ -7,7 +7,8 @@ declarativeNetRequest API with the `declarative_net_request` manifest key. This extension blocks: -- network requests to URLs containing "blocksub" (except for top-level navigations). +- network requests to URLs containing "blocksub" (except for top-level + navigations). - top-level navigation to URLs containing "blocktop". - all requests containing "blockall". @@ -18,9 +19,13 @@ This demo page does not need to be packaged with the extension. 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. +- 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 diff --git a/dnr-dynamic-with-options/README.md b/dnr-dynamic-with-options/README.md index 9b11c052..993ca1b2 100644 --- a/dnr-dynamic-with-options/README.md +++ b/dnr-dynamic-with-options/README.md @@ -70,7 +70,8 @@ How to retrieve and dynamically register declarativeNetRequest rules, using: 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. + 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 diff --git a/dnr-redirect-url/README.md b/dnr-redirect-url/README.md index 4fbd9fed..27bc5276 100644 --- a/dnr-redirect-url/README.md +++ b/dnr-redirect-url/README.md @@ -2,18 +2,21 @@ 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. +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: +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. +- 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. @@ -21,21 +24,27 @@ 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. -- use the `permissions.contains` API to check whether an extension is granted host permissions. -- use the `permissions.request` API to request host permissions from the `action` popup panel. +- 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 `regexSubstitution`. -- use "priority" to specify the rule to action when multiple rule conditions are matched to a request. -- specify the "declarativeNetRequestWithHostAccess" permission in the - manifest.json, which 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.) +- 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