How Ad Attribution is implemented

This Help page includes information currently only applicable to the Snapshot version of the browser.

In order to improve the result of ad monetization for sites where a user has decided to enable ads, Vivaldi has now included support for ad attribution. You can read more about why this change was implemented here.

This page mainly aims to describe how Ad Attribution is implemented and explain the choices that led to this implementation. The goal is to be fully transparent about what may be allowed through and when.

As with the rest of the ad blocker code, this implementation is fully available as part of our released source code bundles. This allows you to fully verify that our implementation is as described here and in other articles.

Allow Ad Attribution rules

The main challenge with ad monetization is that many ad providers rely on known trackers in order to prevent click fraud and ensure that conversion has occurred before paying out. The only solution to this is unfortunately to allow such trackers to load, regardless of what our tracker blocking lists say. However, we also want to ensure that these trackers are not loaded as part of general browsing.

In order to satisfy all these requirements, I have extended the normal ad blocker rules format. This is the same format used by all popular ad-blockers and rules lists. The extended format consists of three new options that will be detailed below.

This implementation was chosen as it allows us to reuse most of the ad-blocker functionality to effectively accomplish the goal of ad attribution while also allowing us to use the automatic update mechanism coming with ad blocker rules lists. This ensures that we can promptly fix any mistake.

How it works

Ensuring that ad attribution works is a complex task that takes multiple steps to accomplish. In general, the focus is on the site which uses ads for support, however most of the work is done after clicking on a given ad. As part of the implementation, we go through the following states.

1. Navigating to a site which the user wants to support.

When this occurs, the ad attribution implementation records that it should be looking for ad clicks. We say that it is primed.

Ad attribution is normally primed on any site where the ad blocker is disabled, regardless of the state of the tracker blocker. Priming ad attribution means we will check whether the next navigation is an ad click. It has no other effect.

In order to be able to support ad attribution for our partner search engines even when ad blocking is enabled for all sites, we introduced the attribute-ads rule option:

@@||partner-site.example.com/page-i-want-to-Support$attribute-ads

This causes ad attribution to be primed on the matching page, regardless of the ad blocker status. In practice, we would also add a document option (identical to the document allow rules supported by AdBlockPlus), in order to allow the partner site to show ads:

@@||partner-site.example.com/page-i-want-to-Support$attribute-ads,document

2. Matching an ad when Ad Attribution is primed.

When this occurs, the ad attribution implementation will examine the URL being loaded as well as the URLs of any redirections which occurs as part of loading.

If none of those URLs matches a known ad, then ad attribution remains disabled. It may be primed again if the site where the user ends up is one the user wants to support.

If the URL matches a known ad, then ad attribution moves to the next stage and the process continues.

The ad-query-trigger option is used to indicate that a rule should be used to match ad URLs:

||advertiser.example.com/ad-URL$ad-query-trigger=&click-id-param=|&other-click-id-param=

The ad-query-trigger option takes a value that is composed of several query string fragments, separated by |.

Once a document matching the pattern for an ad-query-trigger rule was reached, directly or via redirect, further redirections will be examined. For those redirections, the query string of the URL will be examined. If it contains any of the strings provided as value to the option, ad attribution will be fully enabled and the origin of the matching URL will be stored as the ad landing origin for this tab.

The ad-query-trigger option requires a pattern that provides a domain name in the ad URL pattern. This means, the pattern should be host-anchored and the domain should be followed by ^,/ or ?

Once ad attribution is enabled for a specific tab and origin, that state is preserved so long as the tab navigates within this same origin. Navigating to a different origin will cause ad attribution to be disabled, but it’s state will be preserved for a half hour. Further navigations within the deadline extend it to a half hour. If the deadline passes, further navigations outside the original origin clear the state fully. Navigating back to the landing origin will re-enable ad attribution.

The ad attribution state is normally confined to the tab where it was enabled. However, a same-origin navigation to a new tab from a tab where it is enabled will preserve its state.

Ad attribution also always gets disabled seven days after being triggered.

3.Matching trackers when ad attribution is enabled

When ad attribution is enabled, it examines resources loaded on pages whose origin match the landing origin. In order to indicate which resources should be allowed for ad attribution, rules with the ad-attribution-tracker option are used.

@@||advertiser.example.org/track-click$ad-attribution-tracker=advertiser.example.com/&click-id-param=|advertiser.example.net/&ad_id=

The body of this rule matches the url of the resource itself, while the value of the ad-attribution-tracker option provides the context in which it should be allowed. The value of this option consists of a pairs of domain/query-fragment separated by |. The domain part is matched against the domain of the ad that was clicked (the ad itself, not its landing origin). The query-fragment is matched against the query fragment used to enable ad attribution. A pair matches if both components are a match. This rule matches if the resource url matches and any of the domain/query-fragment pair is a match. When a tracker is allowed this way, it bypasses blocking both in the ad blocker and the tracker blocker.

These rules are currently only available in the “Allow Ads from our Partners” list that is provided by Vivaldi. This is to avoid situations where they may be employed in malicious rules lists. You can examine our list to learn of which partner sites have ad attribution enabled and which trackers are allowed as a result here.