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

    • #PresetKind

    ENUM

    Which rough category a given preset list falls in

  • ads
  • trackers
  • partners
  • annoyances
  • cookie_notices
  • other
  • regional

    • #DownloadResult

    ENUM

    The result of downloading an online rule source.

  • success: Download completed successfully.
  • download_failed: Failed to download using the provided URL.
  • replace_failed: Failed to move the downloaded file to its final path, replacing the previous one.
  • unknown: No download has been attempted yet, or the rule source uses a local file and doesn't need download.

    • #ReadResult

    ENUM

    The result of a reading a downloaded or local rule source.

  • success: Fetch completed successfully.
  • 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 reading has been attempted yet.

    • #ParsedMetadata

    Information extracted by the parser in addition to the rules themselves. These include information about the number of rules parsed and metadata from the adblock file comments.

    Properties:

    homepage
    (optional) 
    string

    URL pointing to the original website for this list.

    title
    (optional) 
    string

    List name.

    expires
    (optional) 
    integer

    How often the list is refreshed, in hours.

    license
    (optional) 
    string

    URL pointing to licensing info for the list.

    version
    (optional) 
    integer

    Version number of the list.

    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.

    #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_location
    string

    Either the url or the path to the file that was used to create this ource.

    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.

    parsed_metadata
    ParsedMetadata

    ⚠ 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_download_result
    DownloadResult

    The result of the last fetch attempt

    last_read_result
    ReadResult

    The result of the last fetch attempt

    preset_id
    string

    ⚠ NO DESCRIPTION PROVIDED

    preset_kind
    (optional) 
    PresetKind

    ⚠ 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

    ads_blocked
    integer

    ⚠ NO DESCRIPTION PROVIDED

    trackers_blocked
    integer

    ⚠ NO DESCRIPTION PROVIDED

    #AdBlockingStatsData

    Statistics for trackers and ads blocked.

    Properties:

    reporting_start
    number

    The time at which the counters have been initialized or reset.

    total_ads_blocked
    integer

    Number of ads blocked.

    total_trackers_blocked
    integer

    Number of trackers blocked.

    blocked_domains

    Counter with domains blocked.

    Array of:

    • BlockedCounter
    blocked_for_origin

    Counter with a domain that was an origin for blocking.

    Array of:

    • BlockedCounter

    #BlockedUrlsInfo

    Information about a blocked URL

    Properties:

    url
    string

    ⚠ NO DESCRIPTION PROVIDED

    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_urls_info

    blocked urls.

    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

    #URLPartnerInfo

    Information about the URL given - Is it a partner? What name does it have?

    Properties:

    status
    boolean

    ⚠ NO DESCRIPTION PROVIDED

    name
    string

    Name of the partner, or empty if unknown (in which case a generic message should be used)

    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 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

    #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

    #getAdBlockingStats

    Retrieves the stats for ads and trackers blocked.

    Parameters:

    number_of_days
    integer

    Number of days to return statistic data. 0 or less returns all data.

    #clearAdBlockingStats

    Resets ad blocking stats.

    #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

    #isExemptByPartnerURL

    Returns whether a page URL will be exempt from filtering by a partnership exception.

    Parameters:

    url
    string

    ⚠ NO DESCRIPTION PROVIDED

    tab_id
    integer

    ⚠ 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