TrackingObserver: A Browser-Based
Web Tracking Detection Platform

Developing for TrackingObserver

TrackingObserver is a platform that exposes APIs for web tracking detection, blocking, and measurement. You can develop Chrome extensions that call TrackingObserver's APIs using cross-extension message passing. We provide several sample add-ons to TrackingObserver on the download page. This page describes how to develop for TrackingObserver. If you're not familiar with Chrome extension development in general, we recommend you start here.

If you develop an interesting add-on, we'd love to hear about it!

Example Add-Ons

You can find the source code for our demo add-ons on GitHub here.

Communicating with TrackingObserver

To communicate with another Chrome extension, you need to know its extension id. If you installed TrackingObserver from the Chrome Web Store, its extension id is obheeflpdipmaefcoefhimnaihmhpkao.

However, if you installed TrackingObserver from its source code (as an unpacked extension), its extension id will be different. You can find it in your list of installed extensions (Chrome Settings > Tools > Extensions).

Once you know TrackingObserver's extension id, you can call its APIs from your add-on as follows:

var to_id = "<TrackingObserver's id here>";

chrome.runtime.sendMessage(to_id,
    {type : '<API name here>',
     <other possible arguments here>},
     function(response) {
        // do something with the response, if applicable
    }
);

Tracking Categories

TrackingObserver classifies trackers according to the tracking taxonomy described on the overview page. It uses the following single-character identifiers for each category. Note that a single tracker may exhibit behavior in multiple categories, and that it may exhibit different behavior on different pages or across different loads of the same page.

• A: Analytics tracking (within-site)
• B: Vanilla tracking (cross-site)
• C: Forced tracking (cross-site)
• D: Referred tracking (cross-site)
• E: Personal tracking (cross-site)
• F: Referred analytics tracking (within-site).

Note that for referral-based tracking (categories D and F), TrackingObserver will log the tracking domain associated with the referring domain. For example, if adnetwork.com refers to ads.com, then TrackingObserver will log the tracking domain as ads.com-referredby-adnetwork.com. In your add-on, you may wish to remove the -referredby-x portion of logged tracking domains before further processing data provided by TrackingObserver (e.g., via the getTrackers() API described below).

TrackingObserver's APIs

TrackingObserver exposes the following APIs to add-ons:

Setup

registerAddon()

• Description: Registers your add-on to be known to TrackingObserver.
• Arguments: name, link
• Result: Returns nothing. TrackingObserver will put <a href=link>name</a> into its popup. Also, it will send you a message with type "trackingNotification" and argument tabId whenever it logs tracking on a tab.
• Example use: Tab Visualization add-on

Measurement

browseAutomatically()

• Description: Drives the browser to browse automatically to run tracking measurements.
• Arguments: urls, loadtime, visits
• Result: Returns error or success response. Browses automatically through lists of urls, letting each load for loadtime seconds, and visiting an additional visits number of links mined from each url in the original list.
• Example use: Measurement Tool add-on

Data

getTrackers()

• Description: Get info about all trackers that have been logged.
• Arguments: none
• Result: Returns a map of tracker domain --> object: {domain, categoryList, trackedSites}.
• Example use: Graph Visualization add-on

getTrackersOnCurrentTab()

• Description: Get trackers that were logged on the most recent load of the active tab.
• Arguments: none
• Result: Return a map of tracker domain -> categories (list of strings).
• Example use: Tab Visualization add-on

getTrackersBySite()

• Description: Get trackers indexed by site on which they were logged.
• Arguments: none
• Result: Returns a map of site domain --> map of tracker domain --> categories (list of strings).
• Example use: Raw Data Display add-on

Blocking

blockTrackerDomain()

• Description: Block trackers from this domain.
• Arguments: domain
• Result: Returns nothing. Causes TrackingObserver to start blocking third-party requests to this domain.
• Example use: Tab Visualization Add-On

unblockTrackerDomain()

• Description: Unblock trackers from this domain.
• Arguments: domain
• Result: Returns nothing. Causes TrackingObserver to stop blocking third-party requests to this domain.
• Example use: Tab Visualization Add-On

trackerDomainBlocked()

• Description: Find out if TrackingObserver is currently blocking third-party requests to the specified domain.
• Arguments: domain
• Result: Returns true if the tracker is blocked and false otherwise.
• Example use: Tab Visualization Add-On

getBlockedDomains()

• Description: Find out which domains are currently on the block list.
• Arguments: none
• Result: Returns a list of blocked domains.
• Example use:

blockCategory()

• Description: Block all trackers in this category.
• Arguments: category (single-character identifier)
• Result: Returns nothing. Causes TrackingObserver to start blocking third-party requests to domains that exhibit tracking behavior in this category.
• Example use: Blocking Dashboard add-on

unblockCategory()

• Description: Unblock all trackers in this category.
• Arguments: category (single-character identifier)
• Result: Returns nothing. Causes TrackingObserver to start blocking third-party requests to domains that exhibit tracking behavior in this category.
• Example use: Blocking Dashboard add-on

getBlockedCategories()

• Description: Find out which categories are currently on the block list.
• Arguments: none
• Result: Returns a list of blocked categories.
• Example use: Blocking Dashboard add-on

removeCookiesForTrackerDomain()

• Description: Start removing cookies from requests to this domain.
• Arguments: domain
• Result: Returns nothing. Causes TrackingObserver to start removing cookies from third-party requests to this domain.
• Example use: none

stopRemoveCookiesForTrackerDomain()

• Description: Stop removing cookies from requests to this domain.
• Arguments: none
• Result: Returns nothing. Causes TrackingObserver to stop removing cookies from third-party requests to this domain.
• Example use: none

getRemoveCookieDomains()

• Description: Find out which domains are on the cookie-removal list.
• Arguments: none
• Result: Returns a list of domains to which third-party requests have cookies removed.
• Example use: none