Go back to top

vivaldi.contentBlocking Modders API Reference

Provides control over the Adblocking service and other implemented content blocking measures

Types

#RuleGroup

ENUM

Used to specify whether a specific operation should apply to tracking blocking or adblocking.

  • tracking
  • ad_blocking

    • #ExceptionList

    ENUM

    Used to inform whether the exception list used in a rule group is a list of exemptions or a list for which process is enabled

  • process_list
  • exempt_list

    • #FetchResult

    ENUM

    The result of a fetch operation on a rule source.

  • success: Fetch completed successfully.
  • download_failed: For an online source, failed to download using the provided URL.
  • file_not_found: For a local source, the file provided didn't seem to exist.
  • file_read_error: For a local source, the file provided couldn't be read.
  • file_unsupported: The rules file is of an invalid format or doesn't contain any valid rule.
  • failed_saving_parsed_rules: The rules were fetched and compiled properly, but the result couldn't be saved to the profile.
  • unknown: No fetching attempt has completed yet.

    • #RulesInfo

    Information about the rules themselves and more detailed parsing results

    Properties:

    valid_rules
    integer

    The number of entries in the file that resulted in a rule being compiled.

    unsupported_rules
    integer

    The number of entries in the file that resolved to valid rules that either didn't make sense or are not supported at this time.

    invalid_rules
    integer

    The number of entries in the file that resolved to valid rules that could not be parsed to a rule or were explicitly against the spec.

    #AdBlockMetadata

    Information extracted from the adblock file comments. If the user added a malicous source, these could be anything. Handle with care.

    Properties:

    homepage
    string

    URL pointing to the original website for this list.

    title
    string

    List name.

    expires
    integer

    How often the list is refreshed, in hours.

    license
    string

    URL pointing to licensing info for the list.

    version
    integer

    Version number of the list.

    #RuleSourceSettings

    Parameters used when parsing the rules list. Can only be modified when the source is disabled

    Properties:

    allow_abp_snippets
    boolean

    If false, any present abp snippet rules will be ignored.

    naked_hostname_is_pure_host
    boolean

    If true, any rule that looks like just a host name will be converted to match only the host part of the url.

    use_whole_document_allow
    boolean

    If true, any allow rule using the document type will cause all resources loaded by matching documents to be allowed (ABP beahvior).

    #RuleSource

    Information about a loaded rule source, including its fetching status and metadata retrieved when extracting rules from it

    Properties:

    source_url
    string

    For an online source, this is the url that was provided when setting it up.

    source_file
    string

    For an local source, this is the file that was provided when setting it up.

    is_from_url
    boolean

    indicates whether the rule source is online or local, and which of the source_url and source_file fields is valid

    settings
    RuleSourceSettings

    See RuleSourceSettings.

    id
    integer

    ⚠ NO DESCRIPTION PROVIDED

    rules_list_checksum
    string

    Checksum of the compiled rule file derived from this source. This will be the empty string if the rule source has never been fetched succesfully.

    unsafe_adblock_metadata
    AdBlockMetadata

    ⚠ NO DESCRIPTION PROVIDED

    last_update
    number

    The last time the source was successfully fetched and the corresponding rules updated. Represented in milliseconds since the epoch.

    next_fetch
    number

    The next time a fetching and updating from the rule source will be attempted. Represented in milliseconds since the epoch.

    is_fetching
    boolean

    Whether fetching of the rule source is in progress

    last_fetch_result
    FetchResult

    The result of the last fetch attempt

    rules_info
    RulesInfo

    ⚠ NO DESCRIPTION PROVIDED

    removable
    boolean

    ⚠ NO DESCRIPTION PROVIDED

    loaded
    boolean

    ⚠ NO DESCRIPTION PROVIDED

    #BlockedCounter

    How often requests relating to a domain were blocked

    Properties:

    domain
    string

    ⚠ NO DESCRIPTION PROVIDED

    blocked_count
    integer

    ⚠ NO DESCRIPTION PROVIDED

    #BlockedUrlsInfo

    Information about a blocked URL

    Properties:

    url
    string

    ⚠ NO DESCRIPTION PROVIDED

    blocked_count
    integer

    ⚠ NO DESCRIPTION PROVIDED

    #TrackerInfo

    Information for a given tracker

    Properties:

    source_id
    integer

    The id of the rule source from which this info was obtained.

    info
    any

    ⚠ NO DESCRIPTION PROVIDED

    #BlockedTrackersInfo

    Information about a blocked tracker

    Properties:

    domain
    string

    ⚠ NO DESCRIPTION PROVIDED

    blocked_urls

    blocked urls that belong to this tracker

    Array of:

    • BlockedUrlsInfo
    tracker_info

    ⚠ NO DESCRIPTION PROVIDED

    Array of:

    • TrackerInfo
    blocked_count
    integer

    ⚠ NO DESCRIPTION PROVIDED

    #TabBlockedUrlsInfo

    Information about urls that got blocked, per tab

    Properties:

    tab_id
    integer

    ⚠ NO DESCRIPTION PROVIDED

    total_blocked_count
    integer

    ⚠ NO DESCRIPTION PROVIDED

    blocked_trackers_info

    blocked urls that belong to a known tracker, alongside with tracker information.

    Array of:

    • BlockedTrackersInfo
    blocked_urls_info

    blocked urls for which there is no tracker information.

    Array of:

    • BlockedUrlsInfo

    #AdAttributionDomain

    Information about which domain ad attribution is enabled for, if any, for a given tab

    Properties:

    tab_id
    integer

    ⚠ NO DESCRIPTION PROVIDED

    domain
    string

    ⚠ NO DESCRIPTION PROVIDED

    active
    boolean

    True if the tab is currently on the ad attribution domain, causing ad attribution to be enabled.

    #AllowedAdAttributionTrackers

    Information about which trackers have been allowed for ad attribution, per tab

    Properties:

    tab_id
    integer

    ⚠ NO DESCRIPTION PROVIDED

    tracker_urls

    ⚠ NO DESCRIPTION PROVIDED

    Array of:

    • string

    Listeners

    How to use listeners

    Each listener type has the same functions, used for each listener API in the same way:

    .addListener(function callback)

    Adds a function to a listener for an event

    .removeListener(function callback)

    Removes a function to a listener for an event

    .hasListener(function callback)

    Returns a boolean if a function is attached to a listener for an event

    .hasListeners()

    Returns a boolean if a listener has any attached functions

    .dispatch()

    Returns array of promises dispatched to the listener

    #onRuleSourceAdded

    Fired when a known rule source has been added

    Parameters:

    rule_source
    RuleSource

    ⚠ NO DESCRIPTION PROVIDED

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    #onRuleSourceUpdated

    The properties of a rule source have been updated, either because a fetch started or completed.

    Parameters:

    rule_source
    RuleSource

    ⚠ NO DESCRIPTION PROVIDED

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    #onRuleSourceEnabled

    Fired when a known rule source has been enabled

    Parameters:

    source_id
    integer

    ⚠ NO DESCRIPTION PROVIDED

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    #onRuleSourceDisabled

    Fired when a known rule source has been disabled

    Parameters:

    source_id
    integer

    ⚠ NO DESCRIPTION PROVIDED

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    #onRuleSourceRemoved

    Fired when a known rule source has been removed

    Parameters:

    source_id
    integer

    ⚠ NO DESCRIPTION PROVIDED

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    #onStateChanged

    Fired when a group has been enabled/disabled or when an exception state has changed.

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    #onExceptionsChanged

    Fired when the list of exceptions has changed.

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    exception_list
    ExceptionList

    ⚠ NO DESCRIPTION PROVIDED

    #onUrlsBlocked

    Fired when urls have been blocked by either the ad-blocker or the tracker-blocker. This is fired at most once per second.

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    tab_ids

    ⚠ NO DESCRIPTION PROVIDED

    Array of:

    • integer

    #onAdAttributionDomainChanged

    Fires when the eTLD+s on which ad attribution is active changes or if the tab is navigated away from that domain.

    Parameters:

    tab_id
    integer

    ⚠ NO DESCRIPTION PROVIDED

    #onAdAttributionTrackersAllowed

    Fired when trackers have been allowed on some tabs, as a result of ad attribution.

    Parameters:

    tab_ids

    ⚠ NO DESCRIPTION PROVIDED

    Array of:

    • integer

    Methods

    #setRuleGroupEnabled

    Changes whether a particular type of blocking is in effect.

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    enabled
    boolean

    ⚠ NO DESCRIPTION PROVIDED

    #isRuleGroupEnabled

    Checks whether a specific type of blocking is in effect.

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    #addKnownSourceFromURL

    Adds an online rule source. Newly added sources are automatically enabled.

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    url
    string

    ⚠ NO DESCRIPTION PROVIDED

    source_settings
    (optional) 
    RuleSourceSettings

    ⚠ NO DESCRIPTION PROVIDED

    #addKnownSourceFromFile

    Adds an local rule source. Newly added sources are automatically enabled.

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    file
    string

    ⚠ NO DESCRIPTION PROVIDED

    source_settings
    (optional) 
    RuleSourceSettings

    ⚠ NO DESCRIPTION PROVIDED

    #setKnownSourceSettings

    Changes the settings used when parsing the rules

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    source_id
    integer

    ⚠ NO DESCRIPTION PROVIDED

    source_settings
    RuleSourceSettings

    ⚠ NO DESCRIPTION PROVIDED

    #enableSource

    Enables and loads a known rule source

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    source_id
    integer

    ⚠ NO DESCRIPTION PROVIDED

    #disableSource

    Disables and unloads a known rule source

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    source_id
    integer

    ⚠ NO DESCRIPTION PROVIDED

    #fetchSourceNow

    Forces fetching of a loaded rule source. Does nothing if a fetch is already in progress

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    source_id
    integer

    ⚠ NO DESCRIPTION PROVIDED

    #deleteKnownSource

    Remove a known rule source. The source will be disabled before removal.

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    source_id
    integer

    ⚠ NO DESCRIPTION PROVIDED

    #resetPresetSources

    Re-adds all preset sources that were removed by the user.

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    #getRuleSource

    Gets detailed information about a known rule source

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    source_id
    integer

    ⚠ NO DESCRIPTION PROVIDED

    #getRuleSources

    Gets detailed information about all known rule sources. Loaded sources will have extra information.

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    #setActiveExceptionsList

    Sets whether a rule group should use a list of exempted domains or a list of domains to which it applies.

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    state
    ExceptionList

    ⚠ NO DESCRIPTION PROVIDED

    #getActiveExceptionsList

    Checks whether a rule group is using a list of exempted domains or a list of domains to which it applies

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    #addExceptionForDomain

    Adds an item to the exception list

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    exception_list
    ExceptionList

    ⚠ NO DESCRIPTION PROVIDED

    domain
    string

    ⚠ NO DESCRIPTION PROVIDED

    #removeExceptionForDomain

    Removes an item from the exception list

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    exception_list
    ExceptionList

    ⚠ NO DESCRIPTION PROVIDED

    domain
    string

    ⚠ NO DESCRIPTION PROVIDED

    #removeAllExceptions

    Removes all domains from the exception list

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    exception_list
    ExceptionList

    ⚠ NO DESCRIPTION PROVIDED

    #getExceptions

    Retrieves all domains from the exeption list

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    exception_list
    ExceptionList

    ⚠ NO DESCRIPTION PROVIDED

    #getAllExceptionLists

    Retrieves all the exception lists

    #getBlockedUrlsInfo

    Retrieves information about which URLs have been blocked from loading in a given tab

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    tab_ids

    A list of tabs for which to retrieve blocked urls information.

    Array of:

    • integer

    #getBlockedCounters

    Retrieves the amount of requests blocked since the last time the counters got reset.

    #clearBlockedCounters

    Resets the counters used for getBlockedCounters

    #isExemptOfFiltering

    Returns whether a page URL will be exempt from filtering by a given rule group, based on the active exception list.

    Parameters:

    rule_group
    RuleGroup

    ⚠ NO DESCRIPTION PROVIDED

    url
    string

    ⚠ NO DESCRIPTION PROVIDED

    #getAdAttributionDomain

    Gets the eTLD+1 for which ad attribution is currently active on the given tabs, if any.

    Parameters:

    tab_ids

    A list of tabs for which to retrieve the ad attribution stats.

    Array of:

    • integer

    #getAdAttributionAllowedTrackers

    Gets the allowed ad attribution trackers for the given tabs, if any.

    Parameters:

    tab_ids

    A list of tabs for which to retrieve allowed ad attribution trackers.

    Array of:

    • integer