Merge pull request #533 from AdguardTeam/agm-2120-add-mv3-article

add mv3 info in kb

docs/adguard-browser-extension/mv3-version.md

@@ -0,0 +1,100 @@
+---
+title: AdGuard Browser Extension for Chrome MV3
+sidebar_position: 5
+---
+
+As MV2 extensions are being phased out in the Chrome Web Store, Chrome users may need to switch to MV3 extensions that are compatible with Chrome’s new API Manifest V3. Our thoughts on this topic are extensively discussed on [our blog](https://adguard.com/en/blog/tag/manifest-v3.html).
+
+Our MV3 extension effectively blocks ads and trackers while seamlessly managing social widgets, banners, and video ads. Most users will not notice any operational differences, but there are some limitations and changes to be aware of.
+
+## Where to find our extensions
+
+The **MV3 version** will soon replace our old extension in the [Chrome Web Store](https://chromewebstore.google.com/detail/adguard-adblocker/bgnkhhnnamicmpeenaelnjfhikgbkllg).
+
+The **beta version of MV3** will still be available in the [Chrome Web Store](https://chromewebstore.google.com/detail/adguard-adblocker-mv3-exp/apjcbfpjihpedihablmalmbbhjpklbdf).
+
+The old beta extension will be renamed to [**AdGuard Ad Blocker MV2**](https://chromewebstore.google.com/detail/adguard-adblocker-beta/gfggjaccafhcbfogfkogggoepomehbjl) and will be supported until Google phases it out.
+
+## Main changes in features and settings
+
+- **No auto and manual filter updates.** The options *Auto-update filters* and *Check filters update* are no longer available in the *Filters* tab. Since some of the rules are now applied in DNR form, we can’t update filters on request, only through the full process of updating the extension along with the review in the stores.
+
+- **Filtering log**
+
+  ![Filtering log *border](https://cdn.adtidy.org/content/blog/mv3/new/log.png)
+
+  Due to DNR restrictions, we can’t show exactly which rule worked, but we will provide an “approximate rule that was triggered” based on our engine. For precise information, you’ll need to install the “unpacked” form of the extension in your browser yourself. You’ll find detailed instructions on how to do this in a [separate article](adguard-browser-extension/solving-problems/debug-rules).
+
+- *Tracking protection* (formerly known as *Stealth mode*)
+
+  ![Tracking protection *border](https://cdn.adtidy.org/content/blog/mv3/new/tracking_screen.png)
+
+  There are no *Cookies* section, along with *Self-destruction of first-party cookies* and *Self-destruction of third-party cookies* since we cannot set the TTL of cookies using declarative rules.
+
+- *Phishing & malware protection* is no longer available in the general settings. To protect yourself from malicious websites and scams, enable the appropriate filters in the *Security* tab.
+
+  ![Security](https://cdn.adtidy.org/content/blog/mv3/new/security.png)
+
+## Limitations
+
+### Maximum number of rules and filters
+
+Manifest V3 imposes limits on static and regex rules per extension. Users may receive notifications when these limits are exceeded.
+
+![Rule limits *border](https://cdn.adtidy.org/content/blog/new/rulelimits.png)
+
+![Too many extensions *border](https://cdn.adtidy.org/content/blog/new/other_extension.png)
+
+Basically, Manifest V3 divides rules into static (built-in) and dynamic, with strict limits in place.
+
+**Static rules:** minimum **30,000** rules per extension, with a cumulative limit of **330,000** for all extensions installed by a single user.
+
+For regex rules, the limit is set at **1,000 per extension**.
+
+The maximum number of simultaneously enabled filters is **50**.
+
+**Dynamic rules:** a strict cap of **5,000** rules is imposed, which includes a maximum of 1,000 regex rules.
+
+  If this limit is exceeded, only **5,000 converted rules** will be applied in the following order: first allowlist, then user rules, and finally — custom filters.
+
+> **Converted rules** are rules that have been transformed to [DNR](https://developer.chrome.com/docs/extensions/reference/api/declarativeNetRequest#build-rules) format using the [declarative converter](https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/tsurlfilter/src/rules/declarative-converter). During this conversion process, some rules may overwrite others (`badfilter`), some may be combined (`removeparame`), resulting in a list of rules with a slightly different order.
+>
+> From this list of converted rules, we will only use 5,000 rules. The rest of them will be displayed in the editor, but not applied.
+
+ Here's how a rule with a basic modifier is converted to a declarative rule:
+
+  ```bash
+  ||example.org^$script,third-party,domain=example.com
+  ```
+
+  is converted to
+
+  ```bash
+  [
+  {
+    "id": 1,
+    "action": {
+    "type": "block"
+    },
+    "condition": {
+    "urlFilter": "||example.org^",
+    "domainType": "thirdParty",
+    "initiatorDomains": [
+      "example.com"
+    ],
+    "resourceTypes": [
+      "script"
+    ]
+    },
+    "priority": 302
+  }
+  ]
+  ```
+
+  More examples can be found on [GitHub](https://github.com/AdguardTeam/tsurlfilter/tree/release/v3.1/packages/tsurlfilter/src/rules/declarative-converter#basic-examples).
+
+### Network rules
+
+Network rules have limitations: some types of rules cannot be implemented in MV3, or can only be implemented with restrictions.
+
+Below is a list of modifiers that are supported, partially supported, or not supported at all. More details about the limitations can be found on [GitHub](https://github.com/AdguardTeam/tsurlfilter/tree/release/v3.1/packages/tsurlfilter/src/rules/declarative-converter). For further information on modifiers, please refer to our [Knowledge base](/general/ad-filtering/create-own-filters/#basic-rules-basic-modifiers).

docs/adguard-browser-extension/protected-pages.md

@@ -1,6 +1,6 @@
 ---
 title: Browser-protected pages
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 :::info

docs/adguard-browser-extension/solving-problems/debug-rules.md

@@ -0,0 +1,98 @@
+---
+title: How to debug rules in AdGuard for Chrome MV3
+sidebar_position: 2
+---
+
+In [AdGuard for Chrome MV3](/adguard-browser-extension/mv3-version), the Filtering log only shows the approximate rules that were applied, which we call “assumed rules”. This is because the browser doesn’t provide details about which specific declarative rules were used unless the extension is in an “unpacked” format. To get precise information, you’ll need to install the unpacked version of the extension in your browser yourself.
+
+These instructions are also meant for problematic cases where you want to modify the rules that are bundled with the extension statically. In most cases, using *User rules* in the extension should be sufficient.
+
+## Prerequisites
+
+1. **Git:** [Install Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+
+1. **Node:** [Install Node.js](https://nodejs.org/en/download/package-manager)
+
+1. **Yarn:** [Install Yarn](https://classic.yarnpkg.com/lang/en/docs/install)
+
+## How to clone extension
+
+1. Clone the repository:
+
+    ```bash
+    git clone [email protected]:AdguardTeam/AdguardBrowserExtension.git
+    ```
+
+1. Navigate to the directory:
+
+    ```bash
+    cd AdguardBrowserExtension
+    ```
+
+1. Switch to the `v5.0` branch:
+
+    ```bash
+    git checkout v5.0
+    ```
+
+1. Install dependencies:
+
+    ```bash
+    yarn install
+    ```
+
+## How to build extension
+
+1. Switch to the `v5.0` branch:
+
+    ```bash
+    git checkout v5.0
+    ```
+
+1. Run the following command in the terminal:
+
+    ```bash
+    yarn dev chrome-mv3
+    ```
+
+1. The built extension will be located in the directory:
+
+    ```bash
+    ./build/dev/chrome-mv3
+    ```
+
+## How to install unpacked in the browser
+
+1. Turn on developer mode:
+
+    ![Developer mode](https://cdn.adtidy.org/content/Kb/ad_blocker/browser_extension/developer_mode.png)
+
+1. Click *Load unpacked*:
+
+    ![Load unacked](https://cdn.adtidy.org/content/Kb/ad_blocker/browser_extension/load_unpacked.png)
+
+1. Select the extension directory and click `Select`:
+
+    ![Select](https://cdn.adtidy.org/content/Kb/ad_blocker/browser_extension/select.png)
+
+That’s it!
+
+## How to debug rules
+
+1. Find and modify the rule you need in the `./Extension/filters/chromium-mv3` directory in the `.txt` files.
+
+1. Convert the rules from txt to declarative form:
+
+    ```bash
+    yarn convert-declarative
+    ```
+
+1. Build the extension again:
+
+    ```bash
+    yarn dev chrome-mv3
+    ```
+
+1. Reload the extension in the browser:
+
+    ![Reload extension](https://cdn.adtidy.org/content/Kb/ad_blocker/browser_extension/reload_extension.png)