1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
Telemetry
=========
This section describes existing telemetry probes measuring interaction with
search engines.
.. toctree::
:caption: Table of Contents
telemetry
Definitions
-----------
* ``organic`` is a search that a user performs by visiting a search engine
directly.
* ``SAP`` (search access point) is a search that a user performs by visiting
via one of Firefox's access points, using the associated partner codes.
* ``sap-follow-on`` is a SAP search where the user has first accessed the site
via a SAP, and then performed an additional search.
* ``tagged`` refers to a page that is tagged with an associated partner code.
It may or may not have originated via an SAP.
* ``SERP`` refers to a search engine result page.
Search probes relevant to front-end searches
--------------------------------------------
The Address Bar is an integral part of search and has `additional telemetry of its own`_.
BrowserSearchTelemetry.jsm
~~~~~~~~~~~~~~~~~~~~~~~~~~
This telemetry is handled by `BrowserSearchTelemetry.jsm`_.
SEARCH_COUNTS - SAP usage
This histogram tracks search engines and Search Access Points. It is augmented
by multiple SAPs, including the urlbar.
It's a keyed histogram, the keys are strings made up of search engine names
and SAP names, for example ``google.urlbar``.
For each key, this records the count of searches made using that engine and SAP.
SAP names can be:
- ``alias`` This is when using an alias (like ``@google``) in the urlbar.
Note there is often confusion between the terms alias and keyword, and
they may be used inappropriately: aliases refer to search engines, while
keywords refer to bookmarks. We expect no results for this SAP in Firefox
83+, since urlbar-searchmode replaces it.
- ``abouthome``
- ``contextmenu``
- ``newtab``
- ``searchbar``
- ``system``
- ``urlbar`` Except aliases and search mode.
- ``urlbar-searchmode`` Used when the Urlbar is in search mode.
- ``webextension``
browser.engagement.navigation.*
These keyed scalars track search through different SAPs, for example the
urlbar is tracked by ``browser.engagement.navigation.urlbar``.
It counts loads triggered in a subsession from the specified SAP, broken down
by the originating action.
Possible SAPs are:
- ``urlbar`` Except search mode.
- ``urlbar_searchmode`` Used when the Urlbar is in search mode.
- ``searchbar``
- ``about_home``
- ``about_newtab``
- ``contextmenu``
- ``webextension``
- ``system`` Indicates a search from the command line.
Recorded actions may be:
- ``search``
Used for any search from ``contextmenu``, ``system`` and ``webextension``.
- ``search_alias``
For ``urlbar``, indicates the user confirmed a search through an alias.
- ``search_enter``
For ``about_home`` and ``about:newtab`` this counts any search.
For the other SAPs it tracks typing and then pressing Enter.
- ``search_formhistory``
For ``urlbar``, indicates the user picked a form history result.
- ``search_oneoff``
For ``urlbar`` or ``searchbar``, indicates the user confirmed a search
using a one-off button.
- ``search_suggestion``
For ``urlbar`` or ``searchbar``, indicates the user confirmed a search
suggestion.
navigation.search (OBSOLETE)
This is a legacy and disabled event telemetry that is currently under
discussion for removal or modernization. It can't be enabled through a pref.
it's more or less equivalent to browser.engagement.navigation, but can also
report the picked search engine.
SearchSERPTelemetry.jsm
~~~~~~~~~~~~~~~~~~~~~~~
This telemetry is handled by `SearchSERPTelemetry.jsm and the associated parent/child actors`_.
SEARCH_COUNTS - SERP results
This histogram records search counts for visits to SERP in-content pages.
For in-content searches, the format is
``<provider>.in-content:[sap|sap-follow-on|organic]:[<code>|other|none]``.
This is obsolete, browser.search.content.* should be preferred.
browser.search.content.*
These keyed scalar track counts of SERP page loads. The key format is
``<provider>:[tagged|tagged-follow-on|organic]:[<code>|other|none]``.
These will eventually replace the SEARCH_COUNTS - SERP results.
They are broken down by the originating SAP where known:
- ``urlbar`` Except search mode.
- ``urlbar_searchmode`` Used when the Urlbar is in search mode.
- ``searchbar``
- ``about_home``
- ``about_newtab``
- ``contextmenu``
- ``webextension``
- ``system`` Indicates a search from the command line.
- ``tabhistory`` Indicates a search was counted as a result of the user loading it from the tab history.
- ``reload`` Indicates a search was counted as a result of reloading the page.
- ``unknown`` Indicates the origin was unknown.
browser.search.withads.*
These keyed scalar track counts of SERP pages with adverts displayed. The key
format is ``<provider>:<tagged|organic>``.
They are broken down by the originating SAP where known, the list of SAP
is the same as for ``browser.search.content.*``.
browser.search.adclicks.*
This is the same as ```browser.search.withads.*`` but tracks counts for them
clicks of adverts on SERP pages.
browser.search.with_ads
Obsolete. This is being replaced by ``browser.search.withads.*``.
This keyed scalar records counts of SERP pages with adverts displayed.
The key format is ``<provider>:<sap|organic>``.
browser.search.ad_clicks
Obsolete. This is being replaced by ``browser.search.adclicks.*``.
Records clicks of adverts on SERP pages. The key format is
``<provider>:<sap|organic>``.
.. _additional telemetry of its own: /browser/urlbar/telemetry.html
.. _SearchSERPTelemetry.jsm and the associated parent/child actors: https://searchfox.org/mozilla-central/search?q=&path=SearchSERPTelemetry*.jsm&case=false®exp=false
.. _BrowserSearchTelemetry.jsm: https://searchfox.org/mozilla-central/source/browser/components/search/BrowserSearchTelemetry.jsm
|
