As per discussion with filter list maintainers.
THis requires to use JSON notation for parameter passing:
- "runAt": "end" = execute scriptlet at `DOMContentLoaded` event
- "runAt": "idle" = execute scriptlet at `load` event
A new optional parameter has been added to `set-constant`
scriptlet: `runAt`, default to `0`.
..##+js(set, document.body.oncontextmenu, null, 2)
When the `runAt` parameter is present, uBO will take it into
account to possibly defer execution of `set-constant`:
- `runAt` not present: execute immediately
- `runAt` = 1: execute immediately
- `runAt` = 2: execute when document state is "interactive"
- `runAt` = 3: execute when document state is `"complete"
maintainers.
To enable logging, use the JSON approach to pass parameters to
`acs` scriptlet. Example:
..##+js(acs, { "target": "document.oncontextmenu", "log": true })
Whereas "target", "needle", and "context" correspond to their
respective positional argument. Using JSON form to pass parameters
allows to specify extra paramters to facilitate debugging of that
scriptlet:
- `"log": true` => output useful information at the dev console.
- `"debug": true` => break at key locations in the scriptlet.
The added logging/debugging capabilities work only in the dev build
of uBO or if the advanced setting `filterAuthorMode` is set to
`true`.
The scriptlet addEventListenerLogger has been removed.
The logging of addEventListener() calls can now be done with the
addEventListenerDefuser scriptlet, which now supports the
following named arguments:
"type": the event type to match. Default to '', i.e. match-all.
"pattern": the pattern to match against the handler argument
Default to '', i.e. match-all.
"log": an integer value telling when to log:
- 1: log only when both type and pattern matches, i.e. when a
call to addEventListener() is defused
- 2: log when either the type or pattern matches
- 3: log all calls to addEventListener()
"debug": an integer value telling when to break into the
debugger, useful to inspect the debugger's call stack.
- 1: break into the debugger when both type and pattern match,
so effectively when defusing is taking place.
- 2: break into the debugger when either type or pattern matches.
The usage of named arguments is optional, positional arguments
are still supported as documented. Named arguments is required
to use "log" and/or "debug" arguments.
Obviously, do not use "log" or "debug" in any filter list, these
are investigative tools for filter list authors.
Examples of usage using named arguments:
wikipedia.org##+js(aeld, { "type": "/mouse/", "pattern": "/.^/", "log": 2 })
Above filter will log calls to addEventListener() which have the
pattern "mouse" in the event type (so "mouseover", "mouseout",
etc.) without defusing any of them (because pattern can't match
anything).
wikipedia.org##+js(aeld, { "type": "/.^/", "log": 2 })
Above filter will log all calls without defusing any of them
(because type can't match anything)
wikipedia.org##+js(aeld, { "log": 1 })
Above filter will log and defuse all calls to addEventListener().
Builtin scriptlets are no longer parsed as text-based resources,
they are imported as JS functions, and `toString()` is used to
obtain text-based representation of a scriptlet.
Scriptlet parameters are now passed as function call arguments
rather than by replacing text-based occurrences of `{{i}}`. The
arguments are always string values (see below for exception).
Support for argument as Object has been added. This opens the
door to have scriptlets using named arguments rather than
positional arguments, and hence easier to extend functionality
of existing scriptlets. Example:
example.com##+js(scriplet, { "prop": "adblock", "value": false, "log": true })
Compatibility with user-provided scriptlets has been preserved.
User-provided scriptlets can benefit some of the changes:
Use the form `function(..){..}` instead of `(function(..){..})();`
in order to received scriptlet arguments as part of function call
-- instead of using `{{i}}`.
If using the form `function(..){..}`, you can choose to receive
an Object as argument -- just be sure that your scriptlet's
parameter is valid JSON notation.
The purpose is to prevent a call to an existing function from
throwing an exception. The exception will be caught by the
scriptlet and neutralized.
The first argument must be a reference to a function call. At
the moment, the function call must exist at the time the
scriptlet is called.
Related issue:
- https://github.com/uBlockOrigin/uBlock-issues/issues/2508
If the first argument is a regex with multine flag set, the
scriptlet will execute the regex against the whole text, and
remove matching text from the whole text.
If the matching text does not contains whole lines, the text
won't be removed, i.e. it is not allowed to remove only part
of a line.
Related issue:
- https://github.com/uBlockOrigin/uBlock-issues/issues/2531#issuecomment-1462389539
Usage:
- example.com##+js(href-sanitizer, a[href^="/go?to="]:not([title]))
- example.com##+js(href-sanitizer, a[href^="/go?to="][title], [title])
The second argument is the attribute from which to extract the text
to be used for the `href` attribute of the link. If the second
attribute is absent, the text content of the element will be used.
Related issue:
- https://github.com/uBlockOrigin/uBlock-issues/issues/2531
Usage:
example.com##+js(href-from-text, a[href^="/tracker-link?to="]
The above scriptlet will find all elements matching the selector
passed as 1st argument, and replace the `href` attribute with the
text content of the element, if all the following conditions are
met:
- The element is a link (`a`) element
- The link element has an existing `href` attribute
- The text content of the element is a valid `https`-based URL
Related issue:
- https://github.com/uBlockOrigin/uAssets/issues/14849
Arguments:
1. Required. The selector of elements which are to be removed.
Example: Period[id*="-roll-"][id*="-ad-"]
2. An optional selector that must have a match in the document
for the pruning to occur. No selector means the pruning can
be performed regardless.
3. An optional URL which must be a match for the pruning to
occur. If left blank, the pruning can be performed regardless.
Related discussion:
- https://github.com/uBlockOrigin/uBlock-issues/discussions/2270
If the argument to the window-close-if scriptlet is a regex, the
match will be against the whole location URL, otherwise the
match will be against the part+query part of the location URL.
This scriplet supersedes abort-current-inline-script (acis),
and accepts an optional third argument which is matched
against the `src` property of script resources.
When the third argument is not provided, the scriptlet
behaves essentially the same as `acis`, and because of
this `acis` is now aliased to `abort-current-script`, and
all existing `acis` filters will execute with no change
in behavior.
In the long run, usage of `abort-current-inline-script` or
its alias `acis` should go away and be replaced with
`abort-current-script` or its alias `acs`.
Related issue:
- https://github.com/uBlockOrigin/uBlock-issues/issues/1553
This commit ensures FLoC is opt-in. The generic filter
`*##+js(no-floc)` in "uBlock filters -- Privacy" ensures
the feature is disabled when using default settings/lists.
Users can opt-in to FLoC by adding a generic exception
filter to their custom filters, `#@#+js(no-floc)`; or they
can opt-in only for a specific set of websites through a
more specific exception filter:
example.com,shopping.example#@#+js(no-floc)
Related issue:
- https://github.com/uBlockOrigin/uBlock-issues/issues/1445
A third (optional) argument has been added to `remove-attr`
scriptlet, which can be one or more space-separated tokens
dictating the behavior of the scriptlet:
`stay`: This tells the scriplet to stay and act on DOM
changes, whiĺe the default behavior is to act only once
when the document becomes interactive.
`complete`: This tells the scriplet to start acting only
when the document is complete, i.e. once all secondary
resources have been loaded, while the default is to start
acting when the document is interactive -- which is earlier
than when the document is complete.
Example:
...##+js(remove-attr, class, .j-mini-player, stay)
When no-fetch-if scriptlet is used without argument, the
parameters passed to no-fetch-if will be output to the
console, as `uBO: fetch([...list of arguments...])`.
The new scriptlet allows to defuse calls to fetch() by returning
a promise which always resolve to an empty response.
There is only one argument, which is a space-separated list
of conditions which must be ALL fulfilled in order for the
defusing to take place.
Each condition is a pair of property name and property value
separated by a column. Valid property names are those
documented as valid `init` options:
https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch
The URL of the fetch() is a special case and does not have to
be associated with a property name. Example of usage:
...##+js(no-fetch-if, method:HEAD)
Which means: defuse the call to fetch() if there is an
explicit option which contains `HEAD`. Another example:
...##+js(no-fetch-if, adsbygoogle.js)
Which means: defuse the call to fetch() if the URL contains
`adsbygoogle.js`. Multiple conditions can be provided:
...##+js(no-fetch-if, adsbygoogle.js method:HEAD)
If at least one condition does not match, the defusing will
not take place.
The string against which to match can be a literal regular
expression:
...##+js(no-fetch-if, /adsbygoogle.js$/ method:/HEAD|POST/)
Additonally, the following deprecated scriplets have been
removed:
- requestAnimationFrame-if.js
- setInterval-defuser.js
- setTimeout-logger.js
This new scriplet has become necessary as a
countermeasure to new bypass mechanisms by
some websites, as discussed with filter list
maintainers.
Also related discussion:
https://github.com/AdguardTeam/Scriptlets/issues/82
Scriptlet: abort-on-stack-trace
Alias: aost
Argument 1:
The property to trap in order to launch the
stack trace matching code, ex. Math.random
Argument 2:
The string (needle) to match against the stack
trace. If the empty string, always match. There
is a special string which can be used to match
inline script context, <inline-script>.
Argument 3:
Whether to log, and if so how:
Empty string: do not log
1: log stack trace for all access to trapped
property
2: log stack trace for defused access to trapped
property
3: log stack trace for non-defused access to
trapped property
Reported internally by team.
Explicit conversion was causing an exception to be
thrown when the type argument was not supporting
`toString()`, for example when `type` argument was
literal `null`.
Add support for specially-named properties:
`[]`, to iterate through all elements in an array, in
order to deal more graciously with cases where the
property to remove is an element in an array. An
actual case:
+js(json-prune, playlist.movies.0.adserver playlist.movies.1.adserver ...)
Can be now converted to:
+js(json-prune, playlist.movies.[].adserver)
`*`, to iterate through all own properties of an object,
in order to deal with random-named properties. For
example (not an actual case):
+js(json-prune, playlist.*.adserver)
Where `adserver` would be a property member of an
object which is itself a property of `playlist`, but
which name is unknown or is variable.
Specifically:
- Log entries as received by client code
- Prettier and more readable console output
- Ability to only log entries matching a
specific needle
As per internal discussion at
<https://github.com/uBlockOrigin/uAssets>; limited
logging capabilities of json-prune originally raised
by <https://github.com/gwarser>.
Related issue:
- https://github.com/uBlockOrigin/uBlock-issues/issues/981
To be consistent with no-setTimeout-if.js.
requestAnimationFrame-if.js is deprecated and must no longer be
used, it will be removed in the near future when it's no longer
in use in default filter lists.
no-requestAnimationFrame-if.js is aliased to norafif.js.
The scriptlet will now still try to trap a specific
property if a segment of the chain is not undefined
while yet not an object either.
For example, this now allows to set a value on
`document.body.onselectstart` when `document.body` has
not been instantiated yet by the browser parser,
whereas this would previously fail because
`document.body` would be `null` while the scriptlet
was testing against `undefined`.
As per feedback from filter list maintainers, the
whitelist approach has been deemed to confusing.
The scriptlet has been renamed `no-setTimeout-if`
alias `nostif` to reflect the blacklist approach.
`setInterval-if` has been Similarly changed to
`no-setInterval-if` alias `nosiif`.
The scriptlet will trap calls to JSON.parse, and
if the result of the parsing is an Object, it
will remove specified properties from the result
before returning to the caller.
Usage:
##+js(json-prune, arg1, [arg2])
Where:
- arg1: a list of space-separated properties to remove
- arg2: optional, a list of space-separated properties
which must be all present for the pruning to
occur
Example:
##+js(json-prune, enabled, adpath config)
A property in a list of properties can be a chain
of properties, example: adpath.url.first
This also apply to setInterval-if. Thus to defuse
calls to setTimeout(fn, 1000), the filter could be:
##+js(stif, , !1000)
Meaning "allow setTimeout if the delay is not 1000".
Usage is similar to that of raf-if introduced in
commit 6831967f5f.
The two new scriptlets are meant to replace:
- setTimeout-defuser
- setTimeout-logger
- setInterval-defuser
- setInterval-logger
setTimeout-logger and setInterval-logger have been
removed, since they are not to be used in production.
To log setTimeout and setInterval usage, respectively
(using aliases):
- ##+js(stif)
- ##+js(siif)
To defuse setTimeout unconditionally:
- ##+js(stif, !)
Usage of setTimeout-defuser and setInterval-defuser
is deprecated and will be removed in some future when
they are no longer in use.
Keep in mind that the new scriptlets function on a
whitelist basis, whereas the deprecated ones
function on a blacklist basis. Prefixing the needle
with `!` allow to use the new scriptlets on a
blacklist basis.
Scriptlet name: `raf-if.js`
Usage: `example.com##+js(raf-if, !/(\d+){4}/)`
Argument: one single argument, which is the "needle" to
find in the stringified argument passed to
requestAnimationFrame.
requestAnimationFrame will be defused when:
- The needle is not prefixed with `!` and the needle
does not match the stringified argument; OR
- The needle is prefixed with `!` and the needle
matches the stringified argument.
The `raf-if.js` scriptlet will log calls to
requestAnimationFrame to the console when no parameter
is provided, i.e.:
example.com##+js(raf-if)
Otherwise no logging occurs.
Since https://github.com/uBlockOrigin/uBlock-issues/issues/156
won't be fixed in next release, no need to ship
with code which will be unused, and anyways only once
the fix is worked on will it be clear exactly what needs
to be used by scriptlets to deal harmoniously with
property listener collisions.
Make sure the parser is safely compatible with old
resources format -- for those users still using
custom resources (via `userResourcesLocation`).
Prepare code for future fix to
<https://github.com/uBlockOrigin/uBlock-issues/issues/156>:
This commit introduces a new private Map() object,
`uBOSafe`, accessible by all injected scriptlets. This
private safe can be used to store data which can be shared
with different scriptlets. The idea is for scriptlets to
use that safe to graciously deal with the need to install
multiple listeners for the same property.
With hindsight, I revised decisions made earlier during
this development cycle:
Un-redirectable scriptlets have been removed from
/web_accessible_resources and instead put in the new
/assets/resources/scriptlets.js, which contains all
scriptlets used for web page injection purpose.
uBO will no longer fetch a remote version of built-in
resources.
Advanced setting `userResourcesLocation` will still be
honoured by uBO, and if set, will be fetched every
time at least one asset is updated.
