path: root/browser/components/urlbar/docs/firefox-suggest-telemetry.rst

Firefox Suggest Telemetry
=========================

This document describes the telemetry that Firefox records for the Firefox
Suggest feature. That is, it describes Firefox Suggest telemetry recorded on the
client. It also discusses the data that Firefox sends to the Merino service.

For information on other telemetry related to the address bar, see the general
address bar :doc:`telemetry` document. For information on all telemetry in
Firefox, see the toolkit :doc:`/toolkit/components/telemetry/index` document.

.. contents::
   :depth: 2


Histograms
----------

The following histograms are recorded for Firefox Suggest. For general
information on histogram telemetry in Firefox, see the
:doc:`/toolkit/components/telemetry/collection/histograms` document.

FX_URLBAR_MERINO_LATENCY_MS
~~~~~~~~~~~~~~~~~~~~~~~~~~~

This histogram records the latency in milliseconds of the Merino source for
suggestions, or in other words, the time from Firefox's request to the Merino
server to the time Firefox receives a response. It is an exponential histogram
with 50 buckets and values between 0 and 30000 (0s and 30s).

Changelog
  Firefox 93.0
    Introduced. [Bug 1727799_]

.. _1727799: https://bugzilla.mozilla.org/show_bug.cgi?id=1727799

FX_URLBAR_MERINO_LATENCY_WEATHER_MS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This histogram records the latency in milliseconds of weather suggestions from
Merino. It is updated in addition to ``FX_URLBAR_MERINO_LATENCY_MS`` and has the
same properties. It is an exponential histogram with 50 buckets and values
between 0 and 30000 (0s and 30s).

Changelog
  Firefox 110.0
    Introduced. [Bug 1804536_]

.. _1804536: https://bugzilla.mozilla.org/show_bug.cgi?id=1804536

FX_URLBAR_MERINO_RESPONSE
~~~~~~~~~~~~~~~~~~~~~~~~~

This categorical histogram records a summary of each fetch from the Merino
server. It has the following categories:

:0 "success":
   The fetch completed without any error before the timeout elapsed and it
   included at least one suggestion. (Before Firefox 110.0, this category meant
   simply that the fetch completed without any error before the timeout elapsed
   regardless of whether it included any suggestions.)
:1 "timeout":
   The timeout elapsed before the fetch completed or otherwise failed.
:2 "network_error":
   The fetch failed due to a network error before the timeout elapsed. e.g., the
   user's network or the Merino server was down.
:3 "http_error":
   The fetch completed before the timeout elapsed but the server returned an
   error.
:4 "no_suggestion":
   The fetch completed without any error before the timeout elapsed and it did
   not include any suggestions.

Changelog
  Firefox 94.0.2
    Introduced. [Bug 1737923_]

  Firefox 110.0
    Added the ``no_suggestion`` category. The meaning of the ``success``
    category was changed from "The fetch completed without any error before the
    timeout elapsed" to "The fetch completed without any error before the
    timeout elapsed and it included at least one suggestion." [Bug 1804536_]

.. _1737923: https://bugzilla.mozilla.org/show_bug.cgi?id=1737923
.. _1804536: https://bugzilla.mozilla.org/show_bug.cgi?id=1804536

FX_URLBAR_MERINO_RESPONSE_WEATHER
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This categorical histogram records a summary of each fetch for weather
suggestions from the Merino server. It is updated in addition to
``FX_URLBAR_MERINO_RESPONSE`` and has the same categories.

:0 "success":
   The fetch completed without any error before the timeout elapsed and it
   included at least one suggestion.
:1 "timeout":
   The timeout elapsed before the fetch completed or otherwise failed.
:2 "network_error":
   The fetch failed due to a network error before the timeout elapsed. e.g., the
   user's network or the Merino server was down.
:3 "http_error":
   The fetch completed before the timeout elapsed but the server returned an
   error.
:4 "no_suggestion":
   The fetch completed without any error before the timeout elapsed and it did
   not include any suggestions.

Changelog
  Firefox 110.0
    Introduced. [Bug 1804536_]

.. _1804536: https://bugzilla.mozilla.org/show_bug.cgi?id=1804536

FX_URLBAR_QUICK_SUGGEST_REMOTE_SETTINGS_LATENCY_MS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This histogram records the latency in milliseconds of the remote settings source
for suggestions, or in other words, the time from when Firefox starts fetching a
suggestion from remote settings to the time the suggestion is retrieved. It is
an exponential histogram with 50 buckets and values between 0 and 30000 (0s and
30s).

Note that unlike Merino, fetches from remote settings happen entirely on the
client, so remote settings latencies are expected to be much smaller than Merino
latencies.

Changelog
  Firefox 94.0.2
    Introduced. [Bug 1737651_]

.. _1737651: https://bugzilla.mozilla.org/show_bug.cgi?id=1737651

Scalars
-------

The following scalars are recorded for Firefox Suggest. For general information
on scalar telemetry in Firefox, see the
:doc:`/toolkit/components/telemetry/collection/scalars` document.

browser.ui.interaction.preferences_panePrivacy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user clicks a Firefox Suggest
checkbox or toggle switch in the preferences UI. Keys are the following:

:firefoxSuggestBestMatch:
  This key is incremented when the "Top pick" checkbox is clicked.
:firefoxSuggestBestMatchLearnMore:
  This key is incremented when opening the learn more link for best match.
:firefoxSuggestDataCollectionToggle:
  This key is incremented when the toggle switch for data collection
  is clicked.
:firefoxSuggestNonsponsoredToggle:
  This key is incremented when the toggle switch for non-sponsored suggestions
  is clicked.
:firefoxSuggestSponsoredToggle:
  This key is incremented when the toggle switch for sponsored suggestions
  is clicked.

Changelog
  Firefox 94.0.2
    Introduced firefoxSuggestDataCollectionToggle,
    firefoxSuggestNonsponsoredToggle and firefoxSuggestSponsoredToggle.
    [Bug 1735976_]

  Firefox 99.0
    Introduced firefoxSuggestBestMatch. [Bug 1755100_]
    Introduced firefoxSuggestBestMatchLearnMore. [Bug 1756917_]

.. _1735976: https://bugzilla.mozilla.org/show_bug.cgi?id=1735976
.. _1755100: https://bugzilla.mozilla.org/show_bug.cgi?id=1755100
.. _1756917: https://bugzilla.mozilla.org/show_bug.cgi?id=1756917

contextual.services.quicksuggest.block_dynamic_wikipedia
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user dismisses ("blocks") a
dynamic wikipedia suggestion. Each key is the index at which a suggestion
appeared in the results (1-based), and the corresponding value is the number
of dismissals at that index.

Changelog
  Firefox 109.0
    Introduced. [Bug 1800993_]

.. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993

contextual.services.quicksuggest.block_nonsponsored
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user dismisses ("blocks") a
non-sponsored suggestion, including both best matches and the usual
non-best-match suggestions. Each key is the index at which a suggestion appeared
in the results (1-based), and the corresponding value is the number of
dismissals at that index.

Changelog
  Firefox 101.0
    Introduced. [Bug 1761059_]

.. _1761059: https://bugzilla.mozilla.org/show_bug.cgi?id=1761059

contextual.services.quicksuggest.block_nonsponsored_bestmatch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user dismisses ("blocks") a
non-sponsored best match. Each key is the index at which a suggestion appeared
in the results (1-based), and the corresponding value is the number of
dismissals at that index.

Changelog
  Firefox 101.0
    Introduced. [Bug 1761059_]

.. _1761059: https://bugzilla.mozilla.org/show_bug.cgi?id=1761059

contextual.services.quicksuggest.block_sponsored
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user dismisses ("blocks") a
sponsored suggestion, including both best matches and the usual non-best-match
suggestions. Each key is the index at which a suggestion appeared in the results
(1-based), and the corresponding value is the number of dismissals at that
index.

Changelog
  Firefox 101.0
    Introduced. [Bug 1761059_]

.. _1761059: https://bugzilla.mozilla.org/show_bug.cgi?id=1761059

contextual.services.quicksuggest.block_sponsored_bestmatch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user dismisses ("blocks") a
sponsored best match. Each key is the index at which a suggestion appeared in
the results (1-based), and the corresponding value is the number of dismissals
at that index.

Changelog
  Firefox 101.0
    Introduced. [Bug 1761059_]

.. _1761059: https://bugzilla.mozilla.org/show_bug.cgi?id=1761059

contextual.services.quicksuggest.block_weather
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user dismisses ("blocks") a
Firefox Suggest weather suggestion. Each key is the index at which a suggestion
appeared in the results (1-based), and the corresponding value is the number of
dismissals at that index.

Changelog
  Firefox 110.0
    Introduced. [Bug 1804536_]

.. _1804536: https://bugzilla.mozilla.org/show_bug.cgi?id=1804536

contextual.services.quicksuggest.click
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user picks a suggestion. Each key
is the index at which a suggestion appeared in the results (1-based), and the
corresponding value is the number of clicks at that index.

Changelog
  Firefox 87.0
    Introduced. [Bug 1693927_]

  Firefox 109.0
    Removed. [Bug 1800993_]

.. _1693927: https://bugzilla.mozilla.org/show_bug.cgi?id=1693927
.. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993

contextual.services.quicksuggest.click_dynamic_wikipedia
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user picks a dynamic
wikipedia suggestion. Each key is the index at which a suggestion appeared
in the results (1-based), and the corresponding value is the number of
clicks at that index.

Changelog
  Firefox 109.0
    Introduced. [Bug 1800993_]

.. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993

contextual.services.quicksuggest.click_nav_notmatched
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar records how many times a heuristic result was clicked while a
navigational suggestion was absent. It is recorded only when the Nimbus variable
``recordNavigationalSuggestionTelemetry`` is true. (The variable is false by
default.)

Each key is the type of heuristic result that was clicked. Key names are the
same as the heuristic result type names recorded in Glean telemetry.

Changelog
  Firefox 112.0
    Introduced. [Bug 1819797_]

.. _1819797: https://bugzilla.mozilla.org/show_bug.cgi?id=1819797

contextual.services.quicksuggest.click_nav_shown_heuristic
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar records how many times a heuristic result was clicked while a
navigational suggestion was present. It is recorded only when the Nimbus
variable ``recordNavigationalSuggestionTelemetry`` is true. (The variable is
false by default.)

Each key is the type of heuristic result that was clicked. Key names are the
same as the heuristic result type names recorded in Glean telemetry.

Changelog
  Firefox 112.0
    Introduced. [Bug 1819797_]

.. _1819797: https://bugzilla.mozilla.org/show_bug.cgi?id=1819797

contextual.services.quicksuggest.click_nav_shown_nav
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar records how many times a navigational suggestion was clicked.
It is recorded only when the Nimbus variable
``recordNavigationalSuggestionTelemetry`` is true. (The variable is false by
default.)

Each key is the type of heuristic result that was present at the time of the
engagement. Key names are the same as the heuristic result type names recorded
in Glean telemetry.

Changelog
  Firefox 112.0
    Introduced. [Bug 1819797_]

.. _1819797: https://bugzilla.mozilla.org/show_bug.cgi?id=1819797

contextual.services.quicksuggest.click_nav_superceded
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar records how many times a heuristic result was clicked when a
navigational suggestion was matched but superseded by the heuristic. It is
recorded only when the Nimbus variable ``recordNavigationalSuggestionTelemetry``
is true. (The variable is false by default.)

Each key is the type of heuristic result that was clicked. Key names are the
same as the heuristic result type names recorded in Glean telemetry.

Changelog
  Firefox 112.0
    Introduced. [Bug 1819797_]

.. _1819797: https://bugzilla.mozilla.org/show_bug.cgi?id=1819797

contextual.services.quicksuggest.click_nonsponsored
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user picks a non-sponsored
suggestion. Each key is the index at which a suggestion appeared in the
results (1-based), and the corresponding value is the number of clicks at
that index.

Changelog
  Firefox 109.0
    Introduced. [Bug 1800993_]

.. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993

contextual.services.quicksuggest.click_nonsponsored_bestmatch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user picks a non-sponsored best
match. Each key is the index at which a suggestion appeared in the results
(1-based), and the corresponding value is the number of clicks at that index.

Changelog
  Firefox 99.0
    Introduced. [Bug 1752953_]

.. _1752953: https://bugzilla.mozilla.org/show_bug.cgi?id=1752953

contextual.services.quicksuggest.click_sponsored
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user picks a sponsored suggestion.
Each key is the index at which a suggestion appeared in the results (1-based),
and the corresponding value is the number of clicks at that index.

Changelog
  Firefox 109.0
    Introduced. [Bug 1800993_]

.. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993

contextual.services.quicksuggest.click_sponsored_bestmatch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user picks a sponsored best
match. Each key is the index at which a suggestion appeared in the results
(1-based), and the corresponding value is the number of clicks at that index.

Changelog
  Firefox 99.0
    Introduced. [Bug 1752953_]

.. _1752953: https://bugzilla.mozilla.org/show_bug.cgi?id=1752953

contextual.services.quicksuggest.click_weather
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user picks a weather suggestion.
Each key is the index at which a suggestion appeared in the results (1-based),
and the corresponding value is the number of clicks at that index.

Changelog
  Firefox 110.0
    Introduced. [Bug 1804536_]

.. _1804536: https://bugzilla.mozilla.org/show_bug.cgi?id=1804536

contextual.services.quicksuggest.exposure_weather
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar records weather suggestion exposures. It is incremented each
time the user is shown a weather suggestion. It can be compared to the
``urlbar.zeroprefix.exposure`` scalar (see :doc:`telemetry`) to determine the
percentage of zero-prefix exposures that included weather suggestions.

Each key is the index at which a suggestion appeared in the results (1-based),
and the corresponding value is the number of exposures at that index.

Changelog
  Firefox 110.0
    Introduced. [Bug 1806765_]

  Firefox 114.0
    Removed since the weather suggestion is no longer triggered on zero prefix.
    [Bug 1831971_]

.. _1806765: https://bugzilla.mozilla.org/show_bug.cgi?id=1806765
.. _1831971: https://bugzilla.mozilla.org/show_bug.cgi?id=1831971

contextual.services.quicksuggest.help
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user picks the help button in a
suggestion. Each key is the index at which a suggestion appeared in the results
(1-based), and the corresponding value is the number of help button clicks at
that index.

Changelog
  Firefox 87.0
    Introduced. [Bug 1693927_]

  Firefox 109.0
    Removed. [Bug 1800993_]

.. _1693927: https://bugzilla.mozilla.org/show_bug.cgi?id=1693927
.. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993

contextual.services.quicksuggest.help_dynamic_wikipedia
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user picks the help button in a
dynamic wikipedia suggestion. Each key is the index at which a suggestion
appeared in the results (1-based), and the corresponding value is the number
of help button clicks at that index.

Changelog
  Firefox 109.0
    Introduced. [Bug 1800993_]

.. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993

contextual.services.quicksuggest.help_nonsponsored
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user picks the help button in a
non-sponsored suggestion. Each key is the index at which a suggestion appeared in the
results (1-based), and the corresponding value is the number of help button clicks
at that index.

Changelog
  Firefox 109.0
    Introduced. [Bug 1800993_]

.. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993

contextual.services.quicksuggest.help_nonsponsored_bestmatch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user picks the help button in a
non-sponsored best match. Each key is the index at which a suggestion appeared
in the results (1-based), and the corresponding value is the number of help
button clicks at that index.

Changelog
  Firefox 99.0
    Introduced. [Bug 1752953_]

.. _1752953: https://bugzilla.mozilla.org/show_bug.cgi?id=1752953

contextual.services.quicksuggest.help_sponsored
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user picks the help button in a
sponsored suggestion. Each key is the index at which a suggestion appeared in the
results (1-based), and the corresponding value is the number of help button clicks
at that index.

Changelog
  Firefox 109.0
    Introduced. [Bug 1800993_]

.. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993

contextual.services.quicksuggest.help_sponsored_bestmatch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user picks the help button in a
sponsored best match. Each key is the index at which a suggestion appeared in
the results (1-based), and the corresponding value is the number of help button
clicks at that index.

Changelog
  Firefox 99.0
    Introduced. [Bug 1752953_]

.. _1752953: https://bugzilla.mozilla.org/show_bug.cgi?id=1752953

contextual.services.quicksuggest.help_weather
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar is incremented each time the user picks the help button in a
weather suggestion. Each key is the index at which a suggestion appeared in the
results (1-based), and the corresponding value is the number of help button
clicks at that index.

Changelog
  Firefox 110.0
    Introduced. [Bug 1804536_]

.. _1804536: https://bugzilla.mozilla.org/show_bug.cgi?id=1804536

contextual.services.quicksuggest.impression
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar records suggestion impressions. It is incremented each time
the user is shown a suggestion and the following two conditions hold:

- The user has completed an engagement with the address bar by picking a result
  in it or by pressing the Enter key.
- At the time the user completed the engagement, a suggestion was present in the
  results.

Each key is the index at which a suggestion appeared in the results (1-based),
and the corresponding value is the number of impressions at that index.

Changelog
  Firefox 87.0
    Introduced. [Bug 1693927_]

  Firefox 109.0
    Removed. [Bug 1800993_]

.. _1693927: https://bugzilla.mozilla.org/show_bug.cgi?id=1693927
.. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993

contextual.services.quicksuggest.impression_dynamic_wikipedia
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar records dynamic wikipedia impressions. It is incremented
each time the user is shown a dynamic wikipedia suggestion and the following
two conditions hold:

- The user has completed an engagement with the address bar by picking a result
  in it or by pressing the Enter key.
- At the time the user completed the engagement, a dynamic wikipedia suggestion
  was present in the results.

Each key is the index at which a suggestion appeared in the results (1-based),
and the corresponding value is the number of impressions at that index.

Changelog
  Firefox 109.0
    Introduced. [Bug 1800993_]

.. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993

contextual.services.quicksuggest.impression_nav_notmatched
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar records how many times a urlbar engagement occurred while a
navigational suggestion was absent. It is recorded only when the Nimbus variable
``recordNavigationalSuggestionTelemetry`` is true. (The variable is false by
default.)

Each key is the type of heuristic result that was present at the time of the
engagement. Key names are the same as the heuristic result type names recorded
in Glean telemetry.

Changelog
  Firefox 112.0
    Introduced. [Bug 1819797_]

.. _1819797: https://bugzilla.mozilla.org/show_bug.cgi?id=1819797

contextual.services.quicksuggest.impression_nav_shown
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar records how many times a urlbar engagement occurred while a
navigational suggestion was present. It is recorded only when the Nimbus
variable ``recordNavigationalSuggestionTelemetry`` is true. (The variable is
false by default.)

Each key is the type of heuristic result that was present at the time of the
engagement. Key names are the same as the heuristic result type names recorded
in Glean telemetry.

Changelog
  Firefox 112.0
    Introduced. [Bug 1819797_]

.. _1819797: https://bugzilla.mozilla.org/show_bug.cgi?id=1819797

contextual.services.quicksuggest.impression_nav_superceded
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar records how many times a urlbar engagement occurred when a
navigational suggestion was matched but superseded by a heuristic result. It is
recorded only when the Nimbus variable ``recordNavigationalSuggestionTelemetry``
is true. (The variable is false by default.)

Each key is the type of heuristic result that was present at the time of the
engagement. Key names are the same as the heuristic result type names recorded
in Glean telemetry.

Changelog
  Firefox 112.0
    Introduced. [Bug 1819797_]

.. _1819797: https://bugzilla.mozilla.org/show_bug.cgi?id=1819797

contextual.services.quicksuggest.impression_nonsponsored
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar records suggestion impressions. It is incremented each time
the user is shown a non-sponsored suggestion and the following two conditions hold:

- The user has completed an engagement with the address bar by picking a result
  in it or by pressing the Enter key.
- At the time the user completed the engagement, a suggestion was present in the
  results.

Each key is the index at which a suggestion appeared in the results (1-based),
and the corresponding value is the number of impressions at that index.

Changelog
  Firefox 109.0
    Introduced. [Bug 1800993_]

.. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993

contextual.services.quicksuggest.impression_nonsponsored_bestmatch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar records non-sponsored best match impressions. It is
incremented each time the user is shown a non-sponsored best match and the
following two conditions hold:

- The user has completed an engagement with the address bar by picking a result
  in it or by pressing the Enter key.
- At the time the user completed the engagement, a non-sponsored best match was
  present in the results.

Each key is the index at which a suggestion appeared in the results (1-based),
and the corresponding value is the number of impressions at that index.

Changelog
  Firefox 99.0
    Introduced. [Bug 1752953_]

.. _1752953: https://bugzilla.mozilla.org/show_bug.cgi?id=1752953

contextual.services.quicksuggest.impression_sponsored
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar records suggestion impressions. It is incremented each time
the user is shown a sponsored suggestion and the following two conditions hold:

- The user has completed an engagement with the address bar by picking a result
  in it or by pressing the Enter key.
- At the time the user completed the engagement, a suggestion was present in the
  results.

Each key is the index at which a suggestion appeared in the results (1-based),
and the corresponding value is the number of impressions at that index.

Changelog
  Firefox 109.0
    Introduced. [Bug 1800993_]

.. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993

contextual.services.quicksuggest.impression_sponsored_bestmatch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar records sponsored best match impressions. It is incremented
each time the user is shown a sponsored best match and the following two
conditions hold:

- The user has completed an engagement with the address bar by picking a result
  in it or by pressing the Enter key.
- At the time the user completed the engagement, a sponsored best match was
  present in the results.

Each key is the index at which a suggestion appeared in the results (1-based),
and the corresponding value is the number of impressions at that index.

Changelog
  Firefox 99.0
    Introduced. [Bug 1752953_]

.. _1752953: https://bugzilla.mozilla.org/show_bug.cgi?id=1752953

contextual.services.quicksuggest.impression_weather
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This keyed scalar records weather suggestion impressions. It is incremented each
time the user is shown a weather suggestion and the following two conditions
hold:

- The user has completed an engagement with the address bar by picking a result
  in it or by pressing the Enter key.
- At the time the user completed the engagement, a weather suggestion was
  present in the results.

Each key is the index at which a suggestion appeared in the results (1-based),
and the corresponding value is the number of impressions at that index.

Changelog
  Firefox 110.0
    Introduced. [Bug 1804536_]

.. _1804536: https://bugzilla.mozilla.org/show_bug.cgi?id=1804536

Events
------

The following Firefox Suggest events are recorded in the
``contextservices.quicksuggest`` category. For general information on event
telemetry in Firefox, see the
:doc:`/toolkit/components/telemetry/collection/events` document.

contextservices.quicksuggest.data_collect_toggled
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This event is recorded when the
``browser.urlbar.quicksuggest.dataCollection.enabled`` pref is toggled. The pref
can be toggled in the following ways:

- The user can toggle it in the preferences UI.
- The user can toggle it in about:config.

The event is also recorded when the user opts in to the online modal dialog,
with one exception: If the user has already enabled data collection using the
preferences UI or about:config, then the pref's user value is already
true. Opting in doesn't change the user value, so no event is recorded.

The event's objects are the following:

:enabled:
  Recorded when the pref is flipped from false to true.
:disabled:
  Recorded when the pref is flipped from true to false.

Changelog
  Firefox 94.0.2
    Introduced. [Bug 1735976_]

.. _1735976: https://bugzilla.mozilla.org/show_bug.cgi?id=1735976

contextservices.quicksuggest.enable_toggled
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This event is recorded when the
``browser.urlbar.suggest.quicksuggest.nonsponsored`` pref is toggled. The pref
can be toggled in the following ways:

- The user can toggle it in the preferences UI.
- The user can toggle it in about:config.

The event's objects are the following:

:enabled:
  Recorded when the pref is flipped from false to true.
:disabled:
  Recorded when the pref is flipped from true to false.

Changelog
  Firefox 87.0:
    Introduced. The event corresponds to the
    ``browser.urlbar.suggest.quicksuggest`` pref. [Bug 1693126_]

  Firefox 94.0.2:
    ``browser.urlbar.suggest.quicksuggest`` is replaced with
    ``browser.urlbar.suggest.quicksuggest.nonsponsored``, and this event now
    corresponds to the latter pref. [Bug 1735976_]

  Firefox 96.0:
    The event is no longer recorded when the user interacts with the online
    modal dialog since the ``browser.urlbar.suggest.quicksuggest.nonsponsored``
    pref is no longer set when the user opts in or out. [Bug 1740965_]

.. _1693126: https://bugzilla.mozilla.org/show_bug.cgi?id=1693126
.. _1735976: https://bugzilla.mozilla.org/show_bug.cgi?id=1735976
.. _1740965: https://bugzilla.mozilla.org/show_bug.cgi?id=1740965

contextservices.quicksuggest.engagement
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This event is recorded when an engagement occurs in the address bar while a
Firefox Suggest suggestion is present. In other words, it is recorded in two
cases:

- The user picks a Firefox Suggest suggestion or a related UI element like its
  help button.
- While a Firefox Suggest suggestion is present in the address bar, the user
  picks some other row.

The event's objects are the following possible values:

:block:
  The user dismissed ("blocked") the suggestion.
:click:
  The user picked the suggestion.
:help:
  The user picked the suggestion's help button.
:impression_only:
  The user picked some other row.
:other:
  The user engaged with the suggestion in some other way, for example by picking
  a command in the result menu. This is a catch-all category and going forward
  Glean telemetry should be preferred.

The event's ``extra`` contains the following properties:

:match_type:
  "best-match" if the suggestion was a best match or "firefox-suggest" if it was
  a non-best-match suggestion.
:position:
  The index of the suggestion in the list of results (1-based).
:suggestion_type:
  The type of suggestion, one of: "sponsored", "nonsponsored",
  "dynamic-wikipedia", "navigational"
:source:
  The source of suggestion, one of: "remote-settings", "merino"

Changelog
  Firefox 101.0
    Introduced. [Bug 1761059_]

  Firefox 109.0
    ``source`` is added. [Bug 1800993_]
    ``dynamic-wikipedia`` is added as a value of ``suggestion_type``. [Bug 1800993_]

  Firefox 112.0
    ``navigational`` is added as a value of ``suggestion_type``. [Bug 1819797_]

  Firefox 114.0
    ``other`` is added as a value of the event object. [Bug 1827943_]

.. _1761059: https://bugzilla.mozilla.org/show_bug.cgi?id=1761059
.. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993
.. _1819797: https://bugzilla.mozilla.org/show_bug.cgi?id=1819797
.. _1827943: https://bugzilla.mozilla.org/show_bug.cgi?id=1827943

contextservices.quicksuggest.impression_cap
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This event is recorded when an event related to an impression cap occurs. The
event's objects are the following possible values:

:hit:
  Recorded when an impression cap is hit.
:reset:
  Recorded when a cap's counter is reset because its interval period has
  elapsed. The implementation may batch multiple consecutive reset events for a
  cap in a single telemetry event; see the ``eventCount`` discussion below.
  Reset events are reported only when a cap's interval period elapses while
  Firefox is running.

The event's ``extra`` contains the following properties:

:count:
  The number of impressions during the cap's interval period.
:eventCount:
  The number of impression cap events reported in the telemetry event. This is
  necessary because the implementation may batch multiple consecutive "reset"
  events for a cap in a single telemetry event. When that occurs, this value
  will be greater than 1, ``startDate`` will be the timestamp at which the
  first event's interval period started, ``eventDate`` will be the timestamp at
  which the last event's interval period ended, and ``count`` will be the number
  of impressions during the first event's interval period. (The implementation
  guarantees that reset events are batched only when the number of impressions
  for all subsequent interval periods is zero.) For "hit" events,
  ``eventCount`` will always be 1.
:eventDate:
  The event's timestamp, in number of milliseconds since Unix epoch. For "reset"
  events, this is the timestamp at which the cap's interval period ended. If
  ``eventCount`` is greater than 1, it's the timestamp at which the last
  interval period ended. For "hit" events, this is the timestamp at which the
  cap was hit.
:impressionDate:
  The timestamp of the most recent impression, in number of milliseconds since
  Unix epoch.
:intervalSeconds:
  The number of seconds in the cap's interval period. For lifetime caps, this
  value will be "Infinity".
:maxCount:
  The maximum number of impressions allowed in the cap's interval period.
:startDate:
  The timestamp at which the cap's interval period started, in number of
  milliseconds since Unix epoch.
:type:
  The type of cap, one of: "sponsored", "nonsponsored"

Changelog
  Firefox 101.0
    Introduced. [Bug 1761058_, 1765881_]

.. _1761058: https://bugzilla.mozilla.org/show_bug.cgi?id=1761058
.. _1765881: https://bugzilla.mozilla.org/show_bug.cgi?id=1765881

contextservices.quicksuggest.opt_in_dialog
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This event is recorded when the user interacts with the online modal dialog.
The event's objects are the following:

:accept:
  The user accepted the dialog and opted in. This object was removed in Firefox
  96.0.2.
:accept_2:
  The user accepted the dialog and opted in.
:close_1:
  The user clicked close button or something similar link on the introduction
  section. The user remains opted out in this case.
:dismiss_1:
  The user dismissed the dialog by pressing the Escape key or some unknown way
  on the introduction section. The user remains opted out in this case.
:dismiss_2:
  The user dismissed the dialog by pressing the Escape key or some unknown way
  on main section. The user remains opted out in this case.
:dismissed_escape_key:
  The user dismissed the dialog by pressing the Escape key. The user remains
  opted out in this case. This object was removed in Firefox 96.0.2.
:dismissed_other:
  The dialog was dismissed in some unknown way. One case where this can happen
  is when the dialog is replaced with another higher priority dialog like the
  one shown when quitting the app. The user remains opted out in this case.
  This object was removed in Firefox 96.0.2.
:learn_more:
  The user clicked "Learn more". The user remains opted out in this case. This
  object was removed in Firefox 96.0.2.
:learn_more_1:
  The user clicked "Learn more" on the introduction section. The user remains
  opted out in this case.
:learn_more_2:
  The user clicked "Learn more" on the main section. The user remains opted out
  in this case.
:not_now:
  The dialog was dismissed in some way without opting in. This object was
  removed in Firefox 94.0.
:not_now_2:
  The user clicked "Not now" link on main section. The user remains opted out in
  this case.
:not_now_link:
  The user clicked "Not now". The user remains opted out in this case. This
  object was removed in Firefox 96.0.2.
:reject_2:
  The user rejected the dialog and opted out.
:settings:
  The user clicked the "Customize" button. The user remains opted out in this
  case. This object was removed in Firefox 96.0.2.

Changelog
  Firefox 92.0.1
    Introduced. Objects are: ``accept``, ``settings``, ``learn_more``, and
    ``not_now``. ``not_now`` is recorded when the dialog is dismissed in any
    manner not covered by the other objects. [Bug 1723860_]

  Firefox 94.0
    Objects changed to: ``accept``, ``dismissed_escape_key``,
    ``dismissed_other``, ``learn_more``, ``not_now_link``, and ``settings``.
    [Bug 1733687_]

  Firefox 96.0.2
    Objects changed to: ``accept_2``, ``reject_2``, ``learn_more_2``,
    ``close_1``, ``not_now_2``, ``dismiss_1`` and ``dismiss_2``.
    [Bug 1745026_]

  Firefox 100.0
    Objects changed to: ``accept_2``, ``reject_2``, ``learn_more_1``,
    ``learn_more_2``, ``close_1``, ``not_now_2``, ``dismiss_1`` and
    ``dismiss_2``.
    [Bug 1761171_]

.. _1723860: https://bugzilla.mozilla.org/show_bug.cgi?id=1723860
.. _1733687: https://bugzilla.mozilla.org/show_bug.cgi?id=1733687
.. _1745026: https://bugzilla.mozilla.org/show_bug.cgi?id=1745026
.. _1761171: https://bugzilla.mozilla.org/show_bug.cgi?id=1761171

contextservices.quicksuggest.sponsored_toggled
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This event is recorded when the
``browser.urlbar.suggest.quicksuggest.sponsored`` pref is toggled. The pref can
be toggled in the following ways:

- The user can toggle it in the preferences UI.
- The user can toggle it in about:config.

The event's objects are the following:

:enabled:
  Recorded when the pref is flipped from false to true.
:disabled:
  Recorded when the pref is flipped from true to false.

Changelog
  Firefox 92.0.1
    Introduced. [Bug 1728430_]

  Firefox 96.0:
    The event is no longer recorded when the user interacts with the online
    modal dialog since the ``browser.urlbar.suggest.quicksuggest.sponsored``
    pref is no longer set when the user opts in or out. [Bug 1740965_]

.. _1728430: https://bugzilla.mozilla.org/show_bug.cgi?id=1728430
.. _1740965: https://bugzilla.mozilla.org/show_bug.cgi?id=1740965

Environment
-----------

The following preferences are recorded in telemetry environment data. For
general information on telemetry environment data in Firefox, see the
:doc:`/toolkit/components/telemetry/data/environment` document.

browser.urlbar.quicksuggest.onboardingDialogChoice
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This pref records the user's choice in the online modal dialog. If the dialog
was shown multiple times, it records the user's most recent choice. It is a
string-valued pref with the following possible values:

:<empty string>:
  The user has not made a choice (e.g., because the dialog hasn't been shown).
:accept:
  The user accepted the dialog and opted in. This object was removed in Firefox
  96.0.2.
:accept_2:
  The user accepted the dialog and opted in.
:close_1:
  The user clicked close button or something similar link on the introduction
  section. The user remains opted out in this case.
:dismiss_1:
  The user dismissed the dialog by pressing the Escape key or some unknown way
  on the introduction section. The user remains opted out in this case.
:dismiss_2:
  The user dismissed the dialog by pressing the Escape key or some unknown way
  on main section. The user remains opted out in this case.
:dismissed_escape_key:
  The user dismissed the dialog by pressing the Escape key. The user remains
  opted out in this case. This object was removed in Firefox 96.0.2.
:dismissed_other:
  The dialog was dismissed in some unknown way. One case where this can happen
  is when the dialog is replaced with another higher priority dialog like the
  one shown when quitting the app. The user remains opted out in this case. This
  object was removed in Firefox 96.0.2.
:learn_more:
  The user clicked "Learn more". The user remains opted out in this case. This
  object was removed in Firefox 96.0.2.
:learn_more_1:
  The user clicked "Learn more" on the introduction section. The user remains
  opted out in this case.
:learn_more_2:
  The user clicked "Learn more" on the main section. The user remains opted out
  in this case.
:not_now_2:
  The user clicked "Not now" link on main section. The user remains opted out in
  this case.
:not_now_link:
  The user clicked "Not now". The user remains opted out in this case. This
  object was removed in Firefox 96.0.2.
:reject_2:
  The user rejected the dialog and opted out.
:settings:
  The user clicked the "Customize" button. The user remains opted out in this
  case. This object was removed in Firefox 96.0.2.

Changelog
  Firefox 94.0
    Introduced. [Bug 1734447_]

  Firefox 96.0.2
    Added ``accept_2``, ``reject_2``, ``learn_more_2``, ``close_1``,
    ``not_now_2``, ``dismiss_1``, ``dismiss_2`` and removed ``accept``,
    ``dismissed_escape_key``, ``dismissed_other``, ``learn_more``,
    ``not_now_link``, ``settings``. [Bug 1745026_]

  Firefox 100.0
    Added ``learn_more_1``. [Bug 1761171_]

.. _1734447: https://bugzilla.mozilla.org/show_bug.cgi?id=1734447
.. _1745026: https://bugzilla.mozilla.org/show_bug.cgi?id=1745026
.. _1761171: https://bugzilla.mozilla.org/show_bug.cgi?id=1761171

browser.urlbar.quicksuggest.dataCollection.enabled
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This boolean pref records whether the user has opted in to data collection for
Firefox Suggest. It is false by default. It is set to true when the user opts in
to the online modal dialog. The user can also toggle it in the preferences UI
and about:config.

Changelog
  Firefox 94.0.2
    Introduced. [Bug 1735976_]

.. _1735976: https://bugzilla.mozilla.org/show_bug.cgi?id=1735976

browser.urlbar.suggest.quicksuggest
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This pref no longer exists and is not recorded. It was replaced with
``browser.urlbar.suggest.quicksuggest.nonsponsored`` in Firefox 94.0.2. Prior to
94.0.2, this boolean pref recorded whether suggestions in general were enabled.

Changelog
  Firefox 92.0.1
    Introduced. [Bug 1730721_]

  Firefox 94.0.2
    Replaced with ``browser.urlbar.suggest.quicksuggest.nonsponsored``. [Bug
    1735976_]

.. _1730721: https://bugzilla.mozilla.org/show_bug.cgi?id=1730721
.. _1735976: https://bugzilla.mozilla.org/show_bug.cgi?id=1735976

browser.urlbar.suggest.quicksuggest.nonsponsored
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This boolean pref records whether non-sponsored suggestions are enabled. In both
the offline and online scenarios it is true by default. The user can also toggle
it in the preferences UI and about:config.

Changelog
  Firefox 94.0.2
    Introduced. It replaces ``browser.urlbar.suggest.quicksuggest``. [Bug
    1735976_]

  Firefox 96.0:
    The pref is now true by default in the online scenario. Previously it was
    false by default in online. For users who were enrolled in the online
    scenario in older versions and who did not opt in or otherwise enable
    non-sponsored suggestions, the pref will remain false when upgrading. For
    all other users, it will default to true when/if they are enrolled in
    online. [Bug 1740965_]

.. _1735976: https://bugzilla.mozilla.org/show_bug.cgi?id=1735976
.. _1740965: https://bugzilla.mozilla.org/show_bug.cgi?id=1740965

browser.urlbar.suggest.quicksuggest.sponsored
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This boolean pref records whether sponsored suggestions are enabled. In both the
offline and online scenarios it is true by default. The user can also toggle it
in the preferences UI and about:config.

Changelog
  Firefox 92.0.1
    Introduced. [Bug 1730721_]

  Firefox 96.0:
    The pref is now true by default in the online scenario. Previously it was
    false by default in online. For users who were enrolled in the online
    scenario in older versions and who did not opt in or otherwise enable
    sponsored suggestions, the pref will remain false when upgrading. For all
    other users, it will default to true when/if they are enrolled in
    online. [Bug 1740965_]

.. _1730721: https://bugzilla.mozilla.org/show_bug.cgi?id=1730721
.. _1740965: https://bugzilla.mozilla.org/show_bug.cgi?id=1740965

Contextual Services Pings
-------------------------

The following custom telemetry pings are recorded for Firefox Suggest
suggestions. For general information on custom telemetry pings in Firefox, see
the `Custom Ping`_ document.

.. _Custom Ping: https://docs.telemetry.mozilla.org/cookbooks/new_ping.html#sending-a-custom-ping

Block
~~~~~

A block ping is recorded when the user dismisses ("blocks") a suggestion. Its
payload includes the following:

:advertiser:
  The name of the suggestion's advertiser.
:block_id:
  A unique identifier for the suggestion (a.k.a. a keywords block).
:context_id:
  A UUID representing this user. Note that it's not client_id, nor can it be
  used to link to a client_id.
:iab_category:
  The suggestion's category, either "22 - Shopping" or "5 - Education".
:improve_suggest_experience_checked:
  A boolean indicating whether the user has opted in to improving the Firefox
  Suggest experience. There are two ways for the user to opt in, either in an
  opt-in modal experiment or by toggling a switch in Firefox's settings.
:match_type:
  "best-match" if the suggestion was a best match or "firefox-suggest" if it was
  a non-best-match suggestion.
:position:
  The index of the suggestion in the list of results (1-based).
:request_id:
  A request identifier for each API request to Merino. This is only included for
  suggestions provided by Merino.
:source:
  The source of the suggestion, either "remote-settings" or "merino".

Changelog
  Firefox 101.0
    Introduced. [Bug 1764669_]

  Firefox 103.0
    ``scenario`` is removed from the payload and
    ``improve_suggest_experience_checked`` is added. [Bug 1776797_]

  Firefox 109.0
    ``source`` is added. [Bug 1800993_]

.. _1764669: https://bugzilla.mozilla.org/show_bug.cgi?id=1764669
.. _1776797: https://bugzilla.mozilla.org/show_bug.cgi?id=1776797
.. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993

Click
~~~~~

A click ping is recorded when the user picks a suggestion. Its payload includes
the following:

:advertiser:
  The name of the suggestion's advertiser.
:block_id:
  A unique identifier for the suggestion (a.k.a. a keywords block).
:context_id:
  A UUID representing this user. Note that it's not client_id, nor can it be
  used to link to a client_id.
:improve_suggest_experience_checked:
  A boolean indicating whether the user has opted in to improving the Firefox
  Suggest experience. There are two ways for the user to opt in, either in an
  opt-in modal experiment or by toggling a switch in Firefox's settings.
:match_type:
  "best-match" if the suggestion was a best match or "firefox-suggest" if it was
  a non-best-match suggestion.
:position:
  The index of the suggestion in the list of results (1-based).
:reporting_url:
  The reporting URL of the suggestion, normally pointing to the ad partner's
  reporting endpoint.
:request_id:
  A request identifier for each API request to Merino. This is only included for
  suggestions provided by Merino.
:source:
  The source of the suggestion, either "remote-settings" or "merino".

Changelog
  Firefox 87.0
    Introduced. The payload is: ``advertiser``, ``block_id``, ``position``, and
    ``reporting_url``. [Bug 1689365_]

  Firefox 92.0.1
    ``scenario`` is added to the payload. [Bug 1729576_]

  Firefox 94.0.2
    ``request_id`` is added to the payload. [Bug 1736117_]

  Firefox 99.0
    ``match_type`` is added to the payload. [Bug 1754622_]

  Firefox 103.0
    ``scenario`` is removed from the payload and
    ``improve_suggest_experience_checked`` is added. [Bug 1776797_]

  Firefox 109.0
    ``source`` is added. [Bug 1800993_]

.. _1689365: https://bugzilla.mozilla.org/show_bug.cgi?id=1689365
.. _1729576: https://bugzilla.mozilla.org/show_bug.cgi?id=1729576
.. _1736117: https://bugzilla.mozilla.org/show_bug.cgi?id=1736117
.. _1754622: https://bugzilla.mozilla.org/show_bug.cgi?id=1754622
.. _1776797: https://bugzilla.mozilla.org/show_bug.cgi?id=1776797
.. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993

Impression
~~~~~~~~~~

An impression ping is recorded when the user is shown a suggestion and the
following two conditions hold:

- The user has completed an engagement with the address bar by picking a result
  in it or by pressing the Enter key.
- At the time the user completed the engagement, a suggestion was present in the
  results.

It is also recorded when the user dismisses ("blocks") a suggestion.

The impression ping payload contains the following:

:advertiser:
  The name of the suggestion's advertiser.
:block_id:
  A unique identifier for the suggestion (a.k.a. a keywords block).
:context_id:
  A UUID representing this user. Note that it's not client_id, nor can it be
  used to link to a client_id.
:improve_suggest_experience_checked:
  A boolean indicating whether the user has opted in to improving the Firefox
  Suggest experience. There are two ways for the user to opt in, either in an
  opt-in modal experiment or by toggling a switch in Firefox's settings.
:is_clicked:
  Whether or not the user also clicked the suggestion. When true, we will also
  send a separate click ping. When the impression ping is recorded because the
  user dismissed ("blocked") the suggestion, this will be false.
:match_type:
  "best-match" if the suggestion was a best match or "firefox-suggest" if it was
  a non-best-match suggestion.
:position:
  The index of the suggestion in the list of results (1-based).
:reporting_url:
  The reporting URL of the suggestion, normally pointing to the ad partner's
  reporting endpoint.
:request_id:
  A request identifier for each API request to Merino. This is only included for
  suggestions provided by Merino.
:source:
  The source of the suggestion, either "remote-settings" or "merino".

Changelog
  Firefox 87.0
    Introduced. The payload is: ``advertiser``, ``block_id``, ``is_clicked``,
    ``matched_keywords``, ``position``, ``reporting_url``, and
    ``search_query``. ``matched_keywords`` and ``search_query`` are always
    included in the payload and are always identical: They both record the exact
    search query as typed by the user. [Bug 1689365_]

  Firefox 91.0.1 (Release and ESR)
    ``matched_keywords`` and ``search_query`` are always recorded as empty
    strings. [Bug 1725492_]

  Firefox 92.0.1
    - When the user's scenaro is "online", ``matched_keywords`` records the full
      keyword of the matching suggestion and ``search_query`` records the exact
      search query as typed by the user; otherwise both are recorded as empty
      strings. [Bug 1728188_, 1729576_]
    - ``scenario`` is added to the payload. [Bug 1729576_]

  Firefox 94.0.2
    - When the user has opted in to data collection and the matching suggestion
      is provided by remote settings, ``matched_keywords`` records the full
      keyword of the suggestion and ``search_query`` records the exact search
      query as typed by the user; otherwise both are excluded from the ping.
      [Bug 1736117_, 1735976_]
    - ``request_id`` is added to the payload. [Bug 1736117_]

  Firefox 97.0
    - Stop sending ``search_query`` and ``matched_keywords`` in the custom
      impression ping for Firefox Suggest. [Bug 1748348_]

  Firefox 99.0
    ``match_type`` is added to the payload. [Bug 1754622_]

  Firefox 101.0
    The impression ping is now also recorded when the user dismisses ("blocks")
    a suggestion. [Bug 1761059_]

  Firefox 103.0
    ``scenario`` is removed from the payload and
    ``improve_suggest_experience_checked`` is added. [Bug 1776797_]

  Firefox 109.0
    ``source`` is added. [Bug 1800993_]

.. _1689365: https://bugzilla.mozilla.org/show_bug.cgi?id=1689365
.. _1725492: https://bugzilla.mozilla.org/show_bug.cgi?id=1725492
.. _1728188: https://bugzilla.mozilla.org/show_bug.cgi?id=1728188
.. _1729576: https://bugzilla.mozilla.org/show_bug.cgi?id=1729576
.. _1736117: https://bugzilla.mozilla.org/show_bug.cgi?id=1736117
.. _1735976: https://bugzilla.mozilla.org/show_bug.cgi?id=1735976
.. _1748348: https://bugzilla.mozilla.org/show_bug.cgi?id=1748348
.. _1754622: https://bugzilla.mozilla.org/show_bug.cgi?id=1754622
.. _1761059: https://bugzilla.mozilla.org/show_bug.cgi?id=1761059
.. _1776797: https://bugzilla.mozilla.org/show_bug.cgi?id=1776797
.. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993

Nimbus Exposure Event
---------------------

A `Nimbus exposure event`_ is recorded once per app session when the user first
encounters the UI of an experiment in which they're enrolled. The timing of the
event depends on the experiment and branch.

There are two Nimbus variables that determine the timing of the event:
``experimentType`` and the deprecated ``isBestMatchExperiment``. To determine
when the exposure event is recorded for a specific experiment and branch,
examine the experiment's recipe and look for one of these variables.

Listed below are the supported values of ``experimentType`` and
``isBestMatchExperiment`` along with details on when their corresponding
exposure events are recorded.

:experimentType = "best-match":
  If the user is in a treatment branch and they did not disable best match, the
  event is recorded the first time they trigger a best match; if the user is in
  a treatment branch and they did disable best match, the event is not recorded
  at all. If the user is in the control branch, the event is recorded the first
  time they would have triggered a best match. (Users in the control branch
  cannot "disable" best match since the feature is totally hidden from them.)
:experimentType = "modal":
  If the user is in a treatment branch, the event is recorded when they are
  shown an opt-in modal. If the user is in the control branch, the event is
  recorded every time they would have been shown a modal, which is on every
  startup where another non-Suggest modal does not appear.
:isBestMatchExperiment = true:
  This is a deprecated version of ``experimentType == "best-match"``.
:All other experiments:
  For all other experiments not listed above, the event is recorded the first
  time the user triggers a Firefox Suggest suggestion.

Changelog
  Firefox 92.0
    Introduced. The event is always recorded the first time the user triggers
    a Firefox Suggest suggestion regardless of the experiment they are enrolled
    in. [Bug 1724076_, 1727392_]

  Firefox 99.0
    The ``isBestMatchExperiment = true`` case is added. [Bug 1752953_]

  Firefox 100.0
    The ``experimentType = "modal"`` case is added.
    ``isBestMatchExperiment = true`` is deprecated in favor of
    ``experimentType = "best-match"``. [Bug 1760596_]

.. _Nimbus exposure event: https://experimenter.info/jetstream/jetstream/#enrollment-vs-exposure

.. _1724076: https://bugzilla.mozilla.org/show_bug.cgi?id=1724076
.. _1727392: https://bugzilla.mozilla.org/show_bug.cgi?id=1727392
.. _1752953: https://bugzilla.mozilla.org/show_bug.cgi?id=1752953
.. _1760596: https://bugzilla.mozilla.org/show_bug.cgi?id=1760596

Merino Search Queries
---------------------

Merino is a Mozilla service that provides Firefox Suggest suggestions. Along
with remote settings on the client, it is one of two possible sources for
Firefox Suggest. When Merino integration is enabled on the client and the user
has opted in to Firefox Suggest data collection, Firefox sends everything the
user types in the address bar to the Merino server. In response, Merino finds
relevant search results from its search providers and sends them to Firefox,
where they are shown to the user in the address bar.

The user opts in to Firefox Suggest data collection when they either opt in to
the online modal dialog or they enable Firefox Suggest data collection in the
preferences UI.

Merino queries are not telemetry per se but we include them in this document
since they necessarily involve data collection.

Merino API
~~~~~~~~~~

Data that Firefox sends to the Merino server is summarized below. When Merino
integration is enabled on the client and the user has opted in to Firefox
Suggest data collection, this data is sent with every user keystroke in the
address bar.

For details on the Merino API, see the `Merino documentation`_.

.. _Merino documentation: https://mozilla-services.github.io/merino/api.html#suggest

Search Query
  The user's search query typed in the address bar.

  API parameter name: ``q``

Session ID
  A UUID that identifies the user's current search session in the address bar.
  This ID is unique per search session. A search session ends when the focus
  leaves the address bar or a timeout of 5 minutes elapses, whichever comes
  first.

  API parameter name: ``sid``

Sequence Number
  A zero-based integer that is incremented after a response is received from
  Merino. It is reset at the end of each search session along with the session
  ID.

  API parameter name: ``seq``

Client Variants
  Optional. A list of experiments or rollouts that are affecting the Firefox
  Suggest user experience. If Merino recognizes any of them, it will modify its
  behavior accordingly.

  API parameter name: ``client_variants``

Providers
  Optional. A list of providers to use for this request. If specified, only
  suggestions from the listed providers will be returned. Otherwise Merino will
  use a default set of providers.

  API parameter name: ``providers``