Skip to content
AdGuard scriptlets library
JavaScript CSS Other
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist
scripts
src
tests
wiki update md table Dec 17, 2019
.env-example
.eslintignore
.eslintrc
.gitignore
.travis.yml
LICENSE
README.md tiny fixes Dec 6, 2019
babel.config.js
browserstack.js
browserstack.json
build.sh
corelibs.build.js refactor building scripts Dec 5, 2019
index.html
package.json
redirects.build.js refactor building scripts Dec 5, 2019
rollup.config.js
yarn.lock

README.md

AdGuard Scriptlets and Redirect resources

Build Status


Scriptlets

Scriptlet is a JavaScript function that provides extended capabilities for content blocking. These functions 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.

Syntax

rule = [domains]  "#%#//scriptlet(" scriptletName arguments ")"
  • scriptletName (mandatory) is a name of the scriptlet from AdGuard's scriptlets library
  • arguments (optional) a list of String arguments (no other types of arguments are supported)

Remarks

  • The meanining of the arguments depends on the scriptlet.
  • You can use either single or double quotes for the scriptlet name and arguments.
  • Special characters must be escaped properly:
    • "prop[\"nested\"]" - valid
    • "prop['nested']" - also valid
    • "prop["nested"]" - not valid

Example

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

This rule applies the abort-on-property-read scriptlet on all pages of example.org and its subdomains, and passes one orgument to it (alert).

Redirect resources

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

Syntax

AdGuard uses the same filtering syntax as uBlock Origin. Also, it is compatible with ABP $rewrite modifier.

$redirect is a modifier for the basic filtering 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 resources below.

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 -- redirects all requests to test.mp4 to the resource named noopmp4-1s.

$redirect rules priority is higher than the regular basic blocking rules' priority. This means that if there's a basic blocking rule (even with $important modifier), $redirect rule will prevail over it. If there's a whitelist (@@) rule matching the same URL, it will disable redirecting as well (unless the $redirect rule is also marked as $important).

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


How to build

Install dependencies

yarn install

Build for CoreLibs

yarn corelibs

Build for Extension

yarn build

Build dev (rebuild js files on every change)

yarn watch

Run node testing

yarn test

Run tests gui

yarn gui-test

To run browserstack tests create .env file or rename .env-example.

Fill in and with data from your Browserstack profile. Run next command

yarn browserstack

Build output

Scriptlets library

dist/scriptlets.js

Creates a global variable scriptlets.

/**
* Returns scriptlet code
*
* @param {Source} source
* @returns {string}
*/
scriptlets.invoke(source)

Corelibs library

dist/scriptlets.corelibs.json

File example

{
    "version": "1.0.0",
    "scriptlets": [
        {
            "names": [
                "abort-on-property-read",
                "ubo-abort-on-property-read.js",
                "abp-abort-on-property-read"
            ],
            "scriptlet": "function() { ...code... }"
        },
    ]
}

Schema

{
    "type": "object",
    "properties": {
        "version": {
            "type": "string"
        },
        "scriptlets": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "names": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "scriptlet": {
                        "type": "string"
                    }
                },
            }
        }
    }
}

Redirects library

dist/redirects.js
dist/redirects.yml

Creates a global variable Redirects.

// Usage

/**
 * Converts rawYaml into JS object with sources titles used as keys
 */
const redirects = new Redirects(rawYaml)

/**
 * Returns redirect source object by title
 */
const redirect = redirect.getRedirect('noopjs');

/**
 * Redirect - object with following props
 * {
 *      title: 1x1-transparent.gif
 *      comment: http://probablyprogramming.com/2009/03/15/the-tiniest-gif-ever
 *      contentType: image/gif;base64
 *      content: R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==
 * }
 */

Browser Compatibility

Chrome Edge Firefox IE Opera Safari
55 15 52 11 42 10
You can’t perform that action at this time.