4 This section describes existing telemetry probes measuring interaction with the
7 For telemetry specific to Firefox Suggest, see the
8 :doc:`firefox-suggest-telemetry` document.
17 PLACES_AUTOCOMPLETE_1ST_RESULT_TIME_MS
18 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
20 This probe tracks the amount of time it takes to get the first result.
21 It is an exponential histogram with values between 5 and 100.
23 PLACES_AUTOCOMPLETE_6_FIRST_RESULTS_TIME_MS
24 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
26 This probe tracks the amount of time it takes to get the first six results.
27 It is an exponential histogram with values between 50 and 1000.
29 FX_URLBAR_SELECTED_RESULT_METHOD
30 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
32 This probe tracks how a result was picked by the user from the list.
33 It is a categorical histogram with these values:
36 The user pressed Enter without selecting a result first.
37 This most likely happens when the user confirms the default preselected
38 result (aka *heuristic result*), or when they select with the keyboard a
39 one-off search button and confirm with Enter.
41 The user selected a result, but not using Tab or the arrow keys, and then
42 pressed Enter. This is a rare and generally unexpected event, there may be
43 exotic ways to select a result we didn't consider, that are tracked here.
44 Look at arrowEnterSelection and tabEnterSelection for more common actions.
46 The user clicked on a result.
47 - ``arrowEnterSelection``
48 The user selected a result using the arrow keys, and then pressed Enter.
49 - ``tabEnterSelection``
50 The first key the user pressed to select a result was the Tab key, and then
51 they pressed Enter. Note that this means the user could have used the arrow
52 keys after first pressing the Tab key.
54 Before QuantumBar, it was possible to right-click a result to highlight but
55 not pick it. Then the user could press Enter. This is no more possible.
57 FX_URLBAR_ZERO_PREFIX_DWELL_TIME_MS
58 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
60 This probe records the amount of time the zero-prefix view was shown; that is,
61 the time from when it was opened to the time it was closed. "Zero-prefix"
62 means the search string was empty, so the zero-prefix view is the view that's
63 shown when the user clicks in the urlbar before typing a search string. Often
64 it's also called the "top sites" view since normally it shows the user's top
65 sites. This is an exponential histogram whose values range from 0 to 60,000
66 with 50 buckets. Values are in milliseconds. This histogram was introduced in
67 Firefox 110.0 in bug 1806765.
69 PLACES_FRECENCY_RECALC_CHUNK_TIME_MS
70 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
72 This records the time necessary to recalculate frecency of a chunk of pages,
73 as defined in the `PlacesFrecencyRecalculator <https://searchfox.org/mozilla-central/source/toolkit/components/places/PlacesFrecencyRecalculator.sys.mjs>`_ module.
81 A uint recording the number of abandoned engagements in the urlbar. An
82 abandonment occurs when the user begins using the urlbar but stops before
83 completing the engagement. This can happen when the user clicks outside the
84 urlbar to focus a different part of the window. It can also happen when the
85 user switches to another window while the urlbar is focused.
87 urlbar.autofill_deletion
88 ~~~~~~~~~~~~~~~~~~~~~~~~
90 A uint recording the deletion count for autofilled string in the urlbar.
91 This occurs when the user deletes whole autofilled string by BACKSPACE or
92 DELETE key while the autofilled string is selected.
97 A uint recording the number of engagements the user completes in the urlbar.
98 An engagement occurs when the user navigates to a page using the urlbar, for
99 example by picking a result in the urlbar panel or typing a search term or URL
100 in the urlbar and pressing the enter key.
105 A uint recording the number of impression that was displaying when user picks
109 For about-page type autofill.
110 - ``autofill_adaptive``
111 For adaptive history type autofill.
112 - ``autofill_origin``
113 For origin type autofill.
115 Counts how many times some other type of autofill result that does not have
116 a specific scalar was shown. This is a fallback that is used when the code is
117 not properly setting a specific autofill type, and it should not normally be
118 used. If it appears in the data, it means we need to investigate and fix the
119 code that is not properly setting a specific autofill type.
121 For url type autofill.
123 urlbar.persistedsearchterms.revert_by_popup_count
124 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
126 A uint that is incremented when search terms are persisted in the Urlbar and
127 the Urlbar is reverted to show a full URL due to a PopupNotification. This
128 can happen when a user is on a SERP and permissions are requested, e.g.
129 request access to location. If the popup is persistent and the user did not
130 dismiss it before switching tabs, the popup will reappear when they return to
131 the tab. Thus, when returning to the tab with the persistent popup, this
132 value will be incremented because it should have persisted search terms but
133 instead showed a full URL.
135 urlbar.persistedsearchterms.view_count
136 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
138 A uint that is incremented when search terms should be persisted in the
139 Urlbar. This will trigger when a user loads a SERP from any SAP that results
140 in the search terms persisting in the Urlbar, as well as switching to a tab
141 containing a SERP that should be persisting the search terms in the Urlbar,
142 regardless of whether a PopupNotification is present. Thus, for every
143 ``revert_by_popup_count``, there should be at least one corresponding
149 This is a keyed scalar whose values are uints and are incremented each time a
150 tip result is shown, a tip is picked, and a tip's help button is picked. The
153 - ``intervention_clear-help``
154 Incremented when the user picks the help button in the clear-history search
156 - ``intervention_clear-picked``
157 Incremented when the user picks the clear-history search intervention.
158 - ``intervention_clear-shown``
159 Incremented when the clear-history search intervention is shown.
160 - ``intervention_refresh-help``
161 Incremented when the user picks the help button in the refresh-Firefox
163 - ``intervention_refresh-picked``
164 Incremented when the user picks the refresh-Firefox search intervention.
165 - ``intervention_refresh-shown``
166 Incremented when the refresh-Firefox search intervention is shown.
167 - ``intervention_update_ask-help``
168 Incremented when the user picks the help button in the update_ask search
169 intervention, which is shown when there's a Firefox update available but the
170 user's preference says we should ask them to download and apply it.
171 - ``intervention_update_ask-picked``
172 Incremented when the user picks the update_ask search intervention.
173 - ``intervention_update_ask-shown``
174 Incremented when the update_ask search intervention is shown.
175 - ``intervention_update_refresh-help``
176 Incremented when the user picks the help button in the update_refresh search
177 intervention, which is shown when the user's browser is up to date but they
178 triggered the update intervention. We show this special refresh intervention
180 - ``intervention_update_refresh-picked``
181 Incremented when the user picks the update_refresh search intervention.
182 - ``intervention_update_refresh-shown``
183 Incremented when the update_refresh search intervention is shown.
184 - ``intervention_update_restart-help``
185 Incremented when the user picks the help button in the update_restart search
186 intervention, which is shown when there's an update and it's been downloaded
187 and applied. The user needs to restart to finish.
188 - ``intervention_update_restart-picked``
189 Incremented when the user picks the update_restart search intervention.
190 - ``intervention_update_restart-shown``
191 Incremented when the update_restart search intervention is shown.
192 - ``intervention_update_web-help``
193 Incremented when the user picks the help button in the update_web search
194 intervention, which is shown when we can't update the browser or possibly
195 even check for updates for some reason, so the user should download the
196 latest version from the web.
197 - ``intervention_update_web-picked``
198 Incremented when the user picks the update_web search intervention.
199 - ``intervention_update_web-shown``
200 Incremented when the update_web search intervention is shown.
201 - ``tabtosearch-shown``
202 Increment when a non-onboarding tab-to-search result is shown, once per
203 engine per engagement. Please note that the number of times non-onboarding
204 tab-to-search results are picked is the sum of all keys in
205 ``urlbar.searchmode.tabtosearch``. Please also note that more detailed
206 telemetry is recorded about both onboarding and non-onboarding tab-to-search
207 results in urlbar.tabtosearch.*. These probes in ``urlbar.tips`` are still
208 recorded because ``urlbar.tabtosearch.*`` is not currently recorded
210 - ``tabtosearch_onboard-shown``
211 Incremented when a tab-to-search onboarding result is shown, once per engine
212 per engagement. Please note that the number of times tab-to-search
213 onboarding results are picked is the sum of all keys in
214 ``urlbar.searchmode.tabtosearch_onboard``.
215 - ``searchTip_onboard-picked``
216 Incremented when the user picks the onboarding search tip.
217 - ``searchTip_onboard-shown``
218 Incremented when the onboarding search tip is shown.
219 - ``searchTip_persist-picked``
220 Incremented when the user picks the urlbar persisted search tip.
221 - ``searchTip_persist-shown``
222 Incremented when the url persisted search tip is shown.
223 - ``searchTip_redirect-picked``
224 Incremented when the user picks the redirect search tip.
225 - ``searchTip_redirect-shown``
226 Incremented when the redirect search tip is shown.
231 This is a set of keyed scalars whose values are uints incremented each
232 time search mode is entered in the Urlbar. The suffix on the scalar name
233 describes how search mode was entered. Possibilities include:
236 Used when the user selects the Search Bookmarks menu item in the Library
239 Used when the user uses the search box on the new tab page and is handed off
240 to the address bar. NOTE: This entry point was disabled from Firefox 88 to
241 91. Starting with 91, it will appear but in low volume. Users must have
242 searching in the Urlbar disabled to enter search mode via handoff.
244 Used when the user selects a keyword offer result.
246 Used when the user selects a one-off engine in the Urlbar.
248 Used when the user enters search mode with a keyboard shortcut or menu bar
249 item (e.g. ``Accel+K``).
251 Used when the user selects the Search Tabs menu item in the tab overflow
254 Used when the user selects a tab-to-search result. These results suggest a
255 search engine when the search engine's domain is autofilled.
256 - ``tabtosearch_onboard``
257 Used when the user selects a tab-to-search onboarding result. These are
258 shown the first few times the user encounters a tab-to-search result.
259 - ``topsites_newtab``
260 Used when the user selects a search shortcut Top Site from the New Tab Page.
261 - ``topsites_urlbar``
262 Used when the user selects a search shortcut Top Site from the Urlbar.
264 Used when the user taps a search shortct on the Touch Bar, available on some
267 Used when the user types an engine alias in the Urlbar.
269 Used when the user selects the Search History menu item in a History
272 Used as a catchall for other behaviour. We don't expect this scalar to hold
273 any values. If it does, we need to correct an issue with search mode entry
276 The keys for the scalars above are engine and source names. If the user enters
277 a remote search mode with a built-in engine, we record the engine name. If the
278 user enters a remote search mode with an engine they installed (e.g. via
279 OpenSearch or a WebExtension), we record ``other`` (not to be confused with
280 the ``urlbar.searchmode.other`` scalar above). If they enter a local search
281 mode, we record the English name of the result source (e.g. "bookmarks",
282 "history", "tabs"). Note that we slightly modify the engine name for some
283 built-in engines: we flatten all localized Amazon sites (Amazon.com,
284 Amazon.ca, Amazon.de, etc.) to "Amazon" and we flatten all localized
285 Wikipedia sites (Wikipedia (en), Wikipedia (fr), etc.) to "Wikipedia". This
286 is done to reduce the number of keys used by these scalars.
291 This is a set of keyed scalars whose values are uints incremented each
292 time a result is picked from the Urlbar. The suffix on the scalar name
293 is the result type. The keys for the scalars above are the 0-based index of
294 the result in the urlbar panel when it was picked.
297 Available from Firefox 84 on. Use the *FX_URLBAR_SELECTED_** histograms in
301 Firefox 102 deprecated ``autofill`` and added ``autofill_about``,
302 ``autofill_adaptive``, ``autofill_origin``, ``autofill_other``,
303 ``autofill_preloaded``, and ``autofill_url``. In Firefox 116,
304 ``autofill_preloaded`` was removed.
306 Valid result types are:
309 This scalar was deprecated in Firefox 102 and replaced with
310 ``autofill_about``, ``autofill_adaptive``, ``autofill_origin``,
311 ``autofill_other``, ``autofill_preloaded``, and ``autofill_url``. Previously
312 it was recorded in each of the cases that the other scalars now cover.
314 An autofilled "about:" page URI (e.g., about:config). The user must first
315 type "about:" to trigger this type of autofill.
316 - ``autofill_adaptive``
317 An autofilled URL from the user's adaptive history. This type of autofill
318 differs from ``autofill_url`` in two ways: (1) It's based on the user's
319 adaptive history, a particular type of history that associates the user's
320 search string with the URL they pick in the address bar. (2) It autofills
321 full URLs instead of "up to the next slash" partial URLs. For more
322 information on this type of autofill, see this `adaptive history autofill
324 - ``autofill_origin``
325 An autofilled origin_ from the user's history. Typically "origin" means a
326 domain or host name like "mozilla.org". Technically it can also include a
327 URL scheme or protocol like "https" and a port number like ":8000". Firefox
328 can autofill domain names by themselves, domain names with schemes, domain
329 names with ports, and domain names with schemes and ports. All of these
330 cases count as origin autofill. For more information, see this `adaptive
331 history autofill document`_.
333 Counts how many times some other type of autofill result that does not have
334 a specific keyed scalar was picked at a given index. This is a fallback that
335 is used when the code is not properly setting a specific autofill type, and
336 it should not normally be used. If it appears in the data, it means we need
337 to investigate and fix the code that is not properly setting a specific
340 An autofilled URL or partial URL from the user's history. Firefox autofills
341 URLs "up to the next slash", so to trigger URL autofill, the user must first
342 type a domain name (or trigger origin autofill) and then begin typing the
343 rest of the URL (technically speaking, its path). As they continue typing,
344 the URL will only be partially autofilled up to the next slash, or if there
345 is no next slash, to the end of the URL. This allows the user to easily
346 visit different subpaths of a domain. For more information, see this
347 `adaptive history autofill document`_.
350 - ``bookmark_adaptive``
351 A bookmarked URL retrieved from adaptive history.
353 A URL retrieved from the system clipboard.
355 A specially crafted result, often used in experiments when basic types are
356 not flexible enough for a rich layout.
357 - ``dynamic_wikipedia``
358 A dynamic Wikipedia Firefox Suggest result.
360 Added by an add-on through the omnibox WebExtension API.
362 A search suggestion from previous search history.
365 - ``history_adaptive``
366 A URL from history retrieved from adaptive history.
370 A navigational suggestion Firefox Suggest result.
374 A Firefox Suggest (a.k.a. quick suggest) suggestion.
376 A tab synced from another device.
378 A search result, but not a suggestion. May be the default search action
380 - ``searchsuggestion``
381 A remote search suggestion.
385 A tab to search result.
389 An entry from top sites.
391 A trending suggestion.
393 An unknown result type, a bug should be filed to figure out what it is.
395 The user typed string can be directly visited.
397 A Firefox Suggest weather suggestion.
399 .. _adaptive history autofill document: https://docs.google.com/document/d/e/2PACX-1vRBLr_2dxus-aYhZRUkW9Q3B1K0uC-a0qQyE3kQDTU3pcNpDHb36-Pfo9fbETk89e7Jz4nkrqwRhi4j/pub
400 .. _origin: https://html.spec.whatwg.org/multipage/origin.html#origin
402 urlbar.picked.searchmode.*
403 ~~~~~~~~~~~~~~~~~~~~~~~~~~
405 This is a set of keyed scalars whose values are uints incremented each time a
406 result is picked from the Urlbar while the Urlbar is in search mode. The
407 suffix on the scalar name is the search mode entry point. The keys for the
408 scalars are the 0-based index of the result in the urlbar panel when it was
412 These scalars share elements of both ``urlbar.picked.*`` and
413 ``urlbar.searchmode.*``. Scalar name suffixes are search mode entry points,
414 like ``urlbar.searchmode.*``. The keys for these scalars are result indices,
415 like ``urlbar.picked.*``.
418 These data are a subset of the data recorded by ``urlbar.picked.*``. For
419 example, if the user enters search mode by clicking a one-off then selects
420 a Google search suggestion at index 2, we would record in **both**
421 ``urlbar.picked.searchsuggestion`` and ``urlbar.picked.searchmode.oneoff``.
426 This is a set of keyed scalars whose values are uints incremented when a
427 tab-to-search result is shown, once per engine per engagement. There are two
428 sub-probes: ``urlbar.tabtosearch.impressions`` and
429 ``urlbar.tabtosearch.impressions_onboarding``. The former records impressions
430 of regular tab-to-search results and the latter records impressions of
431 onboarding tab-to-search results. The key values are identical to those of the
432 ``urlbar.searchmode.*`` probes: they are the names of the engines shown in the
433 tab-to-search results. Engines that are not built in are grouped under the
437 Due to the potentially sensitive nature of these data, they are currently
438 collected only on pre-release version of Firefox. See bug 1686330.
440 urlbar.zeroprefix.abandonment
441 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
443 A uint recording the number of abandonments of the zero-prefix view.
444 "Zero-prefix" means the search string was empty, so the zero-prefix view is
445 the view that's shown when the user clicks in the urlbar before typing a
446 search string. Often it's called the "top sites" view since normally it shows
447 the user's top sites. "Abandonment" means the user opened the zero-prefix view
448 but it was closed without the user picking a result inside it. This scalar was
449 introduced in Firefox 110.0 in bug 1806765.
451 urlbar.zeroprefix.engagement
452 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
454 A uint recording the number of engagements in the zero-prefix view.
455 "Zero-prefix" means the search string was empty, so the zero-prefix view is
456 the view that's shown when the user clicks in the urlbar before typing a
457 search string. Often it's called the "top sites" view since normally it shows
458 the user's top sites. "Engagement" means the user picked a result inside the
459 view. This scalar was introduced in Firefox 110.0 in bug 1806765.
461 urlbar.zeroprefix.exposure
462 ~~~~~~~~~~~~~~~~~~~~~~~~~~
464 A uint recording the number of times the user was exposed to the zero-prefix
465 view; that is, the number of times it was shown. "Zero-prefix" means the
466 search string was empty, so the zero-prefix view is the view that's shown when
467 the user clicks in the urlbar before typing a search string. Often it's called
468 the "top sites" view since normally it shows the user's top sites. This scalar
469 was introduced in Firefox 110.0 in bug 1806765.
471 urlbar.quickaction.impression
472 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
474 A uint recording the number of times the user was shown a quickaction, the
475 key is in the form $key-$n where $n is the number of characters the user typed
476 in order for the suggestion to show. See bug 1806024.
478 urlbar.quickaction.picked
479 ~~~~~~~~~~~~~~~~~~~~~~~~~
481 A uint recording the number of times the user selected a quickaction, the
482 key is in the form $key-$n where $n is the number of characters the user typed
483 in order for the suggestion to show. See bug 1783155.
488 This is Places related telemetry.
490 Valid result types are:
492 - ``sponsored_visit_no_triggering_url``
493 Number of sponsored visits that could not find their triggering URL in
494 history. We expect this to be a small number just due to the navigation layer
495 manipulating URLs. A large or growing value may be a concern.
496 - ``pages_need_frecency_recalculation``
497 Number of pages in need of a frecency recalculation. This number should
498 remain small compared to the total number of pages in the database (see the
499 `PLACES_PAGES_COUNT` histogram). It can be used to valuate the frequency
500 and size of recalculations, for performance reasons.
502 Search Engagement Telemetry
503 ---------------------------
505 The search engagement telemetry provided since Firefox 110 is is recorded using
506 Glean events. Because of the data size, these events are collected only for a
507 subset of the population, using the Glean Sampling feature. Please see the
508 following documents for the details.
511 It is defined as a completed action in urlbar, where a user picked one of
514 It is defined as an action where the user open the results but does not
515 complete an engagement action, usually unfocusing the urlbar. This also
516 happens when the user switches to another window, if the results popup was
519 It is defined as an action where the results had been shown to the user for
520 a while. In default, it will be recorded when the same results have been
521 shown and 1 sec has elapsed. The interval value can be modified through the
522 `browser.urlbar.searchEngagementTelemetry.pauseImpressionIntervalMs`
525 .. _Engagement: https://dictionary.telemetry.mozilla.org/apps/firefox_desktop/metrics/urlbar_engagement
526 .. _Abandonment: https://dictionary.telemetry.mozilla.org/apps/firefox_desktop/metrics/urlbar_abandonment
527 .. _Impression: https://dictionary.telemetry.mozilla.org/apps/firefox_desktop/metrics/urlbar_impression
530 Custom pings for Contextual Services
531 ------------------------------------
533 Contextual Services currently has two features involving the address bar, top
534 sites and Firefox Suggest. Top sites telemetry is described below. For Firefox
535 Suggest, see the :doc:`firefox-suggest-telemetry` document.
537 Firefox sends the following `custom pings`_ to record impressions and clicks of
538 the top sites feature.
540 .. _custom pings: https://docs.telemetry.mozilla.org/cookbooks/new_ping.html#sending-a-custom-ping
545 This records an impression when a sponsored top site is shown.
548 A UUID representing this user. Note that it's not client_id, nor can it be
549 used to link to a client_id.
551 A unique identifier for the sponsored top site.
553 The browser location where the impression was displayed.
555 The placement of the top site (1-based).
557 The Name of the advertiser.
559 The reporting URL of the sponsored top site, normally pointing to the ad
560 partner's reporting endpoint.
563 - ``release_channel``
564 Firefox release channel.
566 User's current locale.
570 The impression ping is sent for Pocket sponsored tiles as well. Pocket sponsored tiles have different values for ``advertiser`` and ``reporting_url`` is null. [Bug 1794022_]
573 Introduced. [Non_public_doc_]
575 .. _Non_public_doc: https://docs.google.com/document/d/1qLb4hUwR8YQj5QnjJtwxQIoDCPLQ6XuAmJPQ6_WmS4E/edit
576 .. _1794022: https://bugzilla.mozilla.org/show_bug.cgi?id=1794022
581 This records a click ping when a sponsored top site is clicked by the user.
584 A UUID representing this user. Note that it's not client_id, nor can it be
585 used to link to a client_id.
587 A unique identifier for the sponsored top site.
589 The browser location where the click was tirggered.
591 The placement of the top site (1-based).
593 The Name of the advertiser.
595 The reporting URL of the sponsored top site, normally pointing to the ad
596 partner's reporting endpoint.
599 - ``release_channel``
600 Firefox release channel.
602 User's current locale.
606 The click ping is sent for Pocket sponsored tiles as well. Pocket sponsored tiles have different values for ``advertiser`` and ``reporting_url`` is null. [Bug 1794022_]
609 Introduced. [Non_public_doc_]
612 Other telemetry relevant to the Address Bar
613 -------------------------------------------
618 Some of the `search telemetry`_ is also relevant to the address bar.
620 contextual.services.topsites.*
621 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
623 These keyed scalars instrument the impressions and clicks for sponsored top
625 The key is a combination of the source and the placement of the top sites link
626 (1-based) such as 'urlbar_1'. For each key, it records the counter of the
628 Note that these scalars are shared with the top sites on the newtab page.
630 Telemetry Environment
631 ~~~~~~~~~~~~~~~~~~~~~
633 The following preferences relevant to the address bar are recorded in
634 :doc:`telemetry environment data </toolkit/components/telemetry/data/environment>`:
636 - ``browser.search.suggest.enabled``: The global toggle for search
637 suggestions everywhere in Firefox (search bar, urlbar, etc.). Defaults to
639 - ``browser.urlbar.autoFill``: The global preference for whether autofill in
640 the urlbar is enabled. When false, all types of autofill are disabled.
641 - ``browser.urlbar.autoFill.adaptiveHistory.enabled``: True if adaptive
642 history autofill in the urlbar is enabled.
643 - ``browser.urlbar.suggest.searches``: True if search suggestions are
644 enabled in the urlbar. Defaults to false.
649 Telemetry specific to Firefox Suggest is described in the
650 :doc:`firefox-suggest-telemetry` document.
652 .. _search telemetry: /browser/search/telemetry.html
658 This is a legacy event telemetry. For the current telemetry, please see
659 `Search Engagement Telemetry`_. These legacy events were disabled by default
660 and required enabling through a preference or a Urlbar WebExtension
663 .. _Search Engagement Telemetry: #search-engagement-telemetry
665 The event telemetry is grouped under the ``urlbar`` category.
670 There are two methods to describe the interaction with the urlbar:
673 It is defined as a completed action in urlbar, where a user inserts text
674 and executes one of the actions described in the Event Object.
676 It is defined as an action where the user inserts text but does not
677 complete an engagement action, usually unfocusing the urlbar. This also
678 happens when the user switches to another window, regardless of urlbar
684 This is how the user interaction started
686 - ``typed``: The text was typed into the urlbar.
687 - ``dropped``: The text was drag and dropped into the urlbar.
688 - ``pasted``: The text was pasted into the urlbar.
689 - ``topsites``: The user opened the urlbar view without typing, dropping,
691 In these cases, if the urlbar input is showing the URL of the loaded page
692 and the user has not modified the input’s content, the urlbar views shows
693 the user’s top sites. Otherwise, if the user had modified the input’s
694 content, the urlbar view shows results based on what the user has typed.
695 To tell whether top sites were shown, it's enough to check whether value is
696 ``topsites``. To know whether the user actually picked a top site, check
697 check that ``numChars`` == 0. If ``numChars`` > 0, the user initially opened
698 top sites, but then they started typing and confirmed a different result.
699 - ``returned``: The user abandoned a search, for example by switching to
700 another tab/window, or focusing something else, then came back to it
701 and continued. We consider a search continued if the user kept at least the
702 first char of the original search string.
703 - ``restarted``: The user abandoned a search, for example by switching to
704 another tab/window, or focusing something else, then came back to it,
705 cleared it and then typed a new string.
710 These describe actions in the urlbar:
713 The user clicked on a result.
715 The user confirmed a result with Enter.
717 The user dropped text on the input field.
719 The user used Paste and Go feature. It is not the same as paste and Enter.
721 The user unfocused the urlbar. This is only valid for ``abandonment``.
726 This object contains additional information about the interaction.
727 Extra is a key-value store, where all the keys and values are strings.
730 Time in milliseconds from the initial interaction to an action.
732 Number of input characters the user typed or pasted at the time of
735 Number of words in the input. The measurement is taken from a trimmed input
736 split up by its spaces. This is not a perfect measurement, since it will
737 return an incorrect value for languages that do not use spaces or URLs
738 containing spaces in its query parameters, for example.
740 The type of the selected result at the time of submission.
741 This is only present for ``engagement`` events.
742 It can be one of: ``none``, ``autofill``, ``visiturl``, ``bookmark``,
743 ``bookmark_adaptive`` ``history``, ``history_adaptive``, ``keyword``,
744 ``searchengine``, ``searchsuggestion``, ``switchtab``, ``remotetab``,
745 ``extension``, ``oneoff``, ``keywordoffer``, ``canonized``, ``tip``,
746 ``tiphelp``, ``formhistory``, ``tabtosearch``, ``help``, ``block``,
747 ``quicksuggest``, ``unknown``
748 In practice, ``tabtosearch`` should not appear in real event telemetry.
749 Opening a tab-to-search result enters search mode and entering search mode
750 does not currently mark the end of an engagement. It is noted here for
751 completeness. Similarly, ``block`` indicates a result was blocked or deleted
752 but should not appear because blocking a result does not end the engagement.
754 Index of the selected result in the urlbar panel, or -1 for no selection.
755 There won't be a selection when a one-off button is the only selection, and
756 for the ``paste_go`` or ``drop_go`` objects. There may also not be a
757 selection if the system was busy and results arrived too late, then we
758 directly decide whether to search or visit the given string without having
759 a fully built result.
760 This is only present for ``engagement`` events.
762 The name of the result provider for the selected result. Existing values
763 are: ``HeuristicFallback``, ``Autofill``, ``Places``,
764 ``TokenAliasEngines``, ``SearchSuggestions``, ``UrlbarProviderTopSites``.
765 Data from before Firefox 91 will also list ``UnifiedComplete`` as a
766 provider. This is equivalent to ``Places``.
767 Values can also be defined by `URLBar provider experiments`_.
769 .. _URLBar provider experiments: experiments.html#developing-address-bar-extensions