Firefox Stub Attribution¶
Stub Attribution is a process that enables the construction and transmission of marketing attribution code on www.mozilla.org. When a user visits a mozilla.org download page, the website constructs an attribution code, which is then passed to download.mozilla.org via a URL parameter. This attribution code is then passed to the Windows stub installer, where it finally gets passed to Firefox for use in Telemetry. This attribution funnel enables Mozilla to better understand how different marketing campaigns effect overall retention in Firefox.
How does it work in bedrock?¶
The base template in bedrock contains a stub attribution script that runs on every page of the website. The script only runs on Windows (since the stub installer is a Windows feature) and if cookies are enabled. The script also respects Do Not Track, so it will not run if the user agent has this flag set.
The stub attribution script looks for utm_*
params on the page URL as well as the
referrer, and then creates a hash of that data by passing it to an authentication
service in bedrock. This hash is then accompanied by a signed, encrypted signature
to prove that the data came from a trusted source. Both pieces of authenticated
data are then stored in a cookie.
Once the user reaches the download page, bedrock then checks if the cookie exists, and if so appends the authenticated data to the download URL. The rest of the process is handled by the download service and stub installer.
Local testing¶
For stub attribution to work locally or on a demo instance, a value for the HMAC key that is used to sign the attribution code must be set via an environment variable e.g.
STUB_ATTRIBUTION_HMAC_KEY='thedude'
Note
This value can be anything if all you need to do is test the bedrock functionality. It only needs to match the value used to verify data passed to the stub installer for full end-to-end testing via Telemetry.
Measuring campaigns and experiments¶
Stub Attribution was originally designed for measuring the effectiveness of marketing
campaigns where the top of the funnel was outside the remit of www.mozilla.org. For
these types of campaigns, stub attribution requires zero configuration. It just works
(as configured in /media/js/base/stub-attribution.js
) in the background and passes
along any attribution data that exists.
More recently, the ability to measure the effectiveness of experiments was also added
as a feature. This is achieved by adding optional experiment
and variation
parameters to a page URL. Additionally, these values can also be set via JavaScript
using:
Mozilla.StubAttribution.experimentName = 'experiment-name';
Mozilla.StubAttribution.experimentVariation = 'v1';
Note
When setting a experiment parameters using JavaScript like in the example above,
it must be done prior to calling Mozilla.StubAttribution.init()
.
Return to addons.mozilla.org (RTAMO)¶
Return to AMO (RTAMO) is a Firefox feature whereby a first-time installation onboarding
flow is initiated, that redirects a user to install the extension they have chosen whilst
browsing AMO using a different browser. RTAMO works by leveraging the existing stub
attribution flow, and checking for specific utm_
parameters that were passed if the
referrer is from AMO.
Specifically, the RTAMO feature looks for a utm_content
parameter that starts with rta:
,
followed by an ID specific to an extension. For example: utm_content=rta:dUJsb2NrMEByYXltb25kaGlsbC5uZXQ
.
The stub attribution code in bedrock also checks the referrer before passing this on, to
make sure the links originate from AMO. If RTAMO data comes from a domain other than AMO, then the
attribution data is dropped.
RTAMO initially worked for only a limited subset of addons recommended by Mozilla. This functionality was recently expanded by the AMO team to cover all publically listed addons, under a project called Extended RTAMO (ERTAMO).