Firefox OS/Metrics/App Usage: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(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...")
 
No edit summary
Line 5: Line 5:
# A list of apps that have been uninstalled since the last successful report
# 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.
=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:


=Example JSON payload=
* 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>
<code><pre>
POST https://fxos.telemetry.mozilla.org/submit/telemetry/metrics/FirefoxOS/appusage
{
{
      start: timestamp of batch start time (in millisecond format),
    "apps": {
      stop: timestamp of batch end time,
        "app://verticalhome.gaiamobile.org/manifest.webapp": {
      deviceID: "0i9n4ffh" // a unique id used to link batches together,
            "activities": {},
      locale: "en_US" // the user's language from navigator.language,
            "installs": 0,
      screen: {
            "invocations": 1,
        width: the screen width in css pixels,
            "uninstalls": 0,
        height: the screen height in css pixels,
            "usageTime": 23
         devicePixelRatio: device pixels per css pixel
         }
      },
    },
      deviceinfo: {
    "deviceID": "j2670k6q",
         'deviceinfo.update_channel': update channel,
    "deviceinfo": {
         'deviceinfo.platform_version': gecko version number (I think)
         "developer.menu.enabled": true,
         'deviceinfo.platform_build_id': more version details,
         "deviceinfo.platform_build_id": "20140902135234",
         'developer.menu.enabled': if true user probably has abnormal app usage patterns!
         "deviceinfo.platform_version": "34.0a1",
      },
         "deviceinfo.update_channel": "unknown"
      apps: {
    },
        // the properties of this object are application origins and the values of those properties are
    "locale": "en-US",
        // the usage data for those applications.  For example:
    "screen": {
        'homescreen.gaiamobile.org': {
        "devicePixelRatio": 1.5,
          usageTime: total app usage time during this reporting period, in seconds
        "height": 569,
          invocations: number of times the app has been opened in this period
        "width": 320
          installs: number of times this app has been installed in this period
    },
          uninstalls: number of times this app has been uninstalled in this period
    "start": 1411567451826,
          activities: { // the activity handlers this app has invoked, and how many times
    "stop": 1411577295717
            'gallery.gaiamobile.org': 1,   // gallery handled an activity once
            'wallpaper.gaiamobile.org': 4  // wallpaper app handled activity 4 times
          }
        },
        // more app data here
      }
}
}
</pre></code>
</pre></code>

Revision as of 17:25, 24 September 2014

Requirements

For all system and 3rd party apps, track:

  1. Total time that each app (by URL) has been actively been used (in the foreground while the screen is on)
  2. Counts for the number of times an app has been opened, closed, or crashed
  3. 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

apps Usage for each app in this batch (these are not aggregates), keyed by the app's manifest URL
installs The number of app installs
uninstalls The number of app uninstalls
invocations The number of times the app was started
usageTime The total number of seconds the app was used
deviceID 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
deviceinfo
developer.menu.enabled Whether or not this is a 'production' build
deviceinfo.platform_build_id The timestamp that gecko was built
deviceinfo.platform_version The version string of gecko
deviceinfo.update_channel Update channel used for FxOS OTA updates
locale Platform locale string, i.e. 'en-US'
screen
devicePixelRatio ratio of physical pixels to virtual pixels on the device
width screen width in CSS pixels
height screen height in CSS pixels
start UNIX device timestamp of when this batch of metrics started recording
stop UNIX device timestamp of when this batch of metrics stopped recording

Example

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
}
Retrieved from "https://wiki.allizom.org/index.php?title=Firefox_OS/Metrics/App_Usage&oldid=1017996"