Firefox OS/Metrics/activationping

From MozillaWiki
Jump to: navigation, search

FTU ping

Design of Activation Ping

  1. Activation Ping is triggered through the first-time use experience / activation.
  2. Never pings again once it is successful (unless the phone's "userdata" partition is formatted through the recovery partition, but this is not a case we support generally, it means wiping all of the user's data)
  3. Can also be disabled, but requires extra work on top of disabling app updates or removing the Firefox marketplace app


When a device is first activated, The FTU ping service sends a simple one-off HTTP request to our telemetry server. The HTTP request contains a JSON payload with some high level information about the device and network, but no unique hardware identifiers. A randomly generated pingID is sent to help with filtering on the server side, but this ID is discarded by the server once filtering has occurred (generally after 24 hours).

Currently, the logic for the FTU ping is broken down like this:

  1. Unless the setting ftu.pingEnabled is explicitly set to false, start the FTU ping service. If the setting is missing, or any other value, then the ping service is enabled.
  2. Lazily get or create a randomly generated pingID, which is used for server side filtering. This pingID is only generated once per device, and is discarded on the server side.
  3. Record the time the ping service started, to track the delta of time to a successful ping.
  4. Pull all relevant ping payload settings asynchronously.
  5. Create an interval timer to attempt a ping once an hour. This is configurable with ftu.pingTryInterval.
    1. Check for availability of voice network information. If none is available, try again on the next interval. If this fails 24 times, then continue trying the ping until is successful. This is configurable in the setting ftu.pingMaxNetworkFails.
    2. Send an HTTP request to FTU_PING_URL/PING_ID/ftu/FirefoxOS/VERSION/UPDATE_CHANNEL/BUILD_ID. By default, the ping URL is, and is configurable in the ftu.pingURL setting, or via make with FTU_PING_URL.
      1. If the HTTP request succeeds, set ftu.pingEnabled to false, and disable the interval timer. Otherwise, try again on the next interval.

Example payload and URL


  "activationTime": 1398300000000,
  "pingTime": 1398300000000,
  "locale": "hu",
  "network": {
    "mcc": "216",
    "mnc": "70",
    "operator": "vodafone HU vodafone"
  "icc": {
    "spn": "vodafone",
    "mcc": "216",
    "mnc": "70"
  "info": {
    "appUpdateChannel": "default",
    "reason": "ftu",
    "appVersion": "31.0a1",
    "geoCountry": "HU",
    "appName": "FirefoxOS",
    "appBuildID": "20140423185429"
  "deviceinfo.firmware_revision": "",
  "deviceinfo.hardware": "qcom",
  "deviceinfo.os": "",
  "deviceinfo.product_model": "GP-KEON",
  "": "Boot2Gecko",
  "deviceinfo.update_channel": "default",
  "devicePixelRatio": 1,
  "screenWidth": 320,
  "screenHeight": 480,
  "ver": 2


activationTime Timestamp indicating when the device was activated (user completes first-run experience).
pingTime Timestamp indicating when the FTU ping was sent. The ping is sent as soon as possible after activation, although it may be delayed if no network is available.
locale Platform localization.
network Country and network information retrieved from the voice network connection at the time the ping is sent. Values should be null if no voice network is available. May be different from the SIM information if, eg., device is activated while roaming on another network.
icc Country and network information retrieved from the SIM card at the time the ping is sent. Values should be null if no SIM is present.
mcc Mobile country code.
mnc Mobile network code (identifies operator).
operator Network operator name.
spn SIM service provider name.
info Fields added server-side, read from submission URL.
appUpdateChannel Copied from deviceinfo.update_channel.
appVersion Copied from deviceinfo.platform_version.
appName Name of app submitting ping (set to FirefoxOS).
appBuildID Copied from deviceinfo.platform_build_id.
geoCountry Country from which the ping was sent. Added server-side using GeoIP lookup.
reason A code identifying the type of ping. FTU is currently the only ping being sent.
deviceinfo Fields read off the device.
deviceinfo.hardware Chipset manufacturer.
deviceinfo.os Gaia version.
deviceinfo.product_model Device model name.
deviceinfo.platform_version Gecko version.
deviceinfo.platform_build_id Gecko build ID. Generated from a timestamp - first 8 digits give date. Name of Gaia distribution.
screenWidth Width of the screen in pixels.
screenHeight Height of the screen in pixels.
ver Payload format version. Gets bumped when fields get added or changed.

Standardization of Device info

Firefox OS has fields in device software which identify the sw and hw versions. These fields are modifiable by partners. The issue for us is that, without knowing what values to expect from each partner, it is difficult to map FTU ping data to (partner/OEM/market) segments in order to assess volume. We also see cases where the same device may get assigned slightly different product_model values by different partners, for example, requiring a manually-curated deduplication phase in our data processing. Ideally, this issue would be fixed at the source, by standardizing the field values.

The proposal is to bring consistency to the fields.

Field Explanation Partner modifiable? Format Share with Moz for Certification? Comments
deviceinfo.os GAIA version. Eg: Y. Format needed:"X.Y.Z.W" Y Name of Gaia"Boot2Gecko" Y This field is not adding much value over the existing field "deviceinfo.os".
deviceinfo.product_model String representing "model name". It is part of the system properties (representing a particular HW chipset, PMIC) eg:"GP-KEON", "Cloud FX". Y. String . Y The important thing here is that the same devices use the same string across different partners/markets if we want to be able to group them together when analyzing this data.
deviceinfo.platform_version Gecko version eg: "31.0a1","28.1" N N
deviceinfo.platform_build_id Timestamp of the final "20140423185429". Could be used to filter out test devices Y Y
deviceinfo.hardware "qcom", "sp8810". String representing the hw manufacturer and chipset Y. String. N
deviceinfo.update_channel String representing channel for updates. This is link to webpage for getting updates. historically this was used for "nightly", "stable" etc.

Is this being used by customers? Currently, the examples are"release-zte","release-spreadtrum"

Y N (Y?) Maybe this field should be standardized as well, with identifiers for partner/OEM/country. See below.
deviceinfo.firmware_revision revision of firmware N N Not populated for most devices


  • There are two similar fields: os (GAIA version, "") and software (GAIA distribution, "Boot2Gecko"). Only difference is a string added ahead of the software. What is the reason for needing two fields?
  • There does not seem to be a consistent identifier for 1.3T. Both 1.3 and 1.3T seem to have the same release number "". Why is that?
  • Is update_channel being used? This is link to webpage for getting updates. historically this was used for "nightly", "stable" etc.

Is this being used by customers? Currently, the examples are"release-

    • There don't seem to be consistent identifiers for partner, OEM, and launch country in the FTU payload. Maybe we should include these explicitly, as we generally want to segment according to these variables. It appears that this done in some cases using update_channel (eg. "release-tcl-DT-DE"). Maybe we should formally use update_channel for this, standardizing it and including it in the certification (eg. "<release|prerelease>-<partner>-<oem>-<market>").
  • Otherwise, does update_channel represent something else that would be inconsistent with this scheme?

Here is proposed information that partners have to share with us as part of the certification:

  • "os" in format x.y.z.w.
  • "product_model" for device model name
  • "update_channel"?

Testing tips

Testing the FTU ping can be tedious and time consuming with the default settings. Here's a few things you can do to make it better:

  • When using or make, set FTU_PING_URL to a local IP so you can monitor the http request, i.e: cd gaia; make FTU_PING_URL=... reset-gaia
  • Set DEBUG = true in gaia/apps/system/js/ftu_ping.js to see messages at various stages of the ping lifecycle, and the raw ping data when it is actually sent
  • Change DEFAULT_TRY_INTERVAL in gaia/apps/system/js/ftu_ping.js to something much smaller than 1 hour (i.e. 15 seconds)

High Level Requirements

  1. Product Planning: Need to know the number of devices sold. This will help product decisions be data driven.
  2. User Benefit: knowing the following information will improve security updates and app functionality
    1. Build IDs, Country, Operator, OEM, Version of HW: These are needed for Device Updates and Security patches: When a bug is found, or a security risk is detected, they need to be sent as an update to the particular OEM, Operator.
    2. Screen Height, Width, Pixel density: This is needed for CoreApps development (Gallery, Camera, Dialer, Browser) and 3rd party apps. These apps need to know the screen sizes, resolutions that they would need to support.

Delta to what exists today in Marketplace Ping

  1. Information:
    1. ActivationPing gives the total number of "sold"(activated) FFOS devices, whereas current ADI ping gives the number of devices connected to WiFi on a particular day
      1. Product planning needs the information about devices sold (ActivatioPing). Current ADI ping approximated devices active on a certain day on WiFi. Difference gives us an idea of retention of product, and engagement of user.. This will help us focus on what is causing the dropoff, investigate why certain markets are doing better/worse, and making data-driven investments in improving the retention
    2. Activation Ping has additional information on Build IDs, Country, Operator, OEM, Version of HW, Screen Size, Screen Height, Width, Pixel density. While the previous ADI ping contains the model of device.
  2. Reliability:
    1. Current Ping from 1.3 shows approx 5 devices reporting as of March 24th 2014.
  3. Cost:
    1. From previous versions, Partners removed ADI ping due to cost concern. Activation Ping is sent once in lifetime of device, which should have allay cost concerns.


Metrics Main Page