AdGuard Scriptlets and Redirect Resources

AdGuard's Scriptlets and Redirect resources library which provides extended capabilities for content blocking.

• Scriptlets
  • Syntax
    • Blocking rules
    • Exception rules
  • Available scriptlets
  • Scriptlets compatibility table
  • Trusted scriptlets
    • Restriction
    • Available trusted scriptlets
• Redirect resources
  • Syntax
  • Available redirect resources
  • Redirect resources compatibility table
• Development
  • How to build
  • How to test
  • How to link packages
  • How to update wiki
• Usage
  • CoreLibs
  • NPM module
• API description
  • Scriptlets API
    • invoke()
    • getScriptletFunction()
    • Properties
      • SCRIPTLETS_VERSION
    • ContentScriptApi
      • PolicyApi
  • Redirects API
    • Redirects class
    • getRedirect()
    • isBlocking()
    • getRedirectFilename()
  • Validators API
    • isValidScriptletName()
    • isValidScriptletRule()
    <!-- markdownlint-disable-next-line -->
    • isAdgScriptletRule(), isUboScriptletRule(), isAbpSnippetRule()
    • isValidAdgRedirectRule()
    • isRedirectResourceCompatibleWithAdg()
  • Converters API
    • convertUboToAdg()
    • convertAbpToAdg()
    • convertScriptletToAdg()
    • convertAdgToUbo()
    • convertAdgRedirectToUbo()
• Browser compatibility
• Projects using Scriptlets

---

Scriptlets

Scriptlet is a JavaScript function which can be used in a declarative manner in AdGuard filtering rules.

AdGuard supports a lot of different scriptlets. Please note, that in order to achieve cross-blocker compatibility, we also support syntax of uBO and ABP.

<a name="scriptlet-syntax"></a> Syntax

<a name="scriptlet-syntax--blocking"></a> Blocking rules

[domains]#%#//scriptlet(name[, arguments])

• domains — optional, a list of domains where the rule should be applied;
• name — required, a name of the scriptlet from AdGuard Scriptlets library;
• arguments — optional, a list of string arguments (no other types of arguments are supported).

Remarks

• The meaning of the arguments depends on the scriptlet.

• Special characters in scriptlet argument must be escaped properly:

  • valid:
    • 'prop["nested"]'
    • "prop['nested']"
    • 'prop[\'nested\']'
    • "prop[\"nested\"]"
  • not valid:
    • 'prop['nested']'
    • "prop["nested"]"

• Scriptlet name and each of the arguments should be wrapped in quotes. You can use either single or double quotes for the scriptlet name and arguments. Single quote is recommended but not for cases when its usage makes readability worse, e.g. ".css('display','block');" is more preferred then '.css(\'display\',\'block\');'.

<a name="scriptlet-syntax--exceptions"></a> Exception rules

[domains]#@%#//scriptlet([name[, arguments]])

• domains — optional, a list of domains where the rule should be applied;
• name — optional, a name of the scriptlet to except from the applying; if not set, all scriptlets will not be applied;
• arguments — optional, a list of string arguments to match the same blocking rule and disable it.

Examples

1. Apply the abort-on-property-read scriptlet on all pages of example.org and its subdomains, and passes one argument to it (alert):

   example.org#%#//scriptlet('abort-on-property-read', 'alert')
   

2. Remove the branding class from all div[class^="inner"] elements on all pages of example.org and its subdomains:

   example.org#%#//scriptlet('remove-class', 'branding', 'div[class^="inner"]')
   

3. Apply set-constant and set-cookie on any webpage, but because of specific scriptlet exception rule only set-constant scriptlet will be applied on example.org and its subdomains:

   #%#//scriptlet('set-constant', 'adList', 'emptyArr')
   #%#//scriptlet('set-cookie', 'accepted', 'true')
   example.org#@%#//scriptlet('set-cookie')
   

4. Apply adjust-setInterval on any webpage, and set-local-storage-item on all pages of example.com and its subdomains, but there is also multiple scriptlet exception rule, so no scriptlet rules will be applied on example.com and its subdomains:

   #%#//scriptlet('adjust-setInterval', 'count', '*', '0.001')
   example.com#%#//scriptlet('set-local-storage-item', 'ALLOW_COOKIES', 'false')
   example.com#@%#//scriptlet()
   

• Scriptlets list
• Scriptlets compatibility table

<a name="trusted-scriptlets"></a> Trusted scriptlets

Trusted scriptlets are scriptlets with extended functionality. Their names are prefixed with trusted-, e.g trusted-click-element, to be easily distinguished from common scriptlets.

<a name="trusted-scriptlets-restriction"></a> Restriction

Trusted scriptlets application must be restricted due to dangerous nature of their capabilities. Allowed sources of trusted scriptlets are:

• filters created by AdGuard Team,
• custom filters which were installed as trusted,
• user rules.

Trusted scriptlets has no compatibility table as they are not compatible with any other blocker.

Trusted scriptlets list

Redirect resources

AdGuard is able to redirect web requests to a local "resource".

<a name="redirect-syntax"></a> Syntax

AdGuard uses the same filtering rule syntax as [uBlock Origin][ubo-redirect]. Also, it is compatible with ABP $rewrite=abp-resource modifier.

$redirect is a modifier for [the basic filtering rules][kb-basic-rules] so rules with this modifier support all other basic modifiers like $domain, $third-party, $script, etc.

The value of the $redirect modifier must be the name of the resource that will be used for redirection. See the list of available redirect resources.

Priority of $redirect rules is described in the [Knowledge Base][kb-redirect-priority].

Examples

• ||example.org/script.js$script,redirect=noopjs — redirects all requests to script.js to the resource named noopjs.
• ||example.org/test.mp4$media,redirect=noopmp4-1s — requests to example.org/test.mp4 will be redirected to the resource named noopmp4-1s.

uBlock Origin specifies additional resource name none that can disable other redirect rules. AdGuard does not support it, use $badfilter to disable specific rules.

• Redirect resources list
• Redirect resources compatibility table

---

<a name="development"></a> Development

<a name="how-to-build"></a> How to build

Install dependencies:

pnpm install

Build dist:

pnpm build

In tsurlfilter directory install and link dependencies, link scriptlets, move into package and build, and create tsurlfilter link.

lerna bootstrap

pnpm link --global "@adguard/scriptlets"

cd ./packages/tsurlfilter

pnpm build

pnpm link --global

In extension directory install dependencies, link packages and build

pnpm install

pnpm link --global "@adguard/scriptlets"

# run build script

<a name="how-to-test"></a> How to test

Some tests are run in QUnit, some in Vitest.

Run all tests:

pnpm test

1. QUnit is used for testing of scriptlets, redirects, and helpers:

   pnpm test:qunit [scriptlets | redirects | helpers]
   

   For scriptlets and redirects test run can be more specific:

   // node test run
   pnpm test:qunit scriptlets --name set-cookie
   pnpm test:qunit redirects --name ati-smarttag
   
   // gui test run
   pnpm test:qunit scriptlets --name set-cookie --gui
   pnpm test:qunit redirects --name ati-smarttag --gui
   

   For debugging purposes after some test is running in gui mode, you may change your scriptlet/redirect code, and without stopping the server run in new terminal:

   pnpm test:qunit scriptlets --name set-cookie --build
   

2. Run all jest tests:

   pnpm test:vitest
   

   or limit the testing — include may