Bug 1274727 - Document more details about searches core ping field. r=bnicholson
authorMichael Comella <michael.l.comella@gmail.com>
Mon, 23 May 2016 15:25:32 -0700
changeset 370275 021ff359274b008d3d9a4c74ed07a67f965a75c2
parent 370274 cf8073f1db3b9bcee2c2dc208ef22993c3f25406
child 370276 fad6d48e70f19d36638950d1709b02a227f341be
push id19026
push userbobowencode@gmail.com
push dateTue, 24 May 2016 12:34:53 +0000
reviewersbnicholson
bugs1274727
milestone49.0a1
Bug 1274727 - Document more details about searches core ping field. r=bnicholson MozReview-Commit-ID: DO8gRT8YcQm
toolkit/components/telemetry/docs/core-ping.rst
--- a/toolkit/components/telemetry/docs/core-ping.rst
+++ b/toolkit/components/telemetry/docs/core-ping.rst
@@ -42,17 +42,17 @@ Structure::
                                  // e.g. "yahoo".
       "distributionId": <string>, // Distribution identifier (optional)
       "created": <string>, // date the ping was created
                            // in local time, "yyyy-mm-dd"
       "tz": <integer>, // timezone offset (in minutes) of the
                        // device when the ping was created
       "searches": <object>, // Optional, object of search use counts in the
                             // format: { "engine.source": <pos integer> }
-                            // e.g.: { "yahoo.searchbar": 3, "other.searchbar": 1 }
+                            // e.g.: { "yahoo.suggestion": 3, "other.listitem": 1 }
       "experiments": [<string>, …], // Optional, array of identifiers
                                     // for the active experiments
     }
 
 Field details
 -------------
 
 device
@@ -108,16 +108,30 @@ all of the following events occur:
 
 #. The times.json file does not exist
 #. The package install date could not be persisted to disk
 
 The reason we don't just return the package install time even if the date could
 not be persisted to disk is to ensure the value doesn't change once we start
 sending it: we only want to send consistent values.
 
+searches
+~~~~~~~~
+In the case a search engine is added by a user, the engine identifier "other" is used, e.g. "other.<source>".
+
+Sources in Android are based on the existing UI telemetry values and are as
+follows:
+
+* actionbar: the user types in the url bar and hits enter to use the default
+  search engine
+* listitem: the user selects a search engine from the list of secondary search
+  engines at the bottom of the screen
+* suggestion: the user clicks on a search suggestion or, in the case that
+  suggestions are disabled, the row corresponding with the main engine
+
 Other parameters
 ----------------
 
 HTTP "Date" header
 ~~~~~~~~~~~~~~~~~~
 This header is used to track the submission date of the core ping in the format
 specified by
 `rfc 2616 sec 14.18 <https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.18>`_,