Last updated 2018-08-20
Compiled by Leif Oines loines at mozilla dot com
This file is WIP. In the future it will be a combined resource detailing data collection, metrics definitions, pipeline information, etc. For now it mainly documents metrics parameters (e.g. utm_*) that reliers pass to Firefox Accounts servers.
You should start at this page for more general information on how to integrate with Firefox Accounts.
Self-Hosted Email Forms and Metrics Tracking (AKA the "FxA email-first flow")
As of July 2018, reliers must do either one of the following when integrating with Firefox Accounts:
- Self-host the first step in the FxA authentication flow themselves (e.g. the form capturing the user's email)
- Send users to a FxA-hosted form at https://accounts.firefox.com/.
This means that pages that host an iFrame containing an FxA hosted form are no longer an option moving forward due to performance and security precautions.
In the case when the email entry form is self hosted, we ask that you do the following so that we can properly track top-of-funnel metrics (such as volume of email form views) associated with the page that hosts your FxA form:
- When the page that hosts your FxA form loads, have it make an XHR call to
https://accounts.firefox.com/metrics-flow. The domain name of the request should match the FxA page that is being redirected to (e.g. https://accounts.firefox.com). You can use
fetchto get this info.
- Include the following query parameters in the above request (see chart below for descriptions):
- An example:
- The response to metrics-flow will be a JSON object that contains the fields
flowBeginTime. These values will need to be propagated to FxA as query parameters, which can be done using hidden form fields with the names
flow_begin_time. You can see an example of how the about:welcome page does this by looking here.
By following these instructions you provide both of our teams with data needed to monitor the health of your page.
Descriptions of Metrics-Related Query Parameters
If you are a developer, please read the following before checking the chart below. The values that are passed in the parameters below are subject to validation via regular expressions. If the parameter values do not conform to their associated regexes in this file then all metrics events associated with the nonconforming parameters will fail to be logged!
|Name||Description||Example Values||Validation regex||Amplitude Chart Example|
|The specific page or browser UI element containing the first step of the FxA sign-in/sign-up process (e.g., enter email form)||^[\w.:-]+$||Firstrun form views|
|Identifier for the experiment the user is part of (if any)||^[\w.:-]+$|
|Identifier for the experiment variation the user is part of (if any)||^[\w.:-]+$|
|For self-hosted forms only (see above) the type of form that the user submits to begin the FxA flow||either: ||NA|
|Unambiguous identifier of site or browser UI element that linked to the page containing the beginning of the FxA sign-in/sign-up process||^[\w/.%-]+$||Registration form views segmented by utm_source|
|More general label for the campaign that the site is part of||^[\w/.%-]+$||TBD|
|Used to track the name of an A-B test||^[\w/.%-]+$||TBD|
|Used to track the cohort or variation in an A-B test||^[\w/.%-]+$||TBD|
|What type of link was used to direct to the page, if it came through a marketing campaign||^[\w/.%-]+$||TBD|
|Not relevant to metrics, but this is required to be set to one of ||^[0-9a-z_-]+$/||NA|
Note these may not be all the parameters you need to pass for your integration to work! A more exhaustive but less detailed list can be found here. What is documented above are only the parameters that are relevant for metrics analysis in (e.g.) amplitude.
You must have access to the mozilla amplitude account to see the example charts. If you are a Mozilla employee, please contact Leif for information on gaining access to amplitude.
You can use the amplitude graphs linked in the chart as templates for tracking the login and registration performance of your own page. Simply change the value of
utm_source, etc as appropriate. Contact Leif if you need any help.
utm_term: note that the current usage of this parameter is different from what is typical. In most scenarios, it is used to track the search terms that led the users to the page. If you would like to use the parameter in this way, please inform the Firefox Accounts team.