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

Details

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 https://fxos.telemetry.mozilla.org/submit/telemetry, 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

POST https://fxos.telemetry.mozilla.org/submit/telemetry/e426da9f-2a29-4e09-895b-c883903956cb/ftu/FirefoxOS/31.0a1/default/20140325104133

{
  "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": "2.0.0.0-prerelease",
  "deviceinfo.product_model": "GP-KEON",
  "deviceinfo.software": "Boot2Gecko 2.0.0.0-prerelease",
  "deviceinfo.update_channel": "default",
  "devicePixelRatio": 1,
  "screenWidth": 320,
  "screenHeight": 480,
  "ver": 2
}

Glossary

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.

Questions:

• There are two similar fields: os (GAIA version, "2.0.0.0") and software (GAIA distribution, "Boot2Gecko 2.0.0.0"). 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 "1.3.0.0-prerelease". 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 build.sh 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. https://dataviz.mozilla.org/views/ADI_Ping_1_3/HistoricalADITrend#2
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.

Links

Metrics Main Page