MozillaWiki - User contributions [en]

Firefox OS/Metrics/App Usage

2014-10-23T17:59:51Z

Marshall law: Added a note about average payload size

=Requirements=
For all system and 3rd party apps, track:
# Total time that each app (by URL) has been actively been used (in the foreground while the screen is on)
# Counts for the number of times an app has been opened, closed, or crashed
# A list of apps that have been uninstalled since the last successful report

=Design=
The App Updates Metrics (AUM) service actively collects usage information by hooking into several system events. The determination of running time of an app looks something like this:

* When an app is opened, or the user switches to the homescreen, AUM marks it as the currently running app, and records the current time
* When the device is locked, the display goes to sleep, or another app is opened, AUM records the delta of the current time with the current app's start time
* When the device is unlocked after the display was sleeping, the current app's start time is reset to the current time so we don't record usage time while the screen was off/locked
* AUM also records installs, uninstalls, and and activity invocations (on activity URLs -- not running time) of apps

When the device is idle and and any of these registered events occur:
* AUM will save the currently collected metrics to async storage
* If the device is also online and a specified interval has passed (default 24 hours), AUM will begin attemping to transmit the stored metrics to the Telemetry server
* If transmission fails, then a separate retry interval (default 1 hour) controls how often AUM will retry transmission until it is successful

=Example Payload and URL=
<code><pre>
POST https://fxos.telemetry.mozilla.org/submit/telemetry/metrics/FirefoxOS/appusage
{
"apps": {
"app://verticalhome.gaiamobile.org/manifest.webapp": {
"activities": {},
"installs": 0,
"invocations": 1,
"uninstalls": 0,
"usageTime": 23
}
},
"deviceID": "j2670k6q",
"deviceinfo": {
"developer.menu.enabled": true,
"deviceinfo.platform_build_id": "20140902135234",
"deviceinfo.platform_version": "34.0a1",
"deviceinfo.update_channel": "unknown"
},
"locale": "en-US",
"screen": {
"devicePixelRatio": 1.5,
"height": 569,
"width": 320
},
"start": 1411567451826,
"stop": 1411577295717
}
</pre></code>

==Glossary==
{|
|-
| <code>apps</code> || Usage for each app in this batch (these are not aggregates), keyed by the app's manifest URL
{|
|-
| <code>installs</code> || The number of app installs
|-
| <code>uninstalls</code> || The number of app uninstalls
|-
| <code>invocations</code> || The number of times the app was started
|-
| <code>usageTime</code> || The total number of seconds the app was used
|-
|}
|-
| <code>deviceID</code> || A randomly generated deviceID to help server side de-duplication. This is separate from any other ID in the system, including the FTU activation ping
|-
| <code>deviceinfo</code> ||
{|
|-
| <code>developer.menu.enabled</code> || Whether or not this is a 'production' build
|-
| <code>deviceinfo.platform_build_id</code> || The timestamp that gecko was built
|-
| <code>deviceinfo.platform_version</code> || The version string of gecko
|-
| <code>deviceinfo.update_channel</code> || Update channel used for FxOS OTA updates
|-
|}
|-
| <code>locale</code> || Platform locale string, i.e. 'en-US'
|-
| <code>screen</code> ||
{|
|-
| <code>devicePixelRatio</code> || ratio of physical pixels to virtual pixels on the device
|-
| <code>width</code> || screen width in CSS pixels
|-
| <code>height</code> || screen height in CSS pixels
|-
|}
|-
| <code>start</code> || UNIX device timestamp of when this batch of metrics started recording
|-
| <code>stop</code> || UNIX device timestamp of when this batch of metrics stopped recording
|-
|}
==Notes==
* The size of the JSON payload that we send to the telemetry server seems to be between 1KB-3KB on average.

Firefox OS/Metrics/App Usage

2014-09-24T17:35:21Z

Marshall law:

Firefox OS/Metrics

2014-09-24T17:26:27Z

Marshall law: /* App usage metrics */

=FTU ping=
==Design of Activation Ping==
#Activation Ping is triggered through the first-time use experience / activation.
#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)
#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:
# Unless the setting <tt>ftu.pingEnabled</tt> 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.
# 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.
# Record the time the ping service started, to track the delta of time to a successful ping.
# Pull all relevant ping payload settings asynchronously.
# Create an interval timer to attempt a ping once an hour. This is configurable with <tt>ftu.pingTryInterval</tt>.
## 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 <tt>ftu.pingMaxNetworkFails</tt>.
## Send an HTTP request to <tt>FTU_PING_URL/PING_ID/ftu/FirefoxOS/VERSION/UPDATE_CHANNEL/BUILD_ID</tt>. By default, the ping URL is https://fxos.telemetry.mozilla.org/submit/telemetry, and is configurable in the <tt>ftu.pingURL</tt> setting, or via make with <tt>FTU_PING_URL</tt>.
### If the HTTP request succeeds, set <tt>ftu.pingEnabled</tt> to false, and disable the interval timer. Otherwise, try again on the next interval.

==Example payload and URL==

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

<code><pre>
{
"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.platform_version": "31.0a1",
"deviceinfo.platform_build_id": "20140423185429",
"deviceinfo.software": "Boot2Gecko 2.0.0.0-prerelease",
"deviceinfo.update_channel": "default",
"devicePixelRatio": 1,
"screenWidth": 320,
"screenHeight": 480,
"ver": 2
}
</pre></code>

===Glossary===

{|
|-
| <code>activationTime</code> || Timestamp indicating when the device was activated (user completes first-run experience).
|-
| <code>pingTime</code> || 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.
|-
| <code>locale</code> || Platform localization.
|-
| <code>network</code> || 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.
|-
| <code>icc</code> || 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.
|-
| <code>mcc</code> || Mobile country code.
|-
| <code>mnc</code> || Mobile network code (identifies operator).
|-
| <code>operator</code> || Network operator name.
|-
| <code>spn</code> || SIM service provider name.
|-
| <code>info</code> || Fields added server-side, read from submission URL.
|-
| <code>appUpdateChannel</code> || Copied from <code>deviceinfo.update_channel</code>.
|-
| <code>appVersion</code> || Copied from <code>deviceinfo.platform_version</code>.
|-
| <code>appName</code> || Name of app submitting ping (set to <code>FirefoxOS</code>).
|-
| <code>appBuildID</code> || Copied from <code>deviceinfo.platform_build_id</code>.
|-
| <code>geoCountry</code> || Country from which the ping was sent. Added server-side using GeoIP lookup.
|-
| <code>reason</code> || A code identifying the type of ping. FTU is currently the only ping being sent.
|-
| <code>deviceinfo</code> || Fields read off the device.
|-
| <code>deviceinfo.firmware_revision</code> ||
|-
| <code>deviceinfo.hardware</code> || Chipset manufacturer.
|-
| <code>deviceinfo.os</code> || Gaia version.
|-
| <code>deviceinfo.product_model</code> || Device model name.
|-
| <code>deviceinfo.platform_version</code> || Gecko version.
|-
| <code>deviceinfo.platform_build_id</code> || Gecko build ID. Generated from a timestamp - first 8 digits give date.
|-
| <code>deviceinfo.software</code> || Name of Gaia distribution.
|-
| <code>deviceinfo.update_channel</code> ||
|-
| <code>devicePixelRatio</code> ||
|-
| <code>screenWidth</code> || Width of the screen in pixels.
|-
| <code>screenHeight</code> || Height of the screen in pixels.
|-
| <code>ver</code> || 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.

{| class="wikitable"
|-
! Field !! Explanation !!Partner modifiable? Format!!Share with Moz for Certification?|| Comments
|-
|deviceinfo.os
|GAIA version. Eg: 2.0.0.0
|Y. Format needed:"X.Y.Z.W"
|Y
|
|-
|deviceinfo.software
|Name of Gaia distribution.eg:"Boot2Gecko 2.0.0.0-prerelease"
|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 build_id.eg: "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
|}

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: <tt>cd gaia; make FTU_PING_URL=... reset-gaia</tt>
* Set <tt>DEBUG = true</tt> in <tt>gaia/apps/system/js/ftu_ping.js</tt> to see messages at various stages of the ping lifecycle, and the raw ping data when it is actually sent
* Change <tt>DEFAULT_TRY_INTERVAL</tt> in <tt>gaia/apps/system/js/ftu_ping.js</tt> to something much smaller than 1 hour (i.e. 15 seconds)

=App usage metrics=

See [[FirefoxOS/Metrics/App Usage]]

=High Level Requirements=
#Product Planning: Need to know the number of devices sold. This will help product decisions be data driven.
#User Benefit: knowing the following information will improve security updates and app functionality
## 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.
##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==
#Information:
##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
###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
##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.
#Reliability:
##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
#Cost:
##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.

Firefox OS/Metrics/App Usage

2014-09-24T17:25:19Z

Marshall law:

=Requirements=
For all system and 3rd party apps, track:
# Total time that each app (by URL) has been actively been used (in the foreground while the screen is on)
# Counts for the number of times an app has been opened, closed, or crashed
# A list of apps that have been uninstalled since the last successful report

=Design=
The App Updates Metrics (AUM) service actively collects usage information by hooking into several system events. The determination of running time of an app looks something like this:

* When an app is opened, or the user switches to the homescreen, AUM marks it as the currently running app, and records the current time
* When the device is locked, the display goes to sleep, or another app is opened, AUM records the delta of the current time with the current app's start time
* When the device is unlocked after the display was sleeping, the current app's start time is reset to the current time so we don't record usage time while the screen was off/locked
* AUM also records installs, uninstalls, and and activity invocations (on activity URLs -- not running time) of apps

When the device is idle and and any of these registered events occur:
* AUM will save the currently collected metrics to async storage
* If the device is also online and a specified interval has passed (default 24 hours), AUM will begin attemping to transmit the stored metrics to the Telemetry server
* If transmission fails, then a separate retry interval (default 1 hour) controls how often AUM will retry transmission until it is successful

=Glossary=
{|
|-
| <code>apps</code> || Usage for each app in this batch (these are not aggregates), keyed by the app's manifest URL
{|
|-
| <code>installs</code> || The number of app installs
|-
| <code>uninstalls</code> || The number of app uninstalls
|-
| <code>invocations</code> || The number of times the app was started
|-
| <code>usageTime</code> || The total number of seconds the app was used
|-
|}
|-
| <code>deviceID</code> || A randomly generated deviceID to help server side de-duplication. This is separate from any other ID in the system, including the FTU activation ping
|-
| <code>deviceinfo</code> ||
{|
|-
| <code>developer.menu.enabled</code> || Whether or not this is a 'production' build
|-
| <code>deviceinfo.platform_build_id</code> || The timestamp that gecko was built
|-
| <code>deviceinfo.platform_version</code> || The version string of gecko
|-
| <code>deviceinfo.update_channel</code> || Update channel used for FxOS OTA updates
|-
|}
|-
| <code>locale</code> || Platform locale string, i.e. 'en-US'
|-
| <code>screen</code> ||
{|
|-
| <code>devicePixelRatio</code> || ratio of physical pixels to virtual pixels on the device
|-
| <code>width</code> || screen width in CSS pixels
|-
| <code>height</code> || screen height in CSS pixels
|-
|}
|-
| <code>start</code> || UNIX device timestamp of when this batch of metrics started recording
|-
| <code>stop</code> || UNIX device timestamp of when this batch of metrics stopped recording
|-
|}

==Example==
<code><pre>
POST https://fxos.telemetry.mozilla.org/submit/telemetry/metrics/FirefoxOS/appusage
{
"apps": {
"app://verticalhome.gaiamobile.org/manifest.webapp": {
"activities": {},
"installs": 0,
"invocations": 1,
"uninstalls": 0,
"usageTime": 23
}
},
"deviceID": "j2670k6q",
"deviceinfo": {
"developer.menu.enabled": true,
"deviceinfo.platform_build_id": "20140902135234",
"deviceinfo.platform_version": "34.0a1",
"deviceinfo.update_channel": "unknown"
},
"locale": "en-US",
"screen": {
"devicePixelRatio": 1.5,
"height": 569,
"width": 320
},
"start": 1411567451826,
"stop": 1411577295717
}
</pre></code>

Firefox OS/Metrics/App Usage

2014-09-18T22:33:02Z

Marshall law: Created page with "=Requirements= For all system and 3rd party apps, track: # Total time that each app (by URL) has been actively been used (in the foreground while the screen is on) # Counts fo..."

Firefox OS/Metrics

2014-06-25T22:18:09Z

Marshall law: /* Requirements */

=FTU ping=
==Design of Activation Ping==
#Activation Ping is triggered through the first-time use experience / activation.
#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)
#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:
# Unless the setting <tt>ftu.pingEnabled</tt> 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.
# 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.
# Record the time the ping service started, to track the delta of time to a successful ping.
# Pull all relevant ping payload settings asynchronously.
# Create an interval timer to attempt a ping once an hour. This is configurable with <tt>ftu.pingTryInterval</tt>.
## 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 <tt>ftu.pingMaxNetworkFails</tt>.
## Send an HTTP request to <tt>FTU_PING_URL/PING_ID/ftu/FirefoxOS/VERSION/UPDATE_CHANNEL/BUILD_ID</tt>. By default, the ping URL is https://fxos.telemetry.mozilla.org/submit/telemetry, and is configurable in the <tt>ftu.pingURL</tt> setting, or via make with <tt>FTU_PING_URL</tt>.
### If the HTTP request succeeds, set <tt>ftu.pingEnabled</tt> to false, and disable the interval timer. Otherwise, try again on the next interval.

==Example payload and URL==

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

<code><pre>
{
"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.platform_version": "31.0a1",
"deviceinfo.platform_build_id": "20140423185429",
"deviceinfo.software": "Boot2Gecko 2.0.0.0-prerelease",
"deviceinfo.update_channel": "default",
"devicePixelRatio": 1,
"screenWidth": 320,
"screenHeight": 480,
"ver": 2
}
</pre></code>

===Glossary===

{|
|-
| <code>activationTime</code> || Timestamp indicating when the device was activated (user completes first-run experience).
|-
| <code>pingTime</code> || 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.
|-
| <code>locale</code> || Platform localization.
|-
| <code>network</code> || 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.
|-
| <code>icc</code> || 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.
|-
| <code>mcc</code> || Mobile country code.
|-
| <code>mnc</code> || Mobile network code (identifies operator).
|-
| <code>operator</code> || Network operator name.
|-
| <code>spn</code> || SIM service provider name.
|-
| <code>info</code> || Fields added server-side, read from submission URL.
|-
| <code>appUpdateChannel</code> || Copied from <code>deviceinfo.update_channel</code>.
|-
| <code>appVersion</code> || Copied from <code>deviceinfo.platform_version</code>.
|-
| <code>appName</code> || Name of app submitting ping (set to <code>FirefoxOS</code>).
|-
| <code>appBuildID</code> || Copied from <code>deviceinfo.platform_build_id</code>.
|-
| <code>geoCountry</code> || Country from which the ping was sent. Added server-side using GeoIP lookup.
|-
| <code>reason</code> || A code identifying the type of ping. FTU is currently the only ping being sent.
|-
| <code>deviceinfo</code> || Fields read off the device.
|-
| <code>deviceinfo.firmware_revision</code> ||
|-
| <code>deviceinfo.hardware</code> || Chipset manufacturer.
|-
| <code>deviceinfo.os</code> || Gaia version.
|-
| <code>deviceinfo.product_model</code> || Device model name.
|-
| <code>deviceinfo.platform_version</code> || Gecko version.
|-
| <code>deviceinfo.platform_build_id</code> || Gecko build ID. Generated from a timestamp - first 8 digits give date.
|-
| <code>deviceinfo.software</code> || Name of Gaia distribution.
|-
| <code>deviceinfo.update_channel</code> ||
|-
| <code>devicePixelRatio</code> ||
|-
| <code>screenWidth</code> || Width of the screen in pixels.
|-
| <code>screenHeight</code> || Height of the screen in pixels.
|-
| <code>ver</code> || Payload format version. Gets bumped when fields get added or changed.
|}

==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: <tt>cd gaia; make FTU_PING_URL=... reset-gaia</tt>
* Set <tt>DEBUG = true</tt> in <tt>gaia/apps/system/js/ftu_ping.js</tt> to see messages at various stages of the ping lifecycle, and the raw ping data when it is actually sent
* Change <tt>DEFAULT_TRY_INTERVAL</tt> in <tt>gaia/apps/system/js/ftu_ping.js</tt> to something much smaller than 1 hour (i.e. 15 seconds)

=App usage metrics=

We plan to collect basic usage information periodically about the system and 3rd party apps installed on FxOS devices

==Requirements==
For all system and 3rd party apps, track:
# Total time that each app (by URL) has been actively been used (in the foreground while the screen is on)
# Counts for the number of times an app has been opened, closed, or crashed
# A list of apps that have been uninstalled since the last successful report

These metrics should be collected and submitted to our telemetry server periodically.

=High Level Requirements=
#Product Planning: Need to know the number of devices sold. This will help product decisions be data driven.
#User Benefit: knowing the following information will improve security updates and app functionality
## 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.
##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==
#Information:
##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
###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
##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.
#Reliability:
##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
#Cost:
##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.

Firefox OS/Metrics

2014-06-25T16:23:34Z

Marshall law:

=FTU ping=
==Design of Activation Ping==
#Activation Ping is triggered through the first-time use experience / activation.
#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)
#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:
# Unless the setting <tt>ftu.pingEnabled</tt> 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.
# 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.
# Record the time the ping service started, to track the delta of time to a successful ping.
# Pull all relevant ping payload settings asynchronously.
# Create an interval timer to attempt a ping once an hour. This is configurable with <tt>ftu.pingTryInterval</tt>.
## 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 <tt>ftu.pingMaxNetworkFails</tt>.
## Send an HTTP request to <tt>FTU_PING_URL/PING_ID/ftu/FirefoxOS/VERSION/UPDATE_CHANNEL/BUILD_ID</tt>. By default, the ping URL is https://fxos.telemetry.mozilla.org/submit/telemetry, and is configurable in the <tt>ftu.pingURL</tt> setting, or via make with <tt>FTU_PING_URL</tt>.
### If the HTTP request succeeds, set <tt>ftu.pingEnabled</tt> to false, and disable the interval timer. Otherwise, try again on the next interval.

==Example payload and URL==

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

<code><pre>
{
"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.platform_version": "31.0a1",
"deviceinfo.platform_build_id": "20140423185429",
"deviceinfo.software": "Boot2Gecko 2.0.0.0-prerelease",
"deviceinfo.update_channel": "default",
"devicePixelRatio": 1,
"screenWidth": 320,
"screenHeight": 480,
"ver": 2
}
</pre></code>

===Glossary===

{|
|-
| <code>activationTime</code> || Timestamp indicating when the device was activated (user completes first-run experience).
|-
| <code>pingTime</code> || 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.
|-
| <code>locale</code> || Platform localization.
|-
| <code>network</code> || 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.
|-
| <code>icc</code> || 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.
|-
| <code>mcc</code> || Mobile country code.
|-
| <code>mnc</code> || Mobile network code (identifies operator).
|-
| <code>operator</code> || Network operator name.
|-
| <code>spn</code> || SIM service provider name.
|-
| <code>info</code> || Fields added server-side, read from submission URL.
|-
| <code>appUpdateChannel</code> || Copied from <code>deviceinfo.update_channel</code>.
|-
| <code>appVersion</code> || Copied from <code>deviceinfo.platform_version</code>.
|-
| <code>appName</code> || Name of app submitting ping (set to <code>FirefoxOS</code>).
|-
| <code>appBuildID</code> || Copied from <code>deviceinfo.platform_build_id</code>.
|-
| <code>geoCountry</code> || Country from which the ping was sent. Added server-side using GeoIP lookup.
|-
| <code>reason</code> || A code identifying the type of ping. FTU is currently the only ping being sent.
|-
| <code>deviceinfo</code> || Fields read off the device.
|-
| <code>deviceinfo.firmware_revision</code> ||
|-
| <code>deviceinfo.hardware</code> || Chipset manufacturer.
|-
| <code>deviceinfo.os</code> || Gaia version.
|-
| <code>deviceinfo.product_model</code> || Device model name.
|-
| <code>deviceinfo.platform_version</code> || Gecko version.
|-
| <code>deviceinfo.platform_build_id</code> || Gecko build ID. Generated from a timestamp - first 8 digits give date.
|-
| <code>deviceinfo.software</code> || Name of Gaia distribution.
|-
| <code>deviceinfo.update_channel</code> ||
|-
| <code>devicePixelRatio</code> ||
|-
| <code>screenWidth</code> || Width of the screen in pixels.
|-
| <code>screenHeight</code> || Height of the screen in pixels.
|-
| <code>ver</code> || Payload format version. Gets bumped when fields get added or changed.
|}

==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: <tt>cd gaia; make FTU_PING_URL=... reset-gaia</tt>
* Set <tt>DEBUG = true</tt> in <tt>gaia/apps/system/js/ftu_ping.js</tt> to see messages at various stages of the ping lifecycle, and the raw ping data when it is actually sent
* Change <tt>DEFAULT_TRY_INTERVAL</tt> in <tt>gaia/apps/system/js/ftu_ping.js</tt> to something much smaller than 1 hour (i.e. 15 seconds)

=App usage metrics=

We plan to collect basic usage information periodically about the system and 3rd party apps installed on FxOS devices

==Requirements==
For all system and 3rd party apps, track:
# Total time that each app has been actively been used (in the foreground while the screen is on)
# Counts for the number of times an app has been opened, closed, or crashed
# A list of apps that have been uninstalled

These metrics should be collected and submitted to our telemetry server periodically.

=High Level Requirements=
#Product Planning: Need to know the number of devices sold. This will help product decisions be data driven.
#User Benefit: knowing the following information will improve security updates and app functionality
## 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.
##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==
#Information:
##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
###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
##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.
#Reliability:
##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
#Cost:
##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.

Firefox OS/Metrics

2014-04-15T21:19:50Z

Marshall law: /* Details */

Firefox OS/Metrics

2014-04-03T22:37:53Z

Marshall law:

=FTU ping=

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:
# Unless the setting <tt>ftu.pingEnabled</tt> 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.
# 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.
# Record the time the ping service started, to track the delta of time to a successful ping.
# Pull all relevant ping payload settings asynchronously.
# Create an interval timer to attempt a ping once an hour. This is configurable with <tt>ftu.pingTryInterval</tt>.
## 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 <tt>ftu.pingMaxNetworkFails</tt>.
## Send an HTTP request to <tt>FTU_PING_URL/PING_ID/ftu/FirefoxOS/VERSION/UPDATE_CHANNEL/BUILD_ID</tt>. By default, the ping URL is https://fxos.telemetry.mozilla.org, and is configurable in the <tt>ftu.pingURL</tt> setting, or via make with <tt>FTU_PING_URL</tt>.
### If the HTTP request succeeds, set <tt>ftu.pingEnabled</tt> to false, and disable the interval timer. Otherwise, try again on the next interval.

==Example payload and URL==

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

<code><pre>
{
"activationTime": 1395769944966,
"devicePixelRatio": 1,
"deviceinfo.firmware_revision": "",
"deviceinfo.hardware": "qcom",
"deviceinfo.os": "1.5.0.0-prerelease",
"deviceinfo.platform_build_id": "20140325104133",
"deviceinfo.platform_version": "31.0a1",
"deviceinfo.product_model": "ALCATEL ONE TOUCH FIRE",
"deviceinfo.software": "Boot2Gecko 1.5.0.0-prerelease",
"deviceinfo.update_channel": "default",
"icc": {
"mcc": "310",
"mnc": "410",
"spn": null
},
"locale": "en-US",
"network": {
"mcc": "310",
"mnc": "410",
"operator": "AT&T"
},
"pingID": "e426da9f-2a29-4e09-895b-c883903956cb",
"pingTime": 1395852542588,
"screenHeight": 480,
"screenWidth": 320
}
</pre></code>

==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: <tt>cd gaia; make FTU_PING_URL=... reset-gaia</tt>
* Set <tt>DEBUG = true</tt> in <tt>gaia/apps/system/js/ftu_ping.js</tt> to see messages at various stages of the ping lifecycle, and the raw ping data when it is actually sent
* Change <tt>DEFAULT_TRY_INTERVAL</tt> in <tt>gaia/apps/system/js/ftu_ping.js</tt> to something much smaller than 1 hour (i.e. 15 seconds)

=Phase 1=
==Requirements==
#Product Planning: Need to know the number of devices sold. This will help product decisions be data driven.
#User Benefit: knowing the following information will improve security updates and app functionality
## 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.
##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.

==Design of Activation Ping==
#Activation Ping is triggered through the first-time use experience / activation. Will automatically retry until it is successful (on a 1 hour interval)
#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)
#Can also be disabled, but requires extra work on top of disabling app updates or removing the Firefox marketplace app
==Delta to what exists today==
#Information:
##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
###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
##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.
#Reliability:
##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
#Cost:
##From previous versions, Partners removed ADI ping due to cost concern. Activation Ping is sent once in a lifetime, which should allay cost concerns.

=Phase 2=
==Requirements==

Firefox OS/Metrics

2014-04-02T15:33:05Z

Marshall law:

=FTU ping=

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:
# Unless the setting <tt>ftu.pingEnabled</tt> 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.
# 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.
# Record the time the ping service started, to track the delta of time to a successful ping.
# Pull all relevant ping payload settings asynchronously.
# Create an interval timer to attempt a ping once an hour. This is configurable with <tt>ftu.pingTryInterval</tt>.
## 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 <tt>ftu.pingMaxNetworkFails</tt>.
## Send an HTTP request to <tt>FTU_PING_URL/PING_ID/ftu/FirefoxOS/VERSION/UPDATE_CHANNEL/BUILD_ID</tt>. By default, the ping URL is https://fxos.telemetry.mozilla.org, and is configurable in the <tt>ftu.pingURL</tt> setting, or via make with <tt>FTU_PING_URL</tt>.
### If the HTTP request succeeds, set <tt>ftu.pingEnabled</tt> to false, and disable the interval timer. Otherwise, try again on the next interval.

==Example payload and URL==

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

<code><pre>
{
"activationTime": 1395769944966,
"devicePixelRatio": 1,
"deviceinfo.firmware_revision": "",
"deviceinfo.hardware": "qcom",
"deviceinfo.os": "1.5.0.0-prerelease",
"deviceinfo.platform_build_id": "20140325104133",
"deviceinfo.platform_version": "31.0a1",
"deviceinfo.product_model": "ALCATEL ONE TOUCH FIRE",
"deviceinfo.software": "Boot2Gecko 1.5.0.0-prerelease",
"deviceinfo.update_channel": "default",
"icc": {
"mcc": "310",
"mnc": "410",
"spn": null
},
"locale": "en-US",
"network": {
"mcc": "310",
"mnc": "410",
"operator": "AT&T"
},
"pingID": "e426da9f-2a29-4e09-895b-c883903956cb",
"pingTime": 1395852542588,
"screenHeight": 480,
"screenWidth": 320
}
</pre></code>

=Phase 1=
==Requirements==
#Product Planning: Need to know the number of devices sold. This will help product decisions be data driven.
#User Benefit: knowing the following information will improve security updates and app functionality
## 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.
##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.

==Design of Activation Ping==
#Activation Ping is triggered through the first-time use experience / activation. Will automatically retry until it is successful (on a 1 hour interval)
#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)
#Can also be disabled, but requires extra work on top of disabling app updates or removing the Firefox marketplace app
==Delta to what exists today==
#Information:
##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
###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
##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.
#Reliability:
##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
#Cost:
##From previous versions, Partners removed ADI ping due to cost concern. Activation Ping is sent once in a lifetime, which should allay cost concerns.

=Phase 2=
==Requirements==

Firefox OS/Metrics

2014-04-02T15:31:19Z

Marshall law:

=FTU ping=

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, no unique hardware identifiers.

Currently, the logic for the FTU ping is broken down like this:
# Unless the setting <tt>ftu.pingEnabled</tt> 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.
# 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.
# Record the time the ping service started, to track the delta of time to a successful ping.
# Pull all relevant ping payload settings asynchronously.
# Create an interval timer to attempt a ping once an hour. This is configurable with <tt>ftu.pingTryInterval</tt>.
## 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 <tt>ftu.pingMaxNetworkFails</tt>.
## Send an HTTP request to <tt>FTU_PING_URL/PING_ID/ftu/FirefoxOS/VERSION/UPDATE_CHANNEL/BUILD_ID</tt>. By default, the ping URL is https://fxos.telemetry.mozilla.org, and is configurable in the <tt>ftu.pingURL</tt> setting, or via make with <tt>FTU_PING_URL</tt>.
### If the HTTP request succeeds, set <tt>ftu.pingEnabled</tt> to false, and disable the interval timer. Otherwise, try again on the next interval.

==Example payload and URL==

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

<code><pre>
{
"activationTime": 1395769944966,
"devicePixelRatio": 1,
"deviceinfo.firmware_revision": "",
"deviceinfo.hardware": "qcom",
"deviceinfo.os": "1.5.0.0-prerelease",
"deviceinfo.platform_build_id": "20140325104133",
"deviceinfo.platform_version": "31.0a1",
"deviceinfo.product_model": "ALCATEL ONE TOUCH FIRE",
"deviceinfo.software": "Boot2Gecko 1.5.0.0-prerelease",
"deviceinfo.update_channel": "default",
"icc": {
"mcc": "310",
"mnc": "410",
"spn": null
},
"locale": "en-US",
"network": {
"mcc": "310",
"mnc": "410",
"operator": "AT&T"
},
"pingID": "e426da9f-2a29-4e09-895b-c883903956cb",
"pingTime": 1395852542588,
"screenHeight": 480,
"screenWidth": 320
}
</pre></code>

=Phase 1=
==Requirements==
#Product Planning: Need to know the number of devices sold. This will help product decisions be data driven.
#User Benefit: knowing the following information will improve security updates and app functionality
## 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.
##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.

==Design of Activation Ping==
#Activation Ping is triggered through the first-time use experience / activation. Will automatically retry until it is successful (on a 1 hour interval)
#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)
#Can also be disabled, but requires extra work on top of disabling app updates or removing the Firefox marketplace app
==Delta to what exists today==
#Information:
##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
###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
##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.
#Reliability:
##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
#Cost:
##From previous versions, Partners removed ADI ping due to cost concern. Activation Ping is sent once in a lifetime, which should allay cost concerns.

=Phase 2=
==Requirements==

Firefox OS/Metrics

2014-03-24T17:40:13Z

Marshall law: Created page with "This is a placeholder page for design / discussion around Metrics in FxOS"

This is a placeholder page for design / discussion around Metrics in FxOS

B2G/UpdateTesting

2012-12-26T17:21:02Z

Marshall law:

'''This document is a WIP for the upcoming B2G update test automation in {{bug|821412}}'''

== Overview ==
When a system update is applied in B2G, it causes either a process restart (OTA) or a device reboot (FOTA), requiring special high level support from a testing framework to automate testing of the various stages of the update.

To solve this problem, specialized Marionette based frontends have been written to solve two different use cases:
# A script based frontend for use by developers, and eventually TBPL
# A "continuous build" smoke testing frontend designed to automatically test updates between builds in a Continuous Integration environment.

== Smoke Tests ==

==== Setup ====

To get started, just make a directory that will store updates and flash scripts for each build, and inside it create a smoketest-config.json.
<pre>
$ mkdir $B2G_UPDATE_TESTDATA
</pre>

Example smoketest-config.json:
<pre>
{
"devices": {
"unagi": {
"system_fs_type": "ext4",
"system_location": "/dev/block/mmcblk0p19",
"data_fs_type": "ext4",
"data_location": "/dev/block/mmcblk0p22",
"sdcard": "/mnt/sdcard",
"sdcard_recovery": "/sdcard",
"serials": ["full_unagi"]
}
},

"public_key": "/Users/mculpepper/Code/B2G-dev/build/target/product/security/testkey.x509.pem",
"private_key": "/Users/mculpepper/Code/B2G-dev/build/target/product/security/testkey.pk8"
}
</pre>

==== CI integration ====

* Each CI build should have it's update staged for each test device:
<pre>
$ testing/marionette/update-smoketests/stage-update.py unagi $B2G_UPDATE_TESTDATA
</pre>

* Once at least 2 builds are staged, the smoketests can be run by passing a list of build IDs to test between:
<pre>
$ testing/marionette/update-smoketests/run-smoketests.py --build-dir $B2G_UPDATE_TESTDATA --run-dir $B2G_UPDATE_RUNDATA 20121219101023 20121220172647
</pre>

B2G/UpdateTesting

2012-12-21T23:33:21Z

Marshall law:

'''This document is a WIP for the upcoming B2G update test automation in {{bug|821412}}'''

== Smoke Tests ==

==== Setup ====

To get started, just make a directory that will store updates and flash scripts for each build, and inside it create a smoketest-config.json.
<pre>
$ mkdir $B2G_UPDATE_TESTDATA
</pre>

Example smoketest-config.json:
<pre>
{
"devices": {
"unagi": {
"system_fs_type": "ext4",
"system_location": "/dev/block/mmcblk0p19",
"data_fs_type": "ext4",
"data_location": "/dev/block/mmcblk0p22",
"sdcard": "/mnt/sdcard",
"sdcard_recovery": "/sdcard",
"serials": ["full_unagi"]
}
},

"public_key": "/Users/mculpepper/Code/B2G-dev/build/target/product/security/testkey.x509.pem",
"private_key": "/Users/mculpepper/Code/B2G-dev/build/target/product/security/testkey.pk8"
}
</pre>

==== CI integration ====

* Each CI build should have it's update staged for each test device:
<pre>
$ testing/marionette/update-smoketests/stage-update.py unagi $B2G_UPDATE_TESTDATA
</pre>

* Once at least 2 builds are staged, the smoketests can be run by passing a list of build IDs to test between:
<pre>
$ testing/marionette/update-smoketests/run-smoketests.py --build-dir $B2G_UPDATE_TESTDATA --run-dir $B2G_UPDATE_RUNDATA 20121219101023 20121220172647
</pre>

B2G/UpdateTesting

2012-12-21T23:32:36Z

Marshall law: Created page with "'''This document is a WIP for the upcoming B2G update test automation in Bug 821412''' {{bug|821412}} == Smoke Tests == ==== Setup ==== To get started, just make a directory t..."

'''This document is a WIP for the upcoming B2G update test automation in Bug 821412'''
{{bug|821412}}

== Smoke Tests ==

==== Setup ====

To get started, just make a directory that will store updates and flash scripts for each build, and inside it create a smoketest-config.json.
<pre>
$ mkdir $B2G_UPDATE_TESTDATA
</pre>

Example smoketest-config.json:
<pre>
{
"devices": {
"unagi": {
"system_fs_type": "ext4",
"system_location": "/dev/block/mmcblk0p19",
"data_fs_type": "ext4",
"data_location": "/dev/block/mmcblk0p22",
"sdcard": "/mnt/sdcard",
"sdcard_recovery": "/sdcard",
"serials": ["full_unagi"]
}
},

"public_key": "/Users/mculpepper/Code/B2G-dev/build/target/product/security/testkey.x509.pem",
"private_key": "/Users/mculpepper/Code/B2G-dev/build/target/product/security/testkey.pk8"
}
</pre>

==== CI integration ====

* Each CI build should have it's update staged for each test device:
<pre>
$ testing/marionette/update-smoketests/stage-update.py unagi $B2G_UPDATE_TESTDATA
</pre>

* Once at least 2 builds are staged, the smoketests can be run by passing a list of build IDs to test between:
<pre>
$ testing/marionette/update-smoketests/run-smoketests.py --build-dir $B2G_UPDATE_TESTDATA --run-dir $B2G_UPDATE_RUNDATA 20121219101023 20121220172647
</pre>

B2G/Updating

2012-12-10T19:48:12Z

Marshall law: /* Building updates for multiple software versions */

This page intends to help engineers set up an environment for updating B2G devices. It focuses on low-level details of the updating tools and omits many higher-level topics. The higher-level issues are covered in [http://example.com XXX other doc].

Updating is the process of (i) on a build host, building incremental update packages from old version(s) to a new version; (ii) on the client, finding the right update to download; (iii) downloading the update; (iv) applying the update to existing files on the device. Each of these items are covered below.

== Types of updates ==

B2G phones can update the entire system through '''FOTA updates'''. The technology behind FOTA updates is shared with the Android project. The areas that can be implemented through FOTA updates include the system partition, kernel, modem baseband, recovery image used for updating, or any other file on the device.

B2G can also update ''just'' the Gecko and Gaia files on device, through a mechanism we call '''Gecko/Gaia OTA updates'''. All of the Gecko and Gaia files are in the <code>/system/b2g</code> directory on the device. They compromise the core Gecko runtime and the device's user interface.

=== FOTA updates ===

* B2G is FOTA-client-neutral, but we recommend GOTA, and that's what's discussed here
* update.zip and update-script
* mar wrapping and signing
* librecovery, recovery image

=== Gecko/Gaia OTA updates ===

* update.mar and update.xml
* mar signing
* same technology used by Firefox for Desktop
* update binary

== Building updates for multiple software versions ==

Since we support both OTA and FOTA updates in FirefoxOS, we have tools to help in the generation of both. At a high level, the process looks like this for each build:

# Generate a complete OTA update MAR for the contents of /system/b2g
# Generate an incremental OTA update MAR by providing the previous version's complete OTA update MAR
# Generate a complete FOTA update zip and target files zip for the device partitions
# Generate an incremental FOTA update zip by providing the previous version's target files zip
# Wrap the complete (and/or) incremental FOTA update zips in a MAR for FxOS delivery
# Deploy OTA / FOTA MAR(s) to appropriate locations for hosting

=== Generating a complete OTA update MAR ===
Use the <tt>gecko-update-full</tt> target to generate a complete update MAR for the last successful b2g build. This will place the MAR in <tt>$GECKO_OBJDIR/dist/b2g-update/b2g-gecko-update.mar</tt>:

<pre>
$ ./build.sh gecko-update-full
$ cp $GECKO_OBJDIR/dist/b2g-update/b2g-gecko-update.mar <dest>
</pre>

=== Generating an incremental OTA update MAR ===
Pass the previous build complete OTA update MAR (<tt>$FROM_MAR</tt>) along with the current complete OTA update MAR (<tt>$TO_MAR</tt>) to <tt>build-gecko-mar.py</tt>, and it will generate an incremental MAR at <tt>$DEST_MAR</tt>:

<pre>
$ ./tools/update-tools/build-gecko-mar.py --from $FROM_MAR --to $TO_MAR $DEST_MAR
</pre>

=== Generating a complete FOTA update zip and target files zip ===
When performing a "standard" build, the AOSP build system will automatically generate an FOTA update.zip / target files zip, provided the kernel binary has been copied to the appropriate place under <tt>vendor</tt>. This enables boot image, recovery image, and update.zip generation.

The complete FOTA update zip lives under <tt>out/target/product/$DEVICE/$DEVICE-ota-$VARIANT.$USER.zip</tt><br>
The target files zip lives under <tt>out/target/product/$DEVICE/obj/PACKAGING/target_files_intermediates/$DEVICE-target_files-$VARIANT.$USER.zip</tt>

Variable values:
<table border="1" style="background-color: #eeeeee">
<tr><td>$DEVICE</td><td>Device name for the AOSP product</td></tr>
<tr><td>$VARIANT</td><td><tt>eng</tt>, <tt>user</tt>, or <tt>userdebug</tt></td></tr>
<tr><td>$USER</td><td>The build username</td></tr>
</table>

=== Generating an incremental FOTA update zip ===
Pass the previous build FOTA target files zip (<tt>$FROM_ZIP</tt>) and the current FOTA target files zip (<tt>$TO_ZIP</tt>) to <tt>build/tools/releasetools/ota_from_target_files</tt>:

<pre>
$ ./build/tools/releasetools/ota_from_target_files -v \
-i $FROM_ZIP \
-p out/host/$HOST_ARCH \
-k $FOTA_SIGNING_KEY \
$TO_ZIP \
$DEST_ZIP
</pre>

Variable values:
<table border="1" style="background-color: #eeeeee">
<tr><td>$FROM_ZIP</td><td>The previous FOTA target files zip</td></tr>
<tr><td>$TO_ZIP</td><td>The current FOTA target files zip</td></tr>
<tr><td>$DEST_ZIP</td><td>The destination incremental update zip</td></tr>
<tr><td>$HOST_ARCH</td><td>The host and arch combo (i.e. <tt>linux-x86</tt> or <tt>darwin-x86</tt>)</td></tr>
<tr><td>$FOTA_SIGNING_KEY</td><td>Path to the prefix for a private key and public cert for signing the update zip. <tt>$FOTA_SIGNING_ZIP.pk8</tt> and <tt>$FOTA_SIGNING_ZIP.x509.pem</tt> should both exist on the filesystem</td></tr>
</table>

=== Wrapping a FOTA update zip in a MAR ===
FxOS uses MARs to deliver all updates, whether they are complete or incremental. To wrap a FOTA update zip (<tt>$UPDATE_ZIP</tt>) in a MAR (<tt>$WRAPPED_MAR</tt>), use <tt>tools/update-tools/build-fota-mar.py</tt>:

<pre>
$ ./tools/update-tools/build-fota-mar.py $UPDATE_ZIP --output=$WRAPPED_MAR
</pre>

== Hosting updates (respectively, polling for updates on the client side) ==

* interaction of server tools with build tools
** The build server uploads two files to the update server: the update.mar file and the application.ini. For GOTA updates, the build server then kicks off a local script on the update server that generates update.xml based on these files. For FOTA updates, update.xml generation is manual.
* layout of packages and manifests hosted on the server
** For GOTA updates, all .mar and application.ini files reside in a single directory that corresponds to the update channel (e.g., /data/update-channels/beta for the beta update channel); update.xml points to the newest copies of these files.
** For FOTA updates, only a single .mar, .ini, and update.xml file exist in a folder which corresponds to 'linear update' url (see below), e.g., /data/update-channels/beta/$PRODUCT/$VERSION/$BUILDID.
* (for "linear updates") how a client finds one and only one update
** When linear updates are enabled, the update url on the phone is set to http://host/%CHANNEL%/%PRODUCT_MODEL%/%VERSION%/%BUILD_ID%/update.xml. Thus, each build has a unique update url, and only one update is ever posted to that location. Thus, a phone cannot skip updates, and must apply, in sequence, every update that has been posted.
** In our testing, we have used a combination of linear updates and normal udpates; we use normal updates (which allow users to download only the most recent update) for GOTA updates, but switch to linear updates for FOTA updates, so that users cannot skip FOTA updates. Performing this switch requires that the last GOTA update before a FOTA update contain an update url change, from e.g., http://host/beta/update.xml to http://host/%CHANNEL%/%PRODUCT_MODEL%/%VERSION%/%BUILD_ID%/update.xml.

== Downloading and applying updates ==

* poll for update manifest (update.xml)
* download signed mar
* verify, stage for being applied
* invoke <code>updater</code>

B2G/Updating

2012-12-07T21:39:28Z

Marshall law: /* Building updates for multiple software versions */

Gaia/System/Updates

2012-08-08T17:04:08Z

Marshall law: /* Open questions */

= Overview =

There are several types of FxOS updates:

* Gonk (Kernel)
* Gecko
* Gaia
* Apps
** Core
** Pre-installed third party
** User-installed
*** Packaged
*** Non-packaged

== Foundational principles ==

=== Security ===
The reason that we want to push updates pretty aggressively is in part security. One of the main sources of hacked computers is people running old versions of software with known security issues. Mozilla has for a long time been pushing as one of the main security benefits of Firefox our ability to update a large percentage of people's installed versions quickly.

=== Data consumption control ===
One of the big benefits of Firefox OS that we are going to try to push is the ability to keep costly data transfers down. Hence we want to avoid large downloads while the user is paying a lot of money for each byte.

=== Low friction ===
We reduce user friction by minimizing and automating updates as much as possible.

== High level requirements ==

* User can update system software
* User can update installed Apps
* User can be notified of available updates
* User can use device and apps while download is in progress
* User can be notified of insufficient disk space to download update
* User can be notified of insufficient battery life to conduct update
* User can review update file size before and after install
* User can review update details before and after install

== Development/Software Channels ==

* The requirement is to offer 3 channels for delivering the B2G software stack to users. Each channel will include consistent versions of Gonk, Gecko and Gaia. The proposed channels are:
** Nightly
** Beta
*** Weekly stable builds that users can stay on to get the latest bugs fixes and feature enhancements.
** Release
* All phones manufactured should default to the Release channel.

== References ==

* [https://etherpad.mozilla.org/B2G-software-updates B2G Software Updates]: Etherpad, Chris Lee
* [https://docs.google.com/spreadsheet/ccc?key=0AiBigu584YY7dGlNSlY0QzhJb3M5anRBa1gxalV0Y3c&pli=1#gid=10 Software Update]: Google Doc spreadsheet
* [https://docs.google.com/spreadsheet/ccc?key=0AiBigu584YY7dGlNSlY0QzhJb3M5anRBa1gxalV0Y3c&pli=1#gid=15 Software Update Policy]: Google Doc spreadsheet
* [https://bugzilla.mozilla.org/show_bug.cgi?id=780662 basecamp-update tracking bug]

= Gonk (Kernel) Updates =

== Introduction ==

* Changes to this layer in the software stack should only be made when it is absolutely necessary. The requirement here is to ensure a stable build at this level of the software to minimize any issues with the phone at the Gaia level.
* The update process proposal is take planned fixes here 1 time per quarter and only urgent security/showstopper bugs immediately as needed (and as per our agreement with the carrier partner).
* Based on a mutual agreement, the OEM or Mozilla will need to host the FOTA servers to support Kernel updates
* We cannot guarantee user data and device operability is restored to previous version in event of interrupted or corrupted install.

== Open questions ==

* OTA system updates are high risk because it is possible to brick the device in the process, correct? If so, how do we mitigate that risk?
* What is the sequence of events (eg: prompt user to restart device, whereupon install process runs?)
* Do we require the user to plug in the phone if battery is below X %?
** (sicking) This is somewhat technically doable, but a UX decision if we actually want to. What we can't do is estimate how good the battery is. I think an old "worn out" battery will fall much quicker in battery level than a new one. It's also hard to get a good estimate of how much battery is needed, but we can certainly require battery levels much higher than what's needed (say 30%).
* What prompts do we present to user?
* Do we have a rollback strategy for failed installs? Previous April discussion w/ cjones indicated no...
* What is time to install? Several minutes?
* Can we avoid user friction by downloading silently, and only during periods of user inactivity? Would not want to slow down web browsing while update processed in background, for example.
** (sicking) We don't have good mechanisms for giving lower priority or throttling individual channels in Necko right now. We technically could detect other downloads starting through and abort the update in that case, and then resume once we detect user inactivity.
* How many reboots are required in the process? Previous April discussion w/ cjones indicated two.
* Do we provide link to changelog so user can review update details before installing?
** (sicking) I think this is up to UX to set requirements. Seems technically feasible, but I'm not convinced it's needed given that in every instance we'll likely want to apply the update for security reasons.
* How large are these updates?
* Do we check for available device storage before downloading? If insufficient, how do we mitigate?
* If the user powers down the device while an update is silently downloading in background, can we resume download later on?
** (sicking) Necko has the ability to download ranges, but this also needs server support. We certainly could require such support though.
* How much user agency do we provide over installs? Can they defer? For how long? What affordances do we make for out of date software?
* How can the user review the currently-installed version? From Settings?

= Gecko Updates =

== Introduction ==
* See the B2G Gecko update meta bug here: https://bugzilla.mozilla.org/show_bug.cgi?id=715816
* Gecko updates can happen more frequently than Kernel updates. Based on input from carriers and OEMs, it likely updates at this layer will need to happen somewhere between the current Desktop 6-week train interval and ESR (every 42 weeks).
* The proposed requirement here is to offer regular updates every 18 weeks. This frequency offers Mozilla and our partners the ability to update functionality on the device at a quicker pace than other competitor OS stacks (iOS and Android), but at the same time not overwhelm our Carrier partners who may not be used to updating software so frequently.
* Other requirements here are to offer a back-up instance of Gecko to ensure we can failover when necessary (if we somehow shipped an updated Gecko version that resulted in a bug).
* The updates at the Gecko level should happen silently where the user is not aware of when this is happening.
* The user will not be charged any carrier network fees for any Gecko update (as agreed upon by Telefonica) given they will be making these updates via a private APN.
* The user should be able to go into Settings > About to determine the version of the software the are using in order to debug and/or get support for any issue they encounter.

== Open questions ==

* What is the sequence of events (eg: prompt user to restart device, whereupon install process runs?)
** (marshall_law)
** For user prompting sequence / rules, see the requirements laid out by cjones in these bugs:
*** https://bugzilla.mozilla.org/show_bug.cgi?id=740720
*** https://bugzilla.mozilla.org/show_bug.cgi?id=740722
** Currently, the plan is to automatically download any Gecko updates to /data/local/updates. IIRC we are working w/ carriers to make sure this isn't billable data.
** After an update is downloaded, the update is staged in /system/b2g/updated, and the b2g process is cleanly shutdown (and then restarted by the system)
** Soon after bootup of the new b2g process, the updater runs again, copying the staged updates into /system/b2g to make them live.
** <b>Note</b>: The updater process will re-mount /system as read-write when it starts, and back to read-only when it exits. This will happen for both staging, and copying the staged files in place. In the event of a failure remounting /system as read-only (before exit), the device will be restarted, allowing the system to mount /system as read-only. See https://bugzilla.mozilla.org/show_bug.cgi?id=764683 for more details
** (/marshall_law)

** How different is process from Gonk updates?
* How often should we check for Gecko update?
** Every 18 weeks, according to CLee's etherpad outline...
*** (sicking) This sounds too rare given that we ship Gecko updates every 6 weeks which always contain security updates. Usually we count on security researchers being able to reverse engineer those updates and create exploits for older versions of Gecko.
*** (marshall_law) IIRC the reasoning had to do with risk mitigation from carriers (it was a compromise of some kind?)
* Can we confirm that there will be a back-up instance of Gecko in event of failed updates? If so, what will sequence of it's application be?
** (marshall_law) That is the plan for stage 2 of the update mechanism. See [https://bugzilla.mozilla.org/show_bug.cgi?id=715816#c1 the list of stages proposed by cjones]
* Does being on 3G/Edge affect when we check for Gecko updates?
** Should not, since updates will be free OTA via Carrier's private APN.
* What—if anything—should we tell the user when a Gecko updated is detected? Should we behave differently if the user is on 3G/Edge connection when we detect that an update is available?
** Download update and apply silently in background, same as Gonk process? Might be too intrusive for these more frequent (18 weeks) Gecko updates?
** (marshall_law) see above
* Do we have the technical ability to download the update in the background and only notify the user once the new version is available?
** (marshall_law) yes
* Should we do anything special if the phone has been turned off for a few days and is then started?
** (marshall_law) IIRC, the existing Gecko update internals already have the logic for knowing how long it's been since the last update check. They should be able to detect this and do an update check as soon as the phone is on. We should confirm this, though.
* Do we need to have a mechanism for pushing extra-critical updates?
* Should we inform users about how big updates will be before downloading them? Do we have the ability to tell before doing the actual download?
** (marshall_law) We do have the ability -- the update MAR format specifies update size. We don't currently have plans to inform about the size of an update, but feel free to chime in on any of the bugs listed on how that might work.
* Do we require the user to plug in the phone if battery is below X %?
** (sicking) See answer for Gonk
* What prompts do we present to user?
** (marshall_law) see above
* Do we have a rollback strategy for failed installs? Previous April discussion w/ cjones indicated no...
** (marshall_law) we do in Phase 2, which I don't think we plan to have for v1. Will need to check w/ cjones to verify though
* What is time to install? Several minutes?
** (marshall_law) It all depends on the size of the update, the speed of the internal disk, the device hardware.. :) We might want to profile this in a few configurations..
* Can we avoid user friction by downloading silently, and only during periods of user inactivity? Would not want to slow down web browsing while update processed in background, for example.
** (marshall_law) yes, see the bugs about prompting
* How many device reboots are required in the process?
** (marshall_law) for Gecko, there shouldn't be any. only a process restart is required. the only time a restart might happen is if /system is somehow left in read-write after the updater is finished, as a fail safe.
* Do we provide link to changelog so user can review update details before installing?
** (marshall_law) good question! not currently.. I've opened a new bug for this here: https://bugzilla.mozilla.org/show_bug.cgi?id=781233
** (sicking) See answer for Gonk
* How large are these updates?
** (marshall_law) they are binary diff'd, so potentially not "huge", but again this all depends on how big the update is. definitely smaller than if we were downloading fresh binaries.
* Do we check for available device storage before downloading? If insufficient, how do we mitigate?
* If the user powers down the device while an update is silently downloading in background, can we resume download later on?
** (sicking) See answer for Gonk
* How much user agency do we provide over installs? Can they defer? For how long? What affordances do we make for out of date Gecko?
* How can the user review the currently-installed version? From Settings?

= Gaia Updates =

== Introduction ==

* Gaia updates are related to anything that may modify the user interface and experience of the OS. The update interval will also be every 18-weeks to align with Gecko updates.
* Updates that happen to the Core Apps (Dialer, SMS, Camera, etc.) will happen silently and users will not be charged any carrier network fees for Gaia System and Core App updates (similar to Gecko updates via a private APN). All core apps should be updated simultaneously so that a single B2G version represents the full stack.

== Open questions ==

* How much are we testing Core app updates before delivering these updates to the APN?
** This will be tested at the same level we are testing starndard 3G connectivity to the carrier network? From CLee's etherpad outline...
* Same questions from Gecko apply here:
* What is the sequence of events (eg: prompt user to restart device, whereupon install process runs?)
** How different is process from Gecko updates?
* How often should we check for updates?
* Will there be a back-up instance of Gaia in event of failed updates? If so, what will sequence of it's application be?
* Does being on 3G/Edge affect when we check for Gecko updates?
** Should not, since updates will be free OTA via Carrier's private APN.
* What—if anything—should we tell the user when a Gecko updated is detected? Should we behave differently if the user is on 3G/Edge connection when we detect that an update is available?
** Download update and apply silently in background?
* Do we have the technical ability to download the update in the background and only notify the user once the new version is available?
* Should we do anything special if the phone has been turned off for a few days and is then started?
* Do we need to have a mechanism for pushing extra-critical updates?
* Should we inform users about how big updates will be before downloading them? Do we have the ability to tell before doing the actual download?
* Do we require the user to plug in the phone if battery is below X %?
* What prompts do we present to user?
* Do we have a rollback strategy for failed installs? Previous April discussion w/ cjones indicated no...
* What is time to install? Several minutes?
* Can we avoid user friction by downloading silently, and only during periods of user inactivity? Would not want to slow down web browsing while update processed in background, for example.
* How many device reboots are required in the process?
* Do we provide link to changelog so user can review update details before installing?
* How large are these updates?
* Do we check for available device storage before downloading? If insufficient, how do we mitigate?
* If the user powers down the device while an update is silently downloading in background, can we resume download later on?
* How much user agency do we provide over installs? Can they defer? For how long? What affordances do we make for out of date Gaia + Core apps?
* How can the user review the currently-installed version? From Settings?

= App Updates =

== Introduction ==

Apps can be divided into two categories, each with their own update policies.

* Core apps
* Pre-installed 3rd party apps
* User-installed apps

== Core apps ==

=== About ===

* Are all packaged apps
* Are pre-installed with the OS
* Are not user-removable
* Will survive a factory reset
** We ensure that Core apps are available after a factory reset by storing them in the System partition, in /system/b2g/webapps, instead of the usual /data/local/webapps.

=== Updates ===

* Core apps updates are bundled with Gecko updates, and are therefore governed by Gecko update policies.

== Pre-installed third party apps ==

=== About ===

* These are 3rd party apps that come bundled with the phone.
* Are governed by same rules as User-installed apps.

=== Updates ===

* Are governed by same rules as User-installed apps.

=== Open questions ===

* Can these be uninstalled by the user
* What happens with these on a factory reset? Are they removed if installed? Re-spawn if uninstalled?

== User-installed apps ==

=== About ===

* Can be packaged or non-packaged
** Differences between packaged and non-packaged apps should generally not be surfaced to the user.
** For both types, we ensure that they stay up-to-date by checking for new versions at regular intervals.
* Updates are not be free and will incur data charges when on the carrier’s network.

=== Non-packaged app updates ===

* Non-packaged apps can specify the location of an offline-cache manifest to be loaded at install time. This offline-cache is subsequently updated.
* Update availability is checked by polling the developer website.
* We don't yet have the ability to tell a packaged app that an update is available.

=== Packaged app updates ===

* Update availability is checked by polling the store to see whether a new package available.
* We also have the ability to tell the app that an update is available.

=== Deferred download ===

* We have the ability to download and install app updates while the previous versions are running. The new version is made available on app restart.

=== Open questions ===

* How often should we check for app update?
** Once a day, only on WiFi?
* Does the frequency of usage affect how often we check for app updates?
* Does being on 3G/Edge affect when we check for app updates?
* What should we tell the user when an app update is detected?
* What should we tell the user when an app update is detected while the app is running, or should we rely on the app to do so? (note that while we can inform a running app about an update being available, we can't detect if the app is actually doing anything useful with that information)
* Should we behave differently if the user is on 3G/Edge connection when we detect that an update is available?
* Can the user inspect permissions enumerated in the app at the time of installation? Should we let the user know if an update expands the list of permissions?
* Do we need to have a mechanism for pushing extra-critical updates?
* Should we inform users about how big updates will be before downloading them?
** For un-packaged apps we generally can't tell how big an update is going to be. We could implement mechanisms for doing estimates, but we don't have anything right now
** For packaged apps we could implement such a mechanism, but it depends on the protocols we use (see below):
** What protocol should we use for detecting that an app update is available and downloading the update? This is a question we need to hammer out with the store people and the AMO people who have a lot of experience with updates for addons. The last two solutions involve new server-side APIs to be defined, but could potentially be more efficient. Three possibilities which have been discussed:
*** Check if the HTTP Etag of the package has changed by sending a conditional HTTP request with a If-None-Match header. This is what the work-in-progresss implementation in bug 772364 is doing.
*** Group all the applications by store, and send to each store the list to check with ones to update. This could also return hashes for the new packages which could be safely downloaded from mirrors.
*** If the user has authentication credentials with a store, use a store specific api to get a list of updated applications.
* Should we enable batch download of updates?
* Should we indicate download+install progress to user?
* Should we surface "this app has been updated" information to user?
* Do we create user configuration options? eg:
** Download and install apps in background.
* How do we ensure backwards compatibility for apps that cannot update? eg: User is on Edge connection and rarely accesses via WiFi. Would their apps stop working once they are out of date?

== mozApps API Changes ==

To support the previously described behaviour, we need a couple of
additions to the content facing mozApps API, on the Application object:

* Add a |readonly boolean removable| property.
* Add a |DOMEventListener onupdated| event listener to be notified when an application has been updated. This let a dashboard update any displayed item that could have changed (icon, application name, etc.)

=== Open questions: ===

* Do we also need an event signaling that an update is available?
* Do we also need an event signaling that an update has been downloaded?

Gaia/System/Updates

2012-08-08T16:27:45Z

Marshall law: /* Introduction */

= Overview =

There are several types of FxOS updates:

* Gonk (Kernel)
* Gecko
* Gaia
* Apps
** Core
** Pre-installed third party
** User-installed
*** Packaged
*** Non-packaged

== Foundational principles ==

=== Security ===
The reason that we want to push updates pretty aggressively is in part security. One of the main sources of hacked computers is people running old versions of software with known security issues. Mozilla has for a long time been pushing as one of the main security benefits of Firefox our ability to update a large percentage of people's installed versions quickly.

=== Data consumption control ===
One of the big benefits of Firefox OS that we are going to try to push is the ability to keep costly data transfers down. Hence we want to avoid large downloads while the user is paying a lot of money for each byte.

=== Low friction ===
We reduce user friction by minimizing and automating updates as much as possible.

== High level requirements ==

* User can update system software
* User can update installed Apps
* User can be notified of available updates
* User can use device and apps while download is in progress
* User can be notified of insufficient disk space to download update
* User can be notified of insufficient battery life to conduct update
* User can review update file size before and after install
* User can review update details before and after install

== Development/Software Channels ==

* The requirement is to offer 3 channels for delivering the B2G software stack to users. Each channel will include consistent versions of Gonk, Gecko and Gaia. The proposed channels are:
** Nightly
** Beta
*** Weekly stable builds that users can stay on to get the latest bugs fixes and feature enhancements.
** Release
* All phones manufactured should default to the Release channel.

== References ==

* [https://etherpad.mozilla.org/B2G-software-updates B2G Software Updates]: Etherpad, Chris Lee
* [https://docs.google.com/spreadsheet/ccc?key=0AiBigu584YY7dGlNSlY0QzhJb3M5anRBa1gxalV0Y3c&pli=1#gid=10 Software Update]: Google Doc spreadsheet
* [https://docs.google.com/spreadsheet/ccc?key=0AiBigu584YY7dGlNSlY0QzhJb3M5anRBa1gxalV0Y3c&pli=1#gid=15 Software Update Policy]: Google Doc spreadsheet
* [https://bugzilla.mozilla.org/show_bug.cgi?id=780662 basecamp-update tracking bug]

= Gonk (Kernel) Updates =

== Introduction ==

* Changes to this layer in the software stack should only be made when it is absolutely necessary. The requirement here is to ensure a stable build at this level of the software to minimize any issues with the phone at the Gaia level.
* The update process proposal is take planned fixes here 1 time per quarter and only urgent security/showstopper bugs immediately as needed (and as per our agreement with the carrier partner).
* Based on a mutual agreement, the OEM or Mozilla will need to host the FOTA servers to support Kernel updates
* We cannot guarantee user data and device operability is restored to previous version in event of interrupted or corrupted install.

== Open questions ==

* OTA system updates are high risk because it is possible to brick the device in the process, correct? If so, how do we mitigate that risk?
* What is the sequence of events (eg: prompt user to restart device, whereupon install process runs?)
* Do we require the user to plug in the phone if battery is below X %?
** (sicking) This is somewhat technically doable, but a UX decision if we actually want to. What we can't do is estimate how good the battery is. I think an old "worn out" battery will fall much quicker in battery level than a new one. It's also hard to get a good estimate of how much battery is needed, but we can certainly require battery levels much higher than what's needed (say 30%).
* What prompts do we present to user?
* Do we have a rollback strategy for failed installs? Previous April discussion w/ cjones indicated no...
* What is time to install? Several minutes?
* Can we avoid user friction by downloading silently, and only during periods of user inactivity? Would not want to slow down web browsing while update processed in background, for example.
** (sicking) We don't have good mechanisms for giving lower priority or throttling individual channels in Necko right now. We technically could detect other downloads starting through and abort the update in that case, and then resume once we detect user inactivity.
* How many reboots are required in the process? Previous April discussion w/ cjones indicated two.
* Do we provide link to changelog so user can review update details before installing?
** (sicking) I think this is up to UX to set requirements. Seems technically feasible, but I'm not convinced it's needed given that in every instance we'll likely want to apply the update for security reasons.
* How large are these updates?
* Do we check for available device storage before downloading? If insufficient, how do we mitigate?
* If the user powers down the device while an update is silently downloading in background, can we resume download later on?
** (sicking) Necko has the ability to download ranges, but this also needs server support. We certainly could require such support though.
* How much user agency do we provide over installs? Can they defer? For how long? What affordances do we make for out of date software?
* How can the user review the currently-installed version? From Settings?

= Gecko Updates =

== Introduction ==
* See the B2G Gecko update meta bug here: https://bugzilla.mozilla.org/show_bug.cgi?id=715816
* Gecko updates can happen more frequently than Kernel updates. Based on input from carriers and OEMs, it likely updates at this layer will need to happen somewhere between the current Desktop 6-week train interval and ESR (every 42 weeks).
* The proposed requirement here is to offer regular updates every 18 weeks. This frequency offers Mozilla and our partners the ability to update functionality on the device at a quicker pace than other competitor OS stacks (iOS and Android), but at the same time not overwhelm our Carrier partners who may not be used to updating software so frequently.
* Other requirements here are to offer a back-up instance of Gecko to ensure we can failover when necessary (if we somehow shipped an updated Gecko version that resulted in a bug).
* The updates at the Gecko level should happen silently where the user is not aware of when this is happening.
* The user will not be charged any carrier network fees for any Gecko update (as agreed upon by Telefonica) given they will be making these updates via a private APN.
* The user should be able to go into Settings > About to determine the version of the software the are using in order to debug and/or get support for any issue they encounter.

== Open questions ==

* What is the sequence of events (eg: prompt user to restart device, whereupon install process runs?)
** How different is process from Gonk updates?
* How often should we check for Gecko update?
** Every 18 weeks, according to CLee's etherpad outline...
*** (sicking) This sounds too rare given that we ship Gecko updates every 6 weeks which always contain security updates. Usually we count on security researchers being able to reverse engineer those updates and create exploits for older versions of Gecko.
* Can we confirm that there will be a back-up instance of Gecko in event of failed updates? If so, what will sequence of it's application be?
* Does being on 3G/Edge affect when we check for Gecko updates?
** Should not, since updates will be free OTA via Carrier's private APN.
* What—if anything—should we tell the user when a Gecko updated is detected? Should we behave differently if the user is on 3G/Edge connection when we detect that an update is available?
** Download update and apply silently in background, same as Gonk process? Might be too intrusive for these more frequent (18 weeks) Gecko updates?
* Do we have the technical ability to download the update in the background and only notify the user once the new version is available?
* Should we do anything special if the phone has been turned off for a few days and is then started?
* Do we need to have a mechanism for pushing extra-critical updates?
* Should we inform users about how big updates will be before downloading them? Do we have the ability to tell before doing the actual download?
* Do we require the user to plug in the phone if battery is below X %?
** (sicking) See answer for Gonk
* What prompts do we present to user?
* Do we have a rollback strategy for failed installs? Previous April discussion w/ cjones indicated no...
* What is time to install? Several minutes?
* Can we avoid user friction by downloading silently, and only during periods of user inactivity? Would not want to slow down web browsing while update processed in background, for example.
* How many device reboots are required in the process?
* Do we provide link to changelog so user can review update details before installing?
** (sicking) See answer for Gonk
* How large are these updates?
* Do we check for available device storage before downloading? If insufficient, how do we mitigate?
* If the user powers down the device while an update is silently downloading in background, can we resume download later on?
** (sicking) See answer for Gonk
* How much user agency do we provide over installs? Can they defer? For how long? What affordances do we make for out of date Gecko?
* How can the user review the currently-installed version? From Settings?

= Gaia Updates =

== Introduction ==

* Gaia updates are related to anything that may modify the user interface and experience of the OS. The update interval will also be every 18-weeks to align with Gecko updates.
* Updates that happen to the Core Apps (Dialer, SMS, Camera, etc.) will happen silently and users will not be charged any carrier network fees for Gaia System and Core App updates (similar to Gecko updates via a private APN). All core apps should be updated simultaneously so that a single B2G version represents the full stack.

== Open questions ==

* How much are we testing Core app updates before delivering these updates to the APN?
** This will be tested at the same level we are testing starndard 3G connectivity to the carrier network? From CLee's etherpad outline...
* Same questions from Gecko apply here:
* What is the sequence of events (eg: prompt user to restart device, whereupon install process runs?)
** How different is process from Gecko updates?
* How often should we check for updates?
* Will there be a back-up instance of Gaia in event of failed updates? If so, what will sequence of it's application be?
* Does being on 3G/Edge affect when we check for Gecko updates?
** Should not, since updates will be free OTA via Carrier's private APN.
* What—if anything—should we tell the user when a Gecko updated is detected? Should we behave differently if the user is on 3G/Edge connection when we detect that an update is available?
** Download update and apply silently in background?
* Do we have the technical ability to download the update in the background and only notify the user once the new version is available?
* Should we do anything special if the phone has been turned off for a few days and is then started?
* Do we need to have a mechanism for pushing extra-critical updates?
* Should we inform users about how big updates will be before downloading them? Do we have the ability to tell before doing the actual download?
* Do we require the user to plug in the phone if battery is below X %?
* What prompts do we present to user?
* Do we have a rollback strategy for failed installs? Previous April discussion w/ cjones indicated no...
* What is time to install? Several minutes?
* Can we avoid user friction by downloading silently, and only during periods of user inactivity? Would not want to slow down web browsing while update processed in background, for example.
* How many device reboots are required in the process?
* Do we provide link to changelog so user can review update details before installing?
* How large are these updates?
* Do we check for available device storage before downloading? If insufficient, how do we mitigate?
* If the user powers down the device while an update is silently downloading in background, can we resume download later on?
* How much user agency do we provide over installs? Can they defer? For how long? What affordances do we make for out of date Gaia + Core apps?
* How can the user review the currently-installed version? From Settings?

= App Updates =

== Introduction ==

Apps can be divided into two categories, each with their own update policies.

* Core apps
* Pre-installed 3rd party apps
* User-installed apps

== Core apps ==

=== About ===

* Are all packaged apps
* Are pre-installed with the OS
* Are not user-removable
* Will survive a factory reset
** We ensure that Core apps are available after a factory reset by storing them in the System partition, in /system/b2g/webapps, instead of the usual /data/local/webapps.

=== Updates ===

* Core apps updates are bundled with Gecko updates, and are therefore governed by Gecko update policies.

== Pre-installed third party apps ==

=== About ===

* These are 3rd party apps that come bundled with the phone.
* Are governed by same rules as User-installed apps.

=== Updates ===

* Are governed by same rules as User-installed apps.

=== Open questions ===

* Can these be uninstalled by the user
* What happens with these on a factory reset? Are they removed if installed? Re-spawn if uninstalled?

== User-installed apps ==

=== About ===

* Can be packaged or non-packaged
** Differences between packaged and non-packaged apps should generally not be surfaced to the user.
** For both types, we ensure that they stay up-to-date by checking for new versions at regular intervals.
* Updates are not be free and will incur data charges when on the carrier’s network.

=== Non-packaged app updates ===

* Non-packaged apps can specify the location of an offline-cache manifest to be loaded at install time. This offline-cache is subsequently updated.
* Update availability is checked by polling the developer website.
* We don't yet have the ability to tell a packaged app that an update is available.

=== Packaged app updates ===

* Update availability is checked by polling the store to see whether a new package available.
* We also have the ability to tell the app that an update is available.

=== Deferred download ===

* We have the ability to download and install app updates while the previous versions are running. The new version is made available on app restart.

=== Open questions ===

* How often should we check for app update?
** Once a day, only on WiFi?
* Does the frequency of usage affect how often we check for app updates?
* Does being on 3G/Edge affect when we check for app updates?
* What should we tell the user when an app update is detected?
* What should we tell the user when an app update is detected while the app is running, or should we rely on the app to do so? (note that while we can inform a running app about an update being available, we can't detect if the app is actually doing anything useful with that information)
* Should we behave differently if the user is on 3G/Edge connection when we detect that an update is available?
* Can the user inspect permissions enumerated in the app at the time of installation? Should we let the user know if an update expands the list of permissions?
* Do we need to have a mechanism for pushing extra-critical updates?
* Should we inform users about how big updates will be before downloading them?
** For un-packaged apps we generally can't tell how big an update is going to be. We could implement mechanisms for doing estimates, but we don't have anything right now
** For packaged apps we could implement such a mechanism, but it depends on the protocols we use (see below):
** What protocol should we use for detecting that an app update is available and downloading the update? This is a question we need to hammer out with the store people and the AMO people who have a lot of experience with updates for addons. The last two solutions involve new server-side APIs to be defined, but could potentially be more efficient. Three possibilities which have been discussed:
*** Check if the HTTP Etag of the package has changed by sending a conditional HTTP request with a If-None-Match header. This is what the work-in-progresss implementation in bug 772364 is doing.
*** Group all the applications by store, and send to each store the list to check with ones to update. This could also return hashes for the new packages which could be safely downloaded from mirrors.
*** If the user has authentication credentials with a store, use a store specific api to get a list of updated applications.
* Should we enable batch download of updates?
* Should we indicate download+install progress to user?
* Should we surface "this app has been updated" information to user?
* Do we create user configuration options? eg:
** Download and install apps in background.
* How do we ensure backwards compatibility for apps that cannot update? eg: User is on Edge connection and rarely accesses via WiFi. Would their apps stop working once they are out of date?

== mozApps API Changes ==

To support the previously described behaviour, we need a couple of
additions to the content facing mozApps API, on the Application object:

* Add a |readonly boolean removable| property.
* Add a |DOMEventListener onupdated| event listener to be notified when an application has been updated. This let a dashboard update any displayed item that could have changed (icon, application name, etc.)

=== Open questions: ===

* Do we also need an event signaling that an update is available?
* Do we also need an event signaling that an update has been downloaded?

WebAPI/WebMobileConnection

2012-06-06T15:12:09Z

Marshall law: /* Proposed API */

This exposes information about the current mobile voice and data connection to (certain) HTML content. The primary use case for this is the status bar of the main phone UI. It typically shows the operator name, signal strength, data connection type, etc.
This API also includes ICC-related (SIM/RUIM card) functionalities, such as :
* entering PIN, PIN2, PUK, PUK2 to unlock various states of the SIM card.
* changing the PIN (also serves as enabling/disabling the PIN lock.)

== Status ==

* Implemented in {{bug|729173}}. <br>
* ICC lock(PIN/PIN2/PUK/PUK2) is implemented in {{Bug|729173}}. <br>
* getNetworks() and WebMobileOperatorInfo were added in {{Bug|744344}}

== Proposed API ==

interface MobileConnection : EventTarget
{
/**
* Indicates the state of the device's ICC card.
*
* Possible values: 'unavailable', 'absent', 'pin_required', 'puk_required',
* 'network_locked', 'not_ready', 'ready'.
*/
readonly attribute string cardState;

/**
* Information about the voice connection.
*/
readonly attribute MobileConnectionInfo voice;

/**
* Information about the data connection.
*/
readonly attribute MobileConnectionInfo data;

/**
* The 'cardstatechange' event is notified when the 'cardState' attribute
* changes value.
*/
attribute EventListener oncardstatechange;

/**
* The 'voicechange' event is notified whenever the voice connection object
* changes.
*/
attribute EventListener onvoicechange;

/**
* The 'datachange' event is notified whenever the data connection object
* changes values.
*/
attribute EventListener ondatachange;

/**
* Search for available networks.
*
* If successful, the request's onsuccess will be called, and the request's
* result will be an array of MobileOperatorInfo.
*
* Otherwise, the request's onerror will be called, and the request's error
* will be either 'RadioNotAvailable', 'RequestNotSupported', or 'GenericFailure'.
*/
DOMRequest getNetworks();

/**
* Find out about the status of an ICC lock (e.g. the PIN lock).
*
* @param lockType
* Identifies the lock type, e.g. "pin" for the PIN lock.
*
* @return a DOM Request.
* The request's result will be an object containing
* information about the specified lock's status,
* e.g. {lockType: "pin", enabled: true}.
*/
DOMRequest getCardLock(DOMString lockType);

/**
* Unlock a card lock.
*
* @param info
* An object containing the information necessary to unlock
* the given lock. At a minimum, this object must have a
* "lockType" attribute which specifies the type of lock, e.g.
* "pin" for the PIN lock. Other attributes are dependent on
* the lock type.
*
* Examples:
*
* (1) Unlocking the PIN:
*
* unlockCardLock({lockType: "pin",
* pin: "..."});
*
* (2) Unlocking the PUK and supplying a new PIN:
*
* unlockCardLock({lockType: "puk",
* puk: "...",
* newPin: "..."});
*
* @return a DOMRequest.
* The request's result will be an object containing
* information about the unlock operation.
*
* Examples:
*
* (1) Unlocking failed:
*
* {
* lockType: "pin",
* result: false,
* retryCount: 2
* }
*
* (2) Unlocking succeeded:
*
* {
* lockType: "pin",
* result: true
* }
*/
DOMRequest unlockCardLock(Object info);

/**
* Modify the state of a card lock.
*
* @param info
* An object containing information about the lock and
* how to modify its state. At a minimum, this object
* must have a "lockType" attribute which specifies the
* type of lock, e.g. "pin" for the PIN lock. Other
* attributes are dependent on the lock type.
*
* Examples:
*
* (1) Disabling the PIN lock:
*
* setCardLock({lockType: "pin",
* pin: "...",
* enabled: false});
*
* (2) Changing the PIN:
*
* setCardLock({lockType: "pin",
* pin: "...",
* newPin: "..."});
*
* @return a DOMRequest.
* The request's result will be an object containing
* information about the operation.
*
* Examples:
*
* (1) Enabling/Disabling card lock failed or change card lock failed.
*
* {
* lockType: "pin",
* result: false,
* retryCount: 2
* }
*
* (2) Enabling/Disabling card lock succeed or change card lock succeed.
*
* {
* lockType: "pin",
* result: true
* }
*/
DOMRequest setCardLock(Object info);

};

interface MobileConnectionInfo
{
/**
* Indicates whether the device is connected to a mobile network.
*/
readonly attribute bool connected;

/**
* Indicates whether only emergency calls are possible.
*
* This flag is only relevant to voice connections and when 'connected' is
* false.
*/
readonly attribute bool emergencyCallsOnly;

/**
* Indicates whether the connection is going through a foreign operator
* (roaming) or not.
*/
readonly attribute bool roaming;

/**
* Network operator
*/
readonly attribute DOMString operator;

/**
* Type of connection.
*
* Possible values: 'gsm', 'cdma', gprs', 'edge', 'umts', 'hsdpa', 'evdo0',
* 'evdoa', 'evdob', etc.
*/
readonly attribute DOMString type;

/**
* Signal strength in dBm, or null if no service is available.
*/
readonly attribute int signalStrength;

/**
* Signal strength, represented linearly as a number between 0 (weakest
* signal) and 100 (full signal).
*/
readonly attribute int relSignalStrength;

};

interface MobileOperatorInfo
{
/**
* Short name of the network operator
*/
readonly attribute DOMString shortName;

/**
* Long name of the network operator
*/
readonly attribute DOMString longName;

/**
* Mobile Country Code (MCC) of the network operator
*/
readonly attribute unsigned short mcc;

/**
* Mobile Network Code (MNC) of the network operator
*/
readonly attribute unsigned short mnc;

/**
* State of this network operator.
*
* Possible values: 'available', 'connected', 'forbidden', or null (unknown)
*/
readonly attribute DOMString state;
};

== Other radio-related functionality ==

The following radio/mobile connection related features will be exposed as settings in [[SettingsAPI]]:

* radio on/off (e.g. for aeroplane mode)
* caller ID on/off/provider default (called "CLIR" in TS 27.007)
* call forwarding preferences
* manual override for operator selection

There are also some more features of the radio that should be exposed to (privileged) content in some shape or form:

* ICC-related (SIM/RUIM card)
** own phone number and other ICC I/O related features.(Currently these information are not exposed in WebAPI, see {{Bug|736941}}.)
* device-related
** get IMEI, IMEISV
** depersonalize (remove network lock)
** baseband-related information and features

The latter, device-related features seem to be more exotic than the ICC-related ones and hopefully also mostly unnecessary. The question remains where these APIs should live.

WebAPI/WebMobileConnection

2012-06-06T14:57:49Z

Marshall law: /* Status */

This exposes information about the current mobile voice and data connection to (certain) HTML content. The primary use case for this is the status bar of the main phone UI. It typically shows the operator name, signal strength, data connection type, etc.
This API also includes ICC-related (SIM/RUIM card) functionalities, such as :
* entering PIN, PIN2, PUK, PUK2 to unlock various states of the SIM card.
* changing the PIN (also serves as enabling/disabling the PIN lock.)

== Status ==

* Implemented in {{bug|729173}}. <br>
* ICC lock(PIN/PIN2/PUK/PUK2) is implemented in {{Bug|729173}}. <br>
* getNetworks() and WebMobileOperatorInfo were added in {{Bug|744344}}

== Proposed API ==

interface MobileConnection : EventTarget
{
/**
* Indicates the state of the device's ICC card.
*
* Possible values: 'unavailable', 'absent', 'pin_required', 'puk_required',
* 'network_locked', 'not_ready', 'ready'.
*/
readonly attribute string cardState;

/**
* Indicates whether the device is connected to a mobile network.
*/
readonly attribute bool connected;

/**
* Indicates whether emergency calls are possible.
*
* This flag is only relevant when 'connected' is false.
*/
readonly attribute bool emergencyCallsPossible;

/**
* Indicates whether the connection is going through a foreign operator
* (roaming) or not.
*/
readonly attribute bool roaming;

/**
* Operator name.
*/
readonly attribute string operator?;

/**
* Type of connection.
*
* Possible values: 'gprs', 'edge', 'umts', 'hsdpa', 'evdo0', 'evdoa', 'evdob', etc.
*/
readonly attribute string type?;

/**
* Signal strength, represented linearly as a number between 0 (weakest signal) and 1.0
* (full signal).
*/
readonly attribute float signalStrength?;

/**
* Signal strength in dBm, or null if no service is available.
*/
readonly attribute short signalStrengthDbm?;

/**
* Search for available networks.
*
* If successful, the request's onsuccess will be called, and the request's
* result will be an array of MobileOperatorInfo.
*
* Otherwise, the request's onerror will be called, and the request's error
* will be either 'RadioNotAvailable', 'RequestNotSupported', or 'GenericFailure'.
*/
DOMRequest getNetworks();

/**
* The 'cardstatechange' event is notified when the 'cardState' attribute
* changes value.
*/
attribute EventListener oncardstatechange;

/**
* The 'connectionchange' event is notified whenever one of the 'connected',
* 'roaming', 'operator', 'type' attributes change, since typically many or
* all of them change together.
*/
attribute EventListener onconnectionchange;

/**
* The 'signalstrengthchange' event is notified whenever the signal strength
* changes value. The 'bars' attribute is updated accordingly.
*/
attribute EventListener onsignalstrengthchange;

/**
* Find out about the status of an ICC lock (e.g. the PIN lock).
*
* @param lockType
* Identifies the lock type, e.g. "pin" for the PIN lock.
*
* @return a DOM Request.
* The request's result will be an object containing
* information about the specified lock's status,
* e.g. {lockType: "pin", enabled: true}.
*/
DOMRequest getCardLock(in DOMString lockType);

/**
* Unlock a card lock.
*
* @param info
* An object containing the information necessary to unlock
* the given lock. At a minimum, this object must have a
* "lockType" attribute which specifies the type of lock, e.g.
* "pin" for the PIN lock. Other attributes are dependent on
* the lock type.
*
* Examples:
*
* (1) Unlocking the PIN:
*
* unlockCardLock({lockType: "pin",
* pin: "..."});
*
* (2) Unlocking the PUK and supplying a new PIN:
*
* unlockCardLock({lockType: "puk",
* puk: "...",
* newPin: "..."});
*
* @return a nsIDOMDOMRequest.
* The request's result will be an object containing
* information about the unlock operation.
*
* Examples:
*
* (1) Unlocking failed:
*
* {
* lockType: "pin",
* result: false,
* retryCount: 2
* }
*
* (2) Unlocking succeeded:
*
* {
* lockType: "pin",
* result: true
* }
*/
DOMRequest unlockCardLock(in jsval info);

/**
* Modify the state of a card lock.
*
* @param info
* An object containing information about the lock and
* how to modify its state. At a minimum, this object
* must have a "lockType" attribute which specifies the
* type of lock, e.g. "pin" for the PIN lock. Other
* attributes are dependent on the lock type.
*
* Examples:
*
* (1) Disabling the PIN lock:
*
* setCardLock({lockType: "pin",
* pin: "...",
* enabled: false});
*
* (2) Changing the PIN:
*
* setCardLock({lockType: "pin",
* pin: "...",
* newPin: "..."});
*
* @return a nsIDOMDOMRequest.
* The request's result will be an object containing
* information about the operation.
*
* Examples:
*
* (1) Enabling/Disabling card lock failed or change card lock failed.
*
* {
* lockType: "pin",
* result: false,
* retryCount: 2
* }
*
* (2) Enabling/Disabling card lock succeed or change card lock succeed.
*
* {
* lockType: "pin",
* result: true
* }
*/
DOMRequest setCardLock(in jsval info);

};

== Other radio-related functionality ==

The following radio/mobile connection related features will be exposed as settings in [[SettingsAPI]]:

* radio on/off (e.g. for aeroplane mode)
* caller ID on/off/provider default (called "CLIR" in TS 27.007)
* call forwarding preferences
* manual override for operator selection

There are also some more features of the radio that should be exposed to (privileged) content in some shape or form:

* ICC-related (SIM/RUIM card)
** own phone number and other ICC I/O related features.(Currently these information are not exposed in WebAPI, see {{Bug|736941}}.)
* device-related
** get IMEI, IMEISV
** depersonalize (remove network lock)
** baseband-related information and features

The latter, device-related features seem to be more exotic than the ICC-related ones and hopefully also mostly unnecessary. The question remains where these APIs should live.

WebAPI/WebMobileConnection

2012-06-06T14:51:46Z

Marshall law: /* Proposed API */

This exposes information about the current mobile voice and data connection to (certain) HTML content. The primary use case for this is the status bar of the main phone UI. It typically shows the operator name, signal strength, data connection type, etc.
This API also includes ICC-related (SIM/RUIM card) functionalities, such as :
* entering PIN, PIN2, PUK, PUK2 to unlock various states of the SIM card.
* changing the PIN (also serves as enabling/disabling the PIN lock.)

== Status ==

Implemented in {{bug|729173}}. <br>
ICC lock(PIN/PIN2/PUK/PUK2) is implemented in {{Bug|729173}}.

== Proposed API ==

interface MobileConnection : EventTarget
{
/**
* Indicates the state of the device's ICC card.
*
* Possible values: 'unavailable', 'absent', 'pin_required', 'puk_required',
* 'network_locked', 'not_ready', 'ready'.
*/
readonly attribute string cardState;

/**
* Indicates whether the device is connected to a mobile network.
*/
readonly attribute bool connected;

/**
* Indicates whether emergency calls are possible.
*
* This flag is only relevant when 'connected' is false.
*/
readonly attribute bool emergencyCallsPossible;

/**
* Indicates whether the connection is going through a foreign operator
* (roaming) or not.
*/
readonly attribute bool roaming;

/**
* Operator name.
*/
readonly attribute string operator?;

/**
* Type of connection.
*
* Possible values: 'gprs', 'edge', 'umts', 'hsdpa', 'evdo0', 'evdoa', 'evdob', etc.
*/
readonly attribute string type?;

/**
* Signal strength, represented linearly as a number between 0 (weakest signal) and 1.0
* (full signal).
*/
readonly attribute float signalStrength?;

/**
* Signal strength in dBm, or null if no service is available.
*/
readonly attribute short signalStrengthDbm?;

/**
* Search for available networks.
*
* If successful, the request's onsuccess will be called, and the request's
* result will be an array of MobileOperatorInfo.
*
* Otherwise, the request's onerror will be called, and the request's error
* will be either 'RadioNotAvailable', 'RequestNotSupported', or 'GenericFailure'.
*/
DOMRequest getNetworks();

/**
* The 'cardstatechange' event is notified when the 'cardState' attribute
* changes value.
*/
attribute EventListener oncardstatechange;

/**
* The 'connectionchange' event is notified whenever one of the 'connected',
* 'roaming', 'operator', 'type' attributes change, since typically many or
* all of them change together.
*/
attribute EventListener onconnectionchange;

/**
* The 'signalstrengthchange' event is notified whenever the signal strength
* changes value. The 'bars' attribute is updated accordingly.
*/
attribute EventListener onsignalstrengthchange;

/**
* Find out about the status of an ICC lock (e.g. the PIN lock).
*
* @param lockType
* Identifies the lock type, e.g. "pin" for the PIN lock.
*
* @return a DOM Request.
* The request's result will be an object containing
* information about the specified lock's status,
* e.g. {lockType: "pin", enabled: true}.
*/
DOMRequest getCardLock(in DOMString lockType);

/**
* Unlock a card lock.
*
* @param info
* An object containing the information necessary to unlock
* the given lock. At a minimum, this object must have a
* "lockType" attribute which specifies the type of lock, e.g.
* "pin" for the PIN lock. Other attributes are dependent on
* the lock type.
*
* Examples:
*
* (1) Unlocking the PIN:
*
* unlockCardLock({lockType: "pin",
* pin: "..."});
*
* (2) Unlocking the PUK and supplying a new PIN:
*
* unlockCardLock({lockType: "puk",
* puk: "...",
* newPin: "..."});
*
* @return a nsIDOMDOMRequest.
* The request's result will be an object containing
* information about the unlock operation.
*
* Examples:
*
* (1) Unlocking failed:
*
* {
* lockType: "pin",
* result: false,
* retryCount: 2
* }
*
* (2) Unlocking succeeded:
*
* {
* lockType: "pin",
* result: true
* }
*/
DOMRequest unlockCardLock(in jsval info);

/**
* Modify the state of a card lock.
*
* @param info
* An object containing information about the lock and
* how to modify its state. At a minimum, this object
* must have a "lockType" attribute which specifies the
* type of lock, e.g. "pin" for the PIN lock. Other
* attributes are dependent on the lock type.
*
* Examples:
*
* (1) Disabling the PIN lock:
*
* setCardLock({lockType: "pin",
* pin: "...",
* enabled: false});
*
* (2) Changing the PIN:
*
* setCardLock({lockType: "pin",
* pin: "...",
* newPin: "..."});
*
* @return a nsIDOMDOMRequest.
* The request's result will be an object containing
* information about the operation.
*
* Examples:
*
* (1) Enabling/Disabling card lock failed or change card lock failed.
*
* {
* lockType: "pin",
* result: false,
* retryCount: 2
* }
*
* (2) Enabling/Disabling card lock succeed or change card lock succeed.
*
* {
* lockType: "pin",
* result: true
* }
*/
DOMRequest setCardLock(in jsval info);

};

== Other radio-related functionality ==

The following radio/mobile connection related features will be exposed as settings in [[SettingsAPI]]:

* radio on/off (e.g. for aeroplane mode)
* caller ID on/off/provider default (called "CLIR" in TS 27.007)
* call forwarding preferences
* manual override for operator selection

There are also some more features of the radio that should be exposed to (privileged) content in some shape or form:

* ICC-related (SIM/RUIM card)
** own phone number and other ICC I/O related features.(Currently these information are not exposed in WebAPI, see {{Bug|736941}}.)
* device-related
** get IMEI, IMEISV
** depersonalize (remove network lock)
** baseband-related information and features

The latter, device-related features seem to be more exotic than the ICC-related ones and hopefully also mostly unnecessary. The question remains where these APIs should live.

WebAPI/WebMobileConnection

2012-05-21T19:15:15Z

Marshall law: /* Proposed API */

This exposes information about the current mobile voice and data connection to (certain) HTML content. The primary use case for this is the status bar of the main phone UI. It typically shows the operator name, signal strength, data connection type, etc.

== Proposed API ==

interface MobileConnection : EventTarget
{
/**
* Indicates the state of the device's ICC card.
*
* Possible values: 'unavailable', 'absent', 'pin_required', 'puk_required',
* 'network_locked', 'not_ready', 'ready'.
*/
readonly attribute string cardState;

/**
* Indicates whether the device is connected to a mobile network.
*/
readonly attribute bool connected;

/**
* Indicates whether emergency calls are possible.
*
* This flag is only relevant when 'connected' is false.
*/
readonly attribute bool emergencyCallsPossible;

/**
* Indicates whether the connection is going through a foreign operator
* (roaming) or not.
*/
readonly attribute bool roaming;

/**
* Operator name.
*/
readonly attribute string operator?;

/**
* Type of connection.
*
* Possible values: 'gprs', 'edge', 'umts', 'hsdpa', 'evdo0', 'evdoa', 'evdob', etc.
*/
readonly attribute string type?;

/**
* Signal strength, represented linearly as a number between 0 (weakest signal) and 1.0
* (full signal).
*/
readonly attribute float signalStrength?;

/**
* Signal strength in dBm, or null if no service is available.
*/
readonly attribute short signalStrengthDbm?;

/**
* Search for available networks.
*
* If successful, the request result will be an array of operator names.
*/
DOMRequest getNetworks();

/**
* The 'cardstatechange' event is notified when the 'cardState' attribute
* changes value.
*/
attribute EventListener oncardstatechange;

/**
* The 'connectionchange' event is notified whenever one of the 'connected',
* 'roaming', 'operator', 'type' attributes change, since typically many or
* all of them change together.
*/
attribute EventListener onconnectionchange;

/**
* The 'signalstrengthchange' event is notified whenever the signal strength
* changes value. The 'bars' attribute is updated accordingly.
*/
attribute EventListener onsignalstrengthchange;

};

== Other radio-related functionality ==

The following radio/mobile connection related features will be exposed as settings in [[SettingsAPI]]:

* radio on/off (e.g. for aeroplane mode)
* caller ID on/off/provider default (called "CLIR" in TS 27.007)
* call forwarding preferences
* manual override for operator selection

There are also some more features of the radio that should be exposed to (privileged) content in some shape or form:

* ICC-related (SIM/RUIM card)
** own phone number and other ICC I/O related features
** entering PIN, PIN2, PUK, PUK2 to unlock various states of the SIM card. Entering the PIN isn't *that* exotic, actually. Some carriers deliver their SIM cards with the PIN lock enabled, for instance.
** changing the PIN (also serves as enabling/disabling the PIN lock.)
* device-related
** get IMEI, IMEISV
** depersonalize (remove network lock)
** baseband-related information and features

The latter, device-related features seem to be more exotic than the ICC-related ones and hopefully also mostly unnecessary. The question remains where these APIs should live.

== Implementation ==

See {{bug|729173}}.