AdGuard API MV3

AdGuard API is a filtering library that provides the following features:

• Request and content filtering, using @adguard/tswebextension.
• Content blocking via AdGuard Assistant UI.

Table of contents

• Installation
• Required web accessible resources
• Required declarativeNetRequest API assets
• Configuration
• Local Script Rules for MV3
• Excluding Unsafe Rules for Chrome Web Store "Skip Review"
• Static methods
  • AdguardApi.create
• Methods
  • adguardApi.getMessageHandler
  • adguardApi.start
  • adguardApi.stop
  • adguardApi.configure
  • adguardApi.openAssistant
  • adguardApi.closeAssistant
  • adguardApi.getRulesCount
  • adguardApi.onAssistantCreateRule
  • adguardApi.onRequestBlocked
• Usage
• Minimum supported browser versions
• Development
  • Install dependencies
  • Build
  • Lint

Installation

1. Install the @adguard/api-mv3 module via npm or yarn

   npm install @adguard/api-mv3

   or

   yarn add @adguard/api-mv3

2. Import the AdguardApi class to the background script

   import { AdguardApi } from "@adguard/api-mv3";

3. Import adguard-contents at the top of your content script entry

   import '@adguard/api-mv3/content-script';

4. Import adguard-assistant at the top of your assistant script entry

   import '@adguard/api-mv3/assistant';

Required web accessible resources

AdGuard API MV3 requires web accessible resources from the AdGuard Scriptlets library to be able to redirect web requests to a local "resource" using the $redirect rule modifier. You can use @adguard/tswebextension CLI to download it.

Required declarativeNetRequest API assets

IMPORTANT: To correct work of $redirect path should be /web-accessible-resources/redirects. If you are using @adguard/dnr-rulesets package, path to web accessible resources is built-in into converted rules with $redirect modifier and packed inside rulesets.

AdGuard API MV3 requires prebuilt DNR rule sets to be able to filter web requests. You can use @adguard/dnr-rulesets CLI to download it. We also provide a extension example with scripts for loading DNR rulesets and patching manifest in the examples/adguard-api-mv3 directory.

Configuration

Syntax:

type Configuration = {
    filters: number[];
    filteringEnabled: boolean;
    assetsPath: string;
    allowlist?: string[] | undefined;
    blocklist?: string[] | undefined;
    rules?: string[] | undefined;
    documentBlockingPageUrl?: string | undefined;
};

Properties:

• filters (mandatory) - An array of filters identifiers. You can look for possible filters identifiers in dnr-rulesets.

• filteringEnabled (mandatory) - Enable/disable filtering engine.

• assetsPath (mandatory) - Path to the directory with DNR rule sets. You can use the dnr-rulesets CLI to download DNR rule sets.

• allowlist (optional) - An array of domains, for which AdGuard won't work.

• blocklist (optional) - This property completely changes AdGuard behavior. If it is defined, Adguard will work for domains from the blocklist only. All other domains will be ignored. If blocklist is defined, allowlist will be ignored.

• rules (optional) - An array of custom filtering rules. Here is an article describing filtering rules syntax. These custom rules might be created by a user via AdGuard Assistant UI.

• documentBlockingPageUrl (optional) - Redirect URL for blocking rules with $document modifier. If not specified, default browser page will be shown. Page will receive following query parameters:

  • url - blocked URL
  • rule - blocking rule that triggered on this URL
  • filterId - ID of the filter that contains this rule (0 for user rules)

  Example: chrome-extension://<extension_id>/blocking-page.html?url=https%3A%2F%2Fexample.net%2F&rule=example.net%24document&filterId=0

Example:

const configuration: Configuration = {
    // Filters identifiers defined in @adguard/dnr-rulesets
    filters: [1, 2, 3, 4, 9, 14],
    filteringEnabled: true,
    assetsPath: 'filters',
    allowlist: ['www.example.com'],
    rules: ['example.org##h1'],
};

![!WARNING] Please note, that we do not allow using filters.adtidy.org other than for testing purposes. You have to use your own server for storing filter files. You can (and actually should) use filters.adtidy.org for periodically updating files on your side.

Local Script Rules for MV3

In Manifest V3 extensions, JavaScript injection rules have strict security restrictions due to Chrome Web Store policies regarding remote code execution. The API enforces a required validation mechanism to ensure all script rules are pre-verified.

How it works

When local_script_rules.js IS provided (Recommended):

• All JS script rules are pre-verified and bundled into the extension during the build process.
• At runtime, only script rules that match entries in local_script_rules.js are executed.
• All other scripts are discarded to prevent remote code execution.
• This ensures perfect compliance with Chrome Web Store policies.

When local_script_rules.js is NOT provided:

• All script rules (except scriptlets) will be blocked for security compliance.
• The extension will not execute any custom JS rules to prevent potential remote code execution.
• It is highly recommended to always provide local_script_rules.js during your build process.

With UserScripts API permission enabled:

• Custom JS rules can be executed directly via the browser's userScripts API, which provides secure sandboxing.
• This requires explicit user activation via extension settings.

Why it's critical for MV3

Providing local_script_rules.js is essential for MV3 extensions because:

1. Chrome Web Store strictly forbids remote code execution in extensions.
2. Pre-verification ensures only safe, approved scripts can execute.
3. Failure to provide it results in all script rules being blocked.
4. This prevents Chrome Web Store rejection due to potential policy violations.

Extending local_script_rules.js

You can extend local_script_rules.js with custom rules during your extension's build process. This allows you to pre-approve specific custom scriptlets or JS injection rules before runtime.

Example implementation:

See the MV3 example extension for a complete implementation:

• Extra scripts definition: packages/examples/adguard-api-mv3/extension/src/extra-scripts.ts
• Build script usage: packages/examples/adguard-api-mv3/scripts/build/build.ts

The build script uses the AssetsLoader.extendLocalScriptRulesJs() method to add extra pre-verified rules to local_script_rules.js:

import { AssetsLoader, LOCAL_SCRIPT_RULES_JS_FILENAME } from '@adguard/dnr-rulesets';
import { extraScripts } from './extra-scripts';

const loader = new AssetsLoader();
await loader.extendLocalScriptRulesJs(
    path.join('./extension/filters', LOCAL_SCRIPT_RULES_JS_FILENAME),
    extraScripts
);

Excluding Unsafe Rules for Chrome Web Store "Skip Review"

Chrome Web Store provides a "skip review" option for extensions that only use "safe" declarativeNetRequest rules. This allows your extension updates to be published instantly without manual review, significantly reducing update deployment time.

What are safe rules?

According to Chrome's policy, only declarative rules with the following action types are considered "safe":

• block - blocks network requests
• allow - allows network requests
• allowAllRequests - allows all requests from a domain
• upgradeScheme - upgrades HTTP to HTTPS

Rules with other action types (such as redirect, modifyHeaders, removeHeaders) are considered "unsafe" and require manual review.

Why exclude unsafe rules?

To qualify for the "skip review" option in Chrome Web Store:

1. Your extension must only contain safe declarative rules
2. Unsafe rules must be excluded from your rulesets during the build process
3. This allows faster extension updates and reduces review queue time

How to exclude unsafe rules in your build process

The @adguard/dnr-rulesets package provides the excludeUnsafeRules function that:

• Scans all rulesets in your filters directory
• Identifies and removes unsafe rules
• Stores unsafe rules in metadata for reference
• Updates ruleset checksums automatically
• AdGuard API will extract unsafe rules automatically and apply them via sessionRules

CLI Usage

Add this command to your build process after loading DNR rulesets:

dnr-rulesets exclude-unsafe-rules ./extension/filters/declarative [options]

Options:

• --prettify-json (default: true) - Prettify JSON output
• --limit <number> - Maximum number of unsafe rules allowed. Build fails if exceeded.

Example in package.json:

{
  "scripts": {
    "load-dnr-rulesets": "dnr-rulesets load ./extension/filters",
    "patch-manifest": "dnr-rulesets manifest ./extension/manifest.json ./extension/filters",
    "exclude-unsafe-rules": "dnr-rulesets exclude-unsafe-rules ./extension/filters/declarative --limit 4900",
    "build": "npm run load-dnr-rulesets && npm run patch-manifest && npm run exclude-unsafe-rules"
  }
}

4900 is selected intentionally since limit for sessionRules is 5000.

Programmatic API Usage

You can also integrate excludeUnsafeRules into your build scripts:

import { excludeUnsafeRules } from '@adguard/dnr-rulesets';

async function build() {
    // Load DNR rulesets and patch manifest first
    // ... your existing build code ...

    // Exclude unsafe rules for CWS "skip review"
    await excludeUnsafeRules({
        dir: './extension/filters/declarative',
        prettifyJson: false,  // optional: minimize JSON file size
        limit: 4900,          // optional: fail build if too many unsafe rules
    });

    console.log('Unsafe rules excluded. Extension is ready for CWS skip review.');
}

Complete build script example:

import { AssetsLoader, ManifestPatcher, excludeUnsafeRules } from '@adguard/dnr-rulesets';

async function build() {
    // 1. Load DNR rulesets
    const loader = new AssetsLoader();
    await loader.load('./extension/filters');

    // 2. Patch manifest with rulesets
    const patcher = new ManifestPatcher();
    patcher.patch('./extension/manifest.json', './extension/filters', {
        forceUpdate: true,
        ids: ['2', '3'], // your filter IDs
    });

    // 3. Exclude unsafe rules for CWS "skip review"
    await excludeUnsafeRules({
        dir: './extension/filters/declarative',
        prettifyJson: false,
        limit: 4900,
    });

    // 4. Continue with your webpack/build process...
}

Important Notes

• Call order matters: Always run excludeUnsafeRules after loading rulesets and patching manifest. Prevent double call of excludeUnsafeRules in your build process since it will override unsafe rules from first call and all unsafe rules will be just deleted from rulesets.

For a complete working example, see the example extension build script.

Static methods

Creates a new AdguardApi instance.

AdguardApi.create

Syntax:

public static async create(): Promise<AdguardApi>

Example:

const adguardApi = await AdguardApi.create();

Methods

adguardApi.getMessageHandler

Gets the message handler for API content script messages.

The API message handler name is a constant that can be exported as MESSAGE_HANDLER_NAME from @adguard/api-mv3.

The list of possible message types is defined in tswebextension

Syntax:

public getMessageHandler(): MessageHandlerMV3

Example:

// get tswebextension message handler
const handleApiMessage = adguardApi.getMessageHandler();

const handleAppMessage = async (message: Message) => {
  // handle your app messages here
};

// route message depending on handler name
browser.runtime.onMessage.addListener(async (message, sender) => {
  if (message?.handlerName === MESSAGE_HANDLER_NAME) {
    return Promise.resolve(handleApiMessage(message, sender));
  }
  return handleAppMessage(message);
});

Returns:

A message handler that will listen to internal messages. For example: messages for get computed css for content-script.

adguardApi.start

Initializes AdGuard API and starts it immediately.

Syntax:

public async start(configuration: Configuration): Promise<Configuration>

Example:

const appliedConfiguration = await adguardApi.start(configuration);

Parameters:

• configuration - API Configuration

Returns:

A Promise, resolved with applied API Configuration when api is initialized and filtering started

adguardApi.stop

Completely stops AdGuard API.

Syntax:

public async stop(): Promise<void>

Example:

await adguardApi.stop();

Returns:

Promise, resolved when API is completely stopped

adguardApi.configure

This method modifies AdGuard configuration.

Note, that Adguard must be already started (see adguardApi.start).

Syntax:

public async configure(configuration: Configuration): Promise<Configuration>

Example:

const updatedConfiguration = await adguardApi.configure(configuration);

Parameters:

• configuration - API Configuration

Returns:

A Promise object that is getting resolved with applied API Configuration when the API config is updated.

adguardApi.openAssistant

Opens the AdGuard Assistant UI in the specified tab. You must also subscribe on onAssistantCreateRule event channel for applying rules that are created by Adguard Assistant.

Syntax:

public async openAssistant(tabId: number): Promise<void>

Example:

await adguardApi.openAssistant(tabId);

Parameters:

• tabId - chrome.tabs.Tab id, see: https://developer.chrome.com/docs/extensions/reference/tabs/#type-Tab

Returns:

A Promise object that is getting resolved when the Assistant UI is opened in the specified tab.

adguardApi.closeAssistant

Closes AdGuard Assistant in the specified tab.

Syntax:

public async openAssistant(tabId: number): Promise<void>

Example:

await adguardApi.closeAssistant(tabId);

Parameters:

• tabId - chrome.tabs.Tab id, see: https://developer.chrome.com/docs/extensions/reference/tabs/#type-Tab

Returns:

A Promise object that is getting resolved when Assistant UI id closed in the specified tab.

adguardApi.getRulesCount

Gets currently loaded rules count.

Syntax:

public getRulesCount(): number

Example:

adguardApi.getRulesCount();

Returns:

rules count number

adguardApi.onAssistantCreateRule

TsWebExtension event channel that receives events when a rule is created via AdGuard Assistant.

Syntax:

public onAssistantCreateRule: EventChannel<string>;

Example:

// update config on Assistant rule apply
const applyRule = async (rule): Promise<void> => {
  console.log(`Rule ${rule} was created by Adguard Assistant`);
  configuration.rules!.push(rule);
  await adguardApi.configure(configuration);
};

// add listener
adguardApi.onAssistantCreateRule.subscribe(applyRule);

// remove listener
adguardApi.onAssistantCreateRule.unsubscribe(applyRule);

adguardApi.onRequestBlocked

API for adding and removing listeners for request blocking events.

[!NOTE] You must have the webRequest permission in your manifest to use.

[!NOTE] Rule calculated by tsurlfilter is not always the same as the declarative rule that has blocked the request. That's why we provide an assumedRule and assumedFilterId properties in the event object. We will improve the rule calculation algorithm to provide more accurate results in future releases.

Syntax:

export interface RequestBlockingLoggerInterface {
    addListener(listener: EventChannelListener<RequestBlockingEvent>): void;
    removeListener(listener: EventChannelListener<RequestBlockingEvent>): void;
}

Callback parameter properties:

type RequestBlockingEvent = {
    /**
     * Tab identifier.
     */
    tabId: number;

    /**
     * Blocked request id.
     */
    requestId: string;

    /**
     * Blocked request URL.
     */
    requestUrl: string;

    /**
     * Referrer URL.
     */
    referrerUrl: string;

    /**
     * Request mime type
     */
    requestType: ContentType;

    /**
     * Assumed Filtering rule index, which has blocked this request. May not be provided if request is blocked by DNR rule.
     */
    assumedRuleIndex?: number;

    /**
     * Assumed rule's filter identifier. May not be provided if request is blocked by DNR rule.
     */
    assumedFilterId?: number;

    /**
     * Company category name for requests blocked by DNR rule. Provided only if request is blocked by DNR rule.
     */
    companyCategoryName?: string;
};

Learn more about companyCategoryName in the list of company categories.

Note that few events can be fired for the same request, e.g., when a request is blocked by a DNR rule, first event is fired during onBeforeRequest with assumedRuleIndex and assumedFilterId properties but no companyCategoryName is provided, and the second event is fired during onErrorOccurred with companyCategoryName property defined but assumedRuleIndex and assumedFilterId are -1. So you can handle such requests by the requestId property.

Example:

// Registers an event listener
adguardApi.onRequestBlocked.addListener(
  callback // function, mandatory
)
// Removes specified event listener
adguardApi.onRequestBlocked.removeListener(
  callback // function, mandatory
)

Supported Request types:

• DOCUMENT - top-level frame document.
• SUBDOCUMENT - document loaded in a nested frame.
• SCRIPT
• STYLESHEET
• OBJECT
• IMAGE
• XMLHTTPREQUEST
• MEDIA
• FONT
• WEBSOCKET
• OTHER

Usage

See full sample app project in examples/adguard-api

import browser from 'webextension-polyfill';
import { AdguardApi, type Configuration, MESSAGE_HANDLER_NAME } from '@adguard/api-mv3';

(async (): Promise<void> => {
    // create new AdguardApi instance
    const adguardApi = await AdguardApi.create();

    // console log event on request blocking
    const onRequestBlocked = (event: RequestBlockingEvent) => {
        console.log(event);
    };

    adguardApi.onRequestBlocked.addListener(onRequestBlocked);

    let configuration: Configuration = {
        /**
         * filters identifiers from dnr-rulesets
         * @see https://filters.adtidy.org/extension/chromium/filters.json
         */
        filters: [2, 3, 4],
        filteringEnabled: true,
        allowlist: ['www.example.com'],
        rules: ['example.org##h1'],
        assetsPath: 'filters',
    };

    // console log current rules count, loaded in engine
    const logTotalCount = (): void => {
        console.log('Total rules count:', adguardApi.getRulesCount());
    };

    try {
        configuration = await adguardApi.start(configuration);
        console.log('Finished Adguard API initialization.');
        console.log('Applied configuration: ', JSON.stringify(configuration));
        logTotalCount();
    } catch (error) {
        console.error('Failed to start AdGuard API:', error);
        return;
    }

    configuration.allowlist!.push('www.google.com');

    try {
        await adguardApi.configure(configuration);
        console.log('Finished Adguard API re-configuration');
        logTotalCount();
    } catch (error) {
        console.error('Failed to configure AdGuard API:', error);
    }

    const onAssistantCreateRule = async (rule: string) => {
        // update config on assistant rule apply
        console.log(`Rule ${rule} was created by Adguard Assistant`);
        configuration.rules!.push(rule);
        try {
            await adguardApi.configure(configuration);
            console.log('Finished Adguard API re-configuration');
            logTotalCount();
        } catch (error) {
            console.error('Failed to apply assistant rule:', error);
        }
    };

    adguardApi.onAssistantCreateRule.subscribe(onAssistantCreateRule);

    // get tswebextension message handler
    const handleApiMessage = adguardApi.getMessageHandler();

    // define custom message handler
    const handleAppMessage = async (message: any) => {
        switch (message.type) {
            case 'OPEN_ASSISTANT': {
                const active = await browser.tabs.query({ active: true });
                if (active[0]?.id) {
                    await adguardApi.openAssistant(active[0].id);
                }
                break;
            }
            default:
            // do nothing
        }
    };

    browser.runtime.onMessage.addListener(async (message, sender) => {
        // route message depending on handler name
        if (message?.handlerName === MESSAGE_HANDLER_NAME) {
            return Promise.resolve(handleApiMessage(message, sender));
        }
        return handleAppMessage(message);
    });

    // Disable Adguard in 1 minute
    setTimeout(async () => {
        adguardApi.onRequestBlocked.removeListener(onRequestBlocked);
        adguardApi.onAssistantCreateRule.unsubscribe(onAssistantCreateRule);
        await adguardApi.stop();
        console.log('Adguard API MV3 has been disabled.');
    }, 60 * 1000);
})();

Minimum supported browser versions

| Browser | Version | | ----------------------- | :-----: | | Chromium Based Browsers | 84 |

Development

Install dependencies

pnpm install

Build

npx lerna run build --scope @adguard/api-mv3 --include-dependencies

Lint

pnpm run lint