Bug 1249288 - Update telemetry docs to include defaultSearch. r=gfritzsche,rnewman a=ritu
authorMichael Comella <michael.l.comella@gmail.com>
Thu, 10 Mar 2016 16:23:13 -0800
changeset 323982 a5801fb8ba648ee9a98a75479c7743d408cc43b9
parent 323981 c046a7887ffa94a050cd44455ab06a7f37e84519
child 323983 98b3c3a9c2732dd58a6e74c6d19deb53060dd5bf
push id5913
push userjlund@mozilla.com
push dateMon, 25 Apr 2016 16:57:49 +0000
treeherdermozilla-beta@dcaf0a6fa115 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersgfritzsche, rnewman, ritu
bugs1249288
milestone47.0a2
Bug 1249288 - Update telemetry docs to include defaultSearch. r=gfritzsche,rnewman a=ritu MozReview-Commit-ID: 4pihITjabns
toolkit/components/telemetry/docs/core-ping.rst
--- a/toolkit/components/telemetry/docs/core-ping.rst
+++ b/toolkit/components/telemetry/docs/core-ping.rst
@@ -20,33 +20,65 @@ Submission will be per the Edge server s
 * ``appBuildID`` is the build number
 
 Note: Counts below (e.g. search & usage times) are “since the last
 ping”, not total for the whole application lifetime.
 
 Structure::
 
     {
-      "v": 1, // ping format version
+      "v": 2, // ping format version
       "clientId": <string>, // client id, e.g.
                             // "c641eacf-c30c-4171-b403-f077724e848a"
       "seq": <positive integer>, // running ping counter, e.g. 3
       "locale": <string>, // application locale, e.g. "en-US"
       "os": <string>, // OS name.
       "osversion": <string>, // OS version.
       "device": <string>, // Build.MANUFACTURER + " - " + Build.MODEL
                           // where manufacturer is truncated to 12 characters
                           // & model is truncated to 19 characters
       "arch": <string>, // e.g. "arm", "x86"
       "profileDate": <pos integer>, // Profile creation date in days since
                                     // UNIX epoch.
+      "defaultSearch": <string>, // Identifier of the default search engine,
+                                 // e.g. "yahoo".
 
       "experiments": [<string>, …], // Optional, array of identifiers
                                     // for the active experiments
     }
 
+Field details
+-------------
+
+device
+~~~~~~
 The ``device`` field is filled in with information specified by the hardware
 manufacturer. As such, it could be excessively long and use excessive amounts
 of limited user data. To avoid this, we limit the length of the field. We're
 more likely have collisions for models within a manufacturer (e.g. "Galaxy S5"
 vs. "Galaxy Note") than we are for shortened manufacturer names so we provide
 more characters for the model than the manufacturer.
 
+defaultSearch
+~~~~~~~~~~~~~
+On Android, this field may be ``null``. To get the engine, we rely on
+``SearchEngineManager#getDefaultEngine``, which searches in several places in
+order to find the search engine identifier:
+
+* Shared Preferences
+* The distribution (if it exists)
+* The localized default engine
+
+If the identifier could not be retrieved, this field is ``null``. If the
+identifier is retrieved, we attempt to create an instance of the search
+engine from the search plugins (in order):
+
+* In the distribution
+* From the localized plugins shipped with the browser
+* The third-party plugins that are installed in the profile directory
+
+If the plugins fail to create a search engine instance, this field is also
+``null``.
+
+Version history
+---------------
+* v2: added ``defaultSearch``
+* v1: initial version