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 level we block all cryptominers and fingerprinters. This will be explained more in debt 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)[https://github.com/mozilla-services/shavar-prod-lists] on a specific hash to get the version 107 files. This will later be automated for us so the files are automatically updated by a GitHub action generated PR. The GitHub action will get the right files from the (Shavar creation repository)[https://github.com/mozilla-services/shavar-list-creation]. The only thing that matters for the sake of this wiki page is that we get the Shavar files a certain way. Once we have the files, we launch the content blocker generator 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.
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.