Enhanced Tracking Protection (ETP)
In Firefox for iOS, we have content blocking to help reduce ads and help stop advertisers from tracking browsing activity. In the application, this feature is called Enhanced tracking protection or ETP. There’s different types of trackers that are blocked with this content blocking feature (social trackers, cross-site trackers, cryptominers, fingerprint trackers). How we know which trackers to block is by using lists that we get from a service called Shavar. Since we're using WebKit in Firefox for iOS, we format those files in a certain way so WebKit can block content. This document aims to clarify what is ETP, how we format the files to enable this feature, how we use them in code and what WebKit expects from us.
There's more than one way to access the ETP settings in the application. One way is by navigating to a website and clicking on the lock icon in the URL bar.
This will give you a menu to discover this specific site tracking protection. It will tell you whether the connection to the site is secure, and if ETP is on for this website.
From there, you can open the Protection Settings where you can select either the Standard protection level or the Strict protection level. You can also access the Protection Settings under settings from the hamburger menu.
Standard mode is what is selected by default. The difference between the two is mostly that we third-party block cookies in standard mode for social, advertisers and analytics trackers but we block all for those same trackers in strict mode. In both protection levels we block all cryptominers and fingerprinters. This will be explained more in depth later.
Here’s how the process currently work to get the block lists generated so Webkit knows what to block. Remember, when you first setup the Firefox for iOS repository, you must run the sh bootstrap.sh script. This script also starts the content blocking generation through the content_blocker_update.sh script.
Note that the script is as of January 4th 2023 in an intermediary state since we're in the process of automating the file generation. As of now we clone the Shavar repository on a specific hash to get the version 107 files. This needs to be updated to be automated, a solution is currently being investigate on what this would look like. The current script gets the version 107 files from the Shavar creation repository. Once we have the files, we launch the content blocker generator script that will generate the WebKit format tracker files for us.
The content blocker generator takes as an input the following Shavar files:
- ads-track-digest256.json
- analytics-track-digest256.json
- base-cryptomining-track-digest256.json
- base-fingerprinting-track-digest256.json
- content-track-digest256.json
- social-track-digest256.json
- disconnect-entitylist.json
And currently outputs the following files:
- disconnect-block-advertising.json
- disconnect-block-analytics.json
- disconnect-block-cookies-advertising.json
- disconnect-block-cookies-analytics.json
- disconnect-block-cookies-content.json
- disconnect-block-cookies-social.json
- disconnect-block-cryptomining.json
- disconnect-block-fingerprinting.json
- disconnect-block-social.json
Before moving further, you should get familiar with the content blocking documentation from WebKit. You can focus on what are the triggers and actions of content blockers (we don't particularly care about creating an extension in our case).
We always specify load-type and specify unless-domain in most tracker cases. To understand what this does, here's an example:
{"action":{"type":"block-cookies"},"trigger":{"url-filter":"^https?://([^/]+\\.)?adnetik\\.com","load-type":["third-party"],"unless-domain":["*wtp101.com"]}},
In this case, we will block cookies for the wtp101.com third-party resource unless we're on the adnetik.com website. In other words, unless-domain is a way of whitelisting certain resources when navigating on a specific domain.
We either block or block-cookies depending on the tracker category and if we're in standard or strict protection level. The names of the generated files indicate what is the action used in that specific file. Here's how we use them in standard and strict mode.
| File | Mode |
|---|---|
| disconnect-block-advertising.json | Strict |
| disconnect-block-analytics.json | Strict |
| disconnect-block-cookies-advertising.json | Standard |
| disconnect-block-cookies-analytics.json | Standard |
| disconnect-block-cookies-content.json | Not used |
| disconnect-block-cookies-social.json | Standard |
| disconnect-block-cryptomining.json | Standard & Strict |
| disconnect-block-fingerprinting.json | Standard & Strict |
| disconnect-block-social.json | Strict |
The disconnect-block-cookies-content.json list is unused in the app itself, as in the past it was found to be too aggressive. It is still generated since Focus will use it. If Focus stops using it then we could stop generating that file.
The different files represents the different tracker categories blocked by the application. For example, the social-track-digest256.json is a list of the different social trackers. The one file that is formatted differently is the disconnect-entitylist.json. The entity list represents a list of the different entities we are interested in for content blocking. Each entity (you can probably refer to this as company), has different resources and properties. The documentation on the Shavar repository mentions this about properties and resources:
The Entity list is used to allow third-party subresources that are wholly owned by the same company that owns the top-level website that the user is visiting. For example, if abcd.com owns efgh.com and efgh.com is on the blocklist, it will not be blocked on abcd.com. Instead, efgh.com will be treated as first party on abcd.com, since the same company owns both. But since efgh.com is on the blocklist it will be blocked on other third-party domains that are not all owned by the same parent company.
In other words, each resources owned by this company should be whitelisted when visiting this entity properties.
The content blocker generator has a few steps to be able to generate the file:
- The file manager first make sure the output folder is created
- The parser ingest and prepare the entity list so we can whitelist (or create
unless-domain) properly for each trackers in the different file categories. - It generates the block lists and block cookies lists using the different Shavar files.
The content blocker WebKit files is input into WebKit using the ContentBlocker class.
Users can manually whitelist certain website by setting tracking protection to off. A white dot then appears on the lock in the URL bar. Each time the tab URL changes after web content is loaded on the page, we notify the content blocker so its status can be correctly shown beside the URL bar (with the lock icon).
The stats are used to determine the tracking protection status.