@adguard/api
Advanced tools
AdGuard API is a filtering library that provides the following features:
@adguard/api module via npm or pnpmnpm install @adguard/api
or
pnpm add @adguard/api
AdguardApi class to the background scriptimport { AdguardApi } from "@adguard/api";
adguard-contents at the top of your content script entryimport '@adguard/api/content-script';
adguard-assistant at the top of your assistant script entryimport '@adguard/api/assistant';
AdGuard API 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.
Syntax:
type Configuration = {
filters: number[],
filteringEnabled: boolean,
allowlist?: string[],
blocklist?: string[],
rules?: string[],
filtersMetadataUrl: string,
filterRulesUrl: string,
documentBlockingPageUrl?: string,
};
Properties:
filters (mandatory) - An array of filters identifiers. You can look for
possible filters identifiers in the filters metadata file.
filteringEnabled (mandatory) - Enable/disable filtering engine.
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.
filtersMetadataUrl (mandatory) - An absolute path to a file, containing
filters metadata. Once started, AdGuard will periodically check filters
updates by downloading this file. Example:
https://filters.adtidy.org/extension/chromium/filters.json.
filterRulesUrl (mandatory) - URL mask used for fetching filters rules.
{filter_id} parameter will be replaced with an actual filter identifier.
Example: https://filters.adtidy.org/extension/chromium/filters/{filter_id}.txt
(English filter (filter id = 2) will be loaded from:
https://filters.adtidy.org/extension/chromium/2.txt)
documentBlockingPageUrl (optional) - Path to the document blocking page. If
not specified, the default browser page will be shown.
Example:
const configuration: Configuration = {
filters: [],
allowlist: [],
blocklist: [],
rules: [],
filtersMetadataUrl: 'https://filters.adtidy.org/extension/chromium/filters.json',
filterRulesUrl: 'https://filters.adtidy.org/extension/chromium/filters/{filter_id}.txt'
};
![!WARNING] Please note, that we do not allow using
filters.adtidy.orgother than for testing purposes. You have to use your own server for storing filter files. You can (and actually should) usefilters.adtidy.orgfor periodically updating files on your side.
Creates a new AdguardApi instance.
AdguardApi.createSyntax:
public static async create(): Promise<AdguardApi>
Example:
const adguardApi = await AdguardApi.create();
adguardApi.getMessageHandlerGets 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.
Syntax:
public getMessageHandler(): MessageHandlerMV2
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.startInitializes AdGuard API and starts it immediately.
Syntax:
public async start(configuration: Configuration): Promise<Configuration>
Example:
const appliedConfiguration = await adguardApi.start(configuration);
Parameters:
configuration - API ConfigurationReturns:
A Promise, resolved with applied API Configuration when api is initialized and filtering started
adguardApi.stopCompletely stops AdGuard API.
Syntax:
public async stop(): Promise<void>
Example:
await adguardApi.stop();
Returns:
Promise, resolved when API is completely stopped
adguardApi.configureThis 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 ConfigurationReturns:
A Promise object that is getting resolved with applied
API Configuration when the API config is updated.
adguardApi.setFilteringEnabledEnables or disables filtering without engine re-initialization.
Syntax:
public async setFilteringEnabled(value: boolean): Promise<void>
Example:
await adguardApi.setFilteringEnabled(false);
Parameters:
value - boolean value that indicates the filtering engine state.Returns:
A Promise object that is getting resolved when filtering engine state is
updated.
adguardApi.openAssistantOpens 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-TabReturns:
A Promise object that is getting resolved when the Assistant UI is opened in
the specified tab.
adguardApi.closeAssistantCloses 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-TabReturns:
A Promise object that is getting resolved when Assistant UI id closed in the
specified tab.
adguardApi.getRulesCountGets currently loaded rules count.
Syntax:
public getRulesCount(): number
Example:
adguardApi.getRulesCount();
Returns:
rules count number
adguardApi.onAssistantCreateRuleTsWebExtension 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.onFiltersDeletionTsWebExtension Event channel, which fires event on obsoleted filters deletion. It can be fired after checking an update for filters in the FiltersUpdateService.
Syntax:
public onFiltersDeletion: EventChannel<number[]>;
Example:
// update config on filter deletion
const removeObsoletedFilterId = async (filterIds: number[]): Promise<void> => {
console.log(`Filters with ids ${filterIds} deleted because they became obsoleted.`);
configuration.filters = configuration.filters.filter((id) => !filterIds.includes(id));
await adguardApi.configure(configuration);
};
// add listener
adguardApi.onFiltersDeletion.subscribe(removeObsoletedFilterId);
// remove listener
adguardApi.onFiltersDeletion.unsubscribe(removeObsoletedFilterId);
adguardApi.onRequestBlockingAPI for adding and removing listeners for request blocking events.
Syntax:
export interface RequestBlockingLoggerInterface {
addListener(listener: EventChannelListener<RequestBlockingEvent>): void;
removeListener(listener: EventChannelListener<RequestBlockingEvent>): void;
}
Example:
// Registers an event listener
adguardApi.onRequestBlocked.addListener(
callback // function, mandatory
)
// Removes specified event listener
adguardApi.onRequestBlocked.removeListener(
callback // function, mandatory
)
Callback parameter properties:
tabId - Tab identifier.requestUrl - URL of the blocked request.referrerUrl - Referrer URL.ruleIndex - Filtering rule index that has been applied to this request.
Can be undefined, e.g. during company category matching.filterId - ID of the filter list the rule belongs to.
Can be undefined, e.g. during company category matching.requestType - Request mime type. Possible values are listed below:Request types:
DOCUMENT- top-level frame document.SUBDOCUMENT- document loaded in a nested frame.SCRIPTSTYLESHEETOBJECTIMAGEXMLHTTPREQUESTMEDIAFONTWEBSOCKETOTHER
See full sample app project in examples/adguard-api
import { AdguardApi, Configuration, RequestBlockingEvent } from "@adguard/api";
(async (): Promise<void> => {
// create new AdguardApi instance
const adguardApi = AdguardApi.create();
const configuration: Configuration = {
filters: [2],
allowlist: ["www.example.com"],
rules: ["example.org##h1"],
filterRulesUrl: "https://filters.adtidy.org/extension/chromium/filters/{filter_id}.txt",
filtersMetadataUrl: "https://filters.adtidy.org/extension/chromium/filters.json",
};
// console log event on request blocking
const onRequestBlocked = (event: RequestBlockingEvent) => {
console.log(event);
};
// console log current rules count, loaded in engine
const logTotalCount = (): void => {
console.log("Total rules count:", adguardApi.getRulesCount());
};
adguardApi.onRequestBlocked.addListener(onRequestBlocked);
await adguardApi.start(configuration);
console.log("Finished Adguard API initialization.");
logTotalCount();
configuration.allowlist!.push("www.google.com");
await adguardApi.configure(configuration);
console.log("Finished Adguard API re-configuration");
logTotalCount();
// update config on Assistant rule apply
adguardApi.onAssistantCreateRule.subscribe(async (rule) => {
console.log(`Rule ${rule} was created by Adguard Assistant`);
configuration.rules!.push(rule);
await adguardApi.configure(configuration);
console.log("Finished Adguard API re-configuration");
logTotalCount();
});
chrome.runtime.onMessage.addListener(async (message) => {
switch (message.type) {
case "OPEN_ASSISTANT": {
chrome.tabs.query({ active: true }, async (res) => {
if (res[0]?.id) {
await adguardApi.openAssistant(res[0].id);
}
});
break;
}
default:
// do nothing
}
});
// Disable Adguard in 1 minute
setTimeout(async () => {
adguardApi.onRequestBlocked.removeListener(onRequestBlocked);
await adguardApi.stop();
console.log("Adguard API has been disabled.");
}, 60 * 1000);
})();
| Browser | Version |
|---|---|
| Chromium Based Browsers | 79 |
| Firefox | 78 |
| Opera | 66 |
| Edge | 79 |
FAQs
This is a TypeScript library that implements AdGuard's extension API
We found that @adguard/api demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Application Security
/Security News
Socket CEO Feross Aboukhadijeh and a16z partner Joel de la Garza discuss vibe coding, AI-driven software development, and how the rise of LLMs, despite their risks, still points toward a more secure and innovative future.
Research
/Security News
Threat actors hijacked Toptal’s GitHub org, publishing npm packages with malicious payloads that steal tokens and attempt to wipe victim systems.
Research
/Security News
Socket researchers investigate 4 malicious npm and PyPI packages with 56,000+ downloads that install surveillance malware.