Bounce Tracking Protection
Bounce Tracking Protection (BTP) is an anti-tracking feature in Gecko which detects bounce trackers (navigational tracking) based on a set of heuristics. As opposed to the cookie purging feature it does not rely on a list of trackers which makes it more webcompat friendly while also covering unknown bounce trackers.
Standardization
The protection is a work item of the PrivacyCG. The implementation in Gecko closely follows the Bounce Tracking Mitigations spec draft.
Mozilla also has a specification position on Bounce Tracking Mitigations.
Behavior
BTP detects bounce trackers by looking at navigation timing. It establishes the concept of an extended navigation which can encompass a chain of short-lived redirects. These short-lived redirects are commonly used by bounce trackers. Any site that appears as an intermediary in such a short-lived redirect gets added to a classification list. Classified bounce trackers have their cookies, site data and cache purged periodically. In order to avoid false positives and purging data that may be important for users, sites which the user directly interacted with in the last 45 days are exempt from being classified or purged.
See Bounce Tracking Mitigations Explainer for a more detailed (albeit chromium-oriented) description of the feature and how trackers are classified.
Deviations from the spec
Comparison with Chromium
Chromium’s implementation starts a redirect chain the same way. In
btm_bounce_detector.cc,
BtmBounceDetector::DidStartNavigation takes the chain start from the tab’s last
committed URL and only consults the navigation’s initiator when the tab has nothing
committed. BtmServiceImpl::HandleRedirects in
btm_service_impl.cc
then skips a redirector whose site equals the chain’s initial or final site, which is
what RecordStatefulBounces does with the initial and final host. A client redirect
is likewise recorded with the tab’s last committed URL as the redirector, never the
navigation’s initiator, and only once the tab has committed something.
Gecko is stricter in one case. Chromium’s fallback is the initiator’s origin as-is, so for a context opened by a cross-site frame it resolves to the frame’s own site and the frame can still name itself. Gecko resolves the opener to its top level document instead.
Purge exceptions
A classified bounce tracker is not purged if its site has one of the following exceptions:
A
trackingprotectionpermission, ortrackingprotection-pbin private browsing. These are set when the user turns off Enhanced Tracking Protection for the site with the toggle in the trust panel.A
cookiepermission withALLOW_ACTION, which is set when the user always allows cookies for the site, for example via the cookie exceptions in preferences. Othercookievalues, such as blocking or allowing for the session only, are not exceptions.cookiepermissions are stored without private browsing isolation, so they currently only exempt sites in normal browsing.A
bounce-tracking-protection-exceptionpermission, which is set by remote interventions, see below.
Exceptions apply to the entire site (eTLD+1): a permission set for
https://www.example.com also exempts example.com and all of its subdomains.
Normal and private browsing are checked separately, using the permissions of the
respective context. A site which is skipped because of an exception is removed
from the bounce tracker candidates. If it bounces again after the exception has
been removed it can be classified and purged again.
Remote interventions
If BTP breaks a website, the site can be exempted from purging remotely,
without shipping a new Firefox release, by setting a
bounce-tracking-protection-exception permission via
remote permissions. Records go into the
remote-permissions Remote Settings collection:
{
"origin": "https://example.com",
"type": "bounce-tracking-protection-exception",
"capability": 1
}
Only ALLOW_ACTION (1) may be set. RemotePermissionService rejects any
other value except UNKNOWN_ACTION (0), which removes the permission, and
BTP only considers ALLOW_ACTION to be an exception. New entries are requested through the
remote permissions process.
Remote permissions are imported as default permissions. They are not written to
the permission database, are mirrored to private browsing, and are not shown in
the permission UI. Firefox does not ship a dump of the remote-permissions
collection, so a new profile only gets the exceptions after its first Remote
Settings sync. The import runs asynchronously during startup and BTP does not
wait for it before purging, so a purge which runs before the import has
finished does not see these exceptions. Changes synced from Remote Settings apply from the next purge
onwards.
Gecko Implementation
Work for the Gecko implementation in tracked under following meta-bug: Bug 1839915 - [meta] Bounce Tracking Protection.
A simplified UML diagram of the BTP implementation in Gecko. Note that some classes and attributes have been omitted for readability. You can use the diagram feature in Searchfox to view the full diagram (example).
classDiagram
class BounceTrackingProtection {
- mBounceTrackingPurgeTimer: nsITimer
- mStorage: BounceTrackingProtectionStorage
}
note for BounceTrackingProtection "Singleton class to manage the feature."
class BounceTrackingAllowList {
<!-- [...] -->
}
class BounceTrackingStateGlobal {
- mUserActivation: nsTHashMap<nsCStringHashKey, PRTime>
- mBounceTrackers: nsTHashMap<nsCStringHashKey, BounceTrackerCandidate>
- mRecentPurges: nsTHashMap<nsCStringHashKey, nsTArray<RefPtr<BounceTrackingPurgeEntry>>>
- mOriginAttributes: OriginAttributes
}
note for BounceTrackingStateGlobal "Manages the global maps for bounce tracker candidates
and user activation for a specific OriginAttributes dict."
class BounceTrackingProtectionStorage {
- mStateGlobal : nsTHashMap<OriginAttributesHashKey, RefPtr<BounceTrackingStateGlobal>>
- mDatabaseFile : nsCOMPtr<nsIFile>
}
class BounceTrackingPurgeEntry {
- mSite: BounceTrackingSite
- mChainRecord: BounceTrackingRecord
}
note for BounceTrackingPurgeEntry "Purge log entry, keeps the bounce chain
which got the site classified."
class BounceTrackingRecord {
- mInitialSite: BounceTrackingSite
- mBounceSites: nsTHashSet<BounceTrackingSiteHashKey>
- mFinalSite: BounceTrackingSite
}
note for BounceTrackingRecord "Encapsulates the per-tab navigation state
during an extended navigation."
class BounceTrackingSite {
- mSiteHost: nsCString
- mOriginAttributes: OriginAttributes
}
note for BounceTrackingSite "A site together with the storage partition it
ran in, or the null site for untracked documents."
class BounceTrackingState {
- mBounceTrackingProtection: BounceTrackingProtection
- mBounceTrackingRecord: BounceTrackingRecord
- mClientBounceDetectionTimeout: nsReadOnlyTimer
- mOriginAttributes: OriginAttributes
}
class BrowsingContextWebProgress {
- mBounceTrackingState: BounceTrackingState
}
class DocumentLoadListener{
<!-- [...] -->
}
note for BrowsingContextWebProgress "Every tab has a web progress
and therefore a BounceTrackingState"
BounceTrackingProtection *-- BounceTrackingProtectionStorage
BounceTrackingState --o BounceTrackingProtection
BounceTrackingState --> BounceTrackingProtection : RecordStatefulBounces() on extended nav end
BounceTrackingState *-- BounceTrackingRecord
BounceTrackingRecord *-- BounceTrackingSite
BounceTrackingPurgeEntry *-- BounceTrackingSite
BounceTrackingStateGlobal *-- BounceTrackingPurgeEntry
BrowsingContextWebProgress *-- BounceTrackingState
BounceTrackingStateGlobal --* BounceTrackingProtectionStorage
BounceTrackingStateGlobal --> BounceTrackingProtectionStorage : Persists state changes in storage.
BounceTrackingProtection --> BounceTrackingStateGlobal : Manages global state
BounceTrackingAllowList --* BounceTrackingProtection
BounceTrackingAllowList --> BounceTrackingProtection : Site purge exceptions from PermissionManager, incl. remote permissions.
BrowsingContextWebProgress --> BounceTrackingState : Navigation signals
DocumentLoadListener --> BounceTrackingState : Navigation signals, OnLoadRetargeted()
Preferences
The feature can be enabled and it’s behavior can be adjusted using the
privacy.bounceTrackingProtection.* prefs. See
StaticPrefList.yaml
for a list of prefs with descriptions.
The main feature pref is privacy.bounceTrackingProtection.mode where 0 is
fully disabled and 1 is fully enabled. See
nsIBounceTrackingProtection.idl
for a full list of options.
Nimbus Integration
A subset of the BTP prefs can be controlled via Nimbus. See definition here: FeatureManifest.yaml.
Logging
BTP has a logger which can be enabled by starting Firefox with the MOZ_LOG
environment variable. Use MOZ_LOG=BounceTrackingProtection:5 for verbose
logging for every navigation and MOZ_LOG=BounceTrackingProtection:3 for more
concise logging focused on classification and purging.
Console Messages
You can check the developer tools console for warning messages which will be logged when a site gets classified. Example:
“bounce-tracking-demo-tracker-server.glitch.me” has been classified as a bounce tracker. If it does not receive user activation within the next 3,600 seconds it will have its state purged.
When a site has recently been purged (since last restart), upon next visit, Firefox will also log a warning to the website console:
The state of “bounce-tracking-demo-tracker-server.glitch.me” was recently purged because it was detected as a bounce tracker.
Testing
When testing sites to ensure they don’t get purged for bounce tracking behavior you can use both logging (as described above) to observe classification and direct calls to the feature via the Browser Toolbox to trigger the purging early.
The snippets in the following section need to be executed in the Browser Toolbox. Note that while the toolbox looks like the regular devtools it’s a special console used to debug Firefox itself rather than websites.
Print the list of classified bounce trackers
To get a list of all currently classified bounce trackers use the following snippet:
await Cc[
"@mozilla.org/bounce-tracking-protection;1"
].getService(Ci.nsIBounceTrackingProtection).testGetUserActivationHosts({})
This prints the list excluding private browsing and tab containers. For those
you need to pass in an OriginAttributes object. See
nsIBounceTrackingProtection
for more documentation.
Sites which have been purged or which receive user interaction are automatically removed from this list.
Note that just because a site is in this list it doesn’t mean that it gets classified. Once classified there is a grace period of 1h in which the site may receive user interaction. If the user interacts with the site in that time window it is removed from the bounce tracker list and exempt from purging for 45 days.
Trigger a purge of all classified trackers:
Before navigating to the site set
privacy.bounceTrackingProtection.bounceTrackingGracePeriodSec to 0 or a low
number. This controls how fast after (classified) bounce a site may be purged.
If you don’t update this pref you need to wait up to 1h for a site to be purged.
Purges normally run every hour. To trigger a purge manually you can use the following snippet:
await Cc[
"@mozilla.org/bounce-tracking-protection;1"
].getService(Ci.nsIBounceTrackingProtection).testRunPurgeBounceTrackers();
The return value will be an array of sites that have been purged. Note that purging applies for the entire domain (eTLD+1).
List recently purged sites
You can obtain a list of recently purged sites (since the last restart) by calling:
await Cc[
"@mozilla.org/bounce-tracking-protection;1"
].getService(Ci.nsIBounceTrackingProtection).testGetRecentlyPurgedTrackers({});
This only shows sites which have been purged in normal browsing. If you want
data from private browsing or containers you need to pass in a non-default
OriginAttributes object, e.g. { privateBrowsingId: 1 }.
There is also hasRecentlyPurgedSite which can be used to check if a specific
site has been recently purged (across all OriginAttributes contexts).
Test Page
https://bounce-tracking-demo.glitch.me/ is a demo page with two links that exhibit bounce tracking behaviour. You can use it combined with the methods above to verify that the mechanism is running.