# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at http://mozilla.org/MPL/2.0/.

# Adding a new metric? We have docs for that!
# https://firefox-source-docs.mozilla.org/toolkit/components/glean/user/new_definitions_file.html

---
$schema: moz://mozilla.org/schemas/glean/metrics/2-0-0
$tags:
  - "Firefox :: Address Bar"

urlbar:
  abandonment:
    type: event
    description: Recorded when the user abandons a search (blurring the urlbar).
    extra_keys:
      sap:
        description: >
          `sap` is the meaning of `search access point`. It records where the
          user started the search action from. The possible values are: `urlbar`
          , `handoff`, `urlbar_newtab` and `urlbar_addonpage`.
        type: string
      interaction:
        description: >
          How the user started the search action. The possible values are:
          `typed`, `pasted`, `topsite_search` (clicked on a topsite search
          shortcut), `topsites` (selected a topsite result with empty search
          string), `returned` (The user abandoned a search, then returned to it)
          , `restarted` (The user abandoned a search, then returned to it,
          cleared it and typed a completely different string), `refined` (The
          user abandoned a search, then returned to it, and partially modified
          the string), `persisted_search_terms` (The user returned to a previous
          successful search that persisted terms in the urlbar),
          `persisted_search_terms_restarted` (The user returned to a previous
          successful search that persisted terms in the urlbar, then cleared it
          and typed a completely different string) and
          `persisted_search_terms_refined` (The user returned to a previous
          successful search that persisted terms in the urlbar, and partially
          modified the string).
        type: string
      search_mode:
        description: >
          If the urlbar is in search mode, thus restricting results to a
          specific search engine or local source, this is set to the search mode
          source. The possible sources are: `actions`, `bookmarks`, `history`,
          `search_engine`, and `tabs`. If search mode is active but the source
          did not fall into any of these categories, this will be `unknown`. If
          search mode is not active, this will be an empty string.
        type: string
      n_chars:
        description: >
          The length of string used for the search. It includes whitespaces.
        type: quantity
      n_words:
        description: >
          The length of words used for the search. The words are made by
          splitting the search string by whitespaces, thus this doesn’t support
          CJK languages. For performance reasons a maximum of 255 characters are
          considered when splitting.
        type: quantity
      n_results:
        description: >
          The number of results shown to the user. If this is high the results
          list below may be truncated due to technical limitations. Also note in
          that case not all the results may be physically visible due to the
          screen size limitation.
        type: quantity
      groups:
        description: >
          Comma separated list of result groups in the order they were shown to
          the user. The groups may be repeated, since the list will match 1:1
          the results list, so we can link each result to a group. The possible
          group names are: `heuristic`, `adaptive_history`, `search_history`,
          `search_suggest`, `top_pick`, `top_site`, `remote_tab`, `addon`,
          `general`, `suggest`, `about_page` and `suggested_index`. If the group
          did not fall into any of these, this will be `unknown` and a bug
          should be filed to investigate it.
        type: string
      results:
        description: >
          Comma separated list of result types in the order they were shown to
          the user. The possible result types are: `autofill_about`,
          `autofill_adaptive`, `autofill_origin`, `autofill_url`,
          `autofill_unknown`, `bookmark`, `history`, `keyword`, `search_engine`,
          `search_suggest`, `search_history`, `url`, `action`, `tab`,
          `remote_tab`, `addon`, `tip_onboard`, `tip_persist`, `tip_redirect`,
          `tip_unknown`, `intervention_clear`, `intervention_refresh`,
          `intervention_update`, `intervention_unknown`, `tab_to_search`,
          `top_site`, `calc`, `unit`, `suggest_sponsor` and
          `suggest_non_sponsor`. If the result type did not fall into any of
          these, this will be `unknown` and a bug should be filed to investigate
          it.
        type: string
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1800414
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1805717
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1800414#c2
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1805717#c4
    data_sensitivity:
      - interaction
    notification_emails:
      - fx-search-telemetry@mozilla.com
    expires: never
  engagement:
    type: event
    description: Recorded when the user executes an action on a result.
    extra_keys:
      sap:
        description: >
          `sap` is the meaning of `search access point`. It records where the
          user started the search action from. The possible values are: `urlbar`
          , `handoff`, `urlbar_newtab` and `urlbar_addonpage`.
        type: string
      interaction:
        description: >
          How the user started the search action. The possible values are:
          `typed`, `pasted`, `topsite_search` (clicked on a topsite search
          shortcut), `topsites` (selected a topsite result with empty search
          string), `returned` (The user abandoned a search, then returned to it)
          , `restarted` (The user abandoned a search, then returned to it,
          cleared it and typed a completely different string), `refined` (The
          user abandoned a search, then returned to it, and partially modified
          the string), `persisted_search_terms` (The user returned to a previous
          successful search that persisted terms in the urlbar),
          `persisted_search_terms_restarted` (The user returned to a previous
          successful search that persisted terms in the urlbar, then cleared it
          and typed a completely different string) and
          `persisted_search_terms_refined` (The user returned to a previous
          successful search that persisted terms in the urlbar, and partially
          modified the string).
        type: string
      search_mode:
        description: >
          If the urlbar is in search mode, thus restricting results to a
          specific search engine or local source, this is set to the search mode
          source. The possible sources are: `actions`, `bookmarks`, `history`,
          `search_engine`, and `tabs`. If search mode is active but the source
          did not fall into any of these categories, this will be `unknown`. If
          search mode is not active, this will be an empty string.
        type: string
      n_chars:
        description: >
          The length of string used for the search. It includes whitespaces.
        type: quantity
      n_words:
        description: >
          The length of words used for the search. The words are made by
          splitting the search string by whitespaces, thus this doesn’t support
          CJK languages. For performance reasons a maximum of 255 characters are
          considered when splitting.
        type: quantity
      n_results:
        description: >
          The number of results shown to the user. If this is high the results
          list below may be truncated due to technical limitations. Also note in
          that case not all the results may be physically visible due to the
          screen size limitation.
        type: quantity
      selected_result:
        description: >
          The type of the result the user selected. The possible result types
          are: `autofill_about`, `autofill_adaptive`, `autofill_origin`,
          `autofill_url`, `autofill_unknown`, `bookmark`, `history`, `keyword`,
          `search_engine`, `search_suggest`, `search_history`, `url`, `action`,
          `tab`, `remote_tab`, `addon`, `tip_onboard`, `tip_persist`,
          `tip_redirect`, `tip_unknown`, `intervention_clear`,
          `intervention_refresh`, `intervention_update`, `intervention_unknown`,
          `tab_to_search`, `top_site`, `calc`, `unit`, `suggest_sponsor` and
          `suggest_non_sponsor`. If the result type did not fall into any of
          these, this will be `unknown`.
        type: string
      selected_result_subtype:
        description: >
          The subtype of the result the user selected. Currently, only the
          action of the quick actions is the target to this. The possible values
          are: `addon`, `bookmarks`, `clear`, `downloads`, `extensions`,
          `inspect`, `logins`, `plugins`, `print`, `private`, `refresh`,
          `restart`, `screenshot`, `settings`, `themes`, `update` and
          `viewsource`. Otherwise, an empty string is returned.
        type: string
      provider:
        description: >
          The name of the `UrlbarProvider` that provided the selected result.
          The possible values are: `AboutPages`, `AliasEngines`, `Autofill`,
          `BookmarkKeywords`, `calculator`, `UrlbarProviderContextualSearch`,
          `HeuristicFallback`, `InputHistory`, `UrlbarProviderInterventions`,
          `Omnibox`, `OpenTabs`, `Places`, `PreloadedSites`, `PrivateSearch`,
          `quickactions`, `UrlbarProviderQuickSuggest`, `RemoteTabs`,
          `SearchSuggestions`, `UrlbarProviderSearchTips`, `TabToSearch`,
          `TokenAliasEngines`, `UrlbarProviderTopSites`, `UnitConversion` and
          `UnifiedComplete`.
        type: string
      engagement_type:
        description: >
          Records how the user selected the result. The possible values are:
          `click`, `enter`, `drop_go`, `paste_go`, `dismiss`, `help`.
        type: string
      groups:
        description: >
          Comma separated list of result groups in the order they were shown to
          the user. The groups may be repeated, since the list will match 1:1
          the results list, so we can link each result to a group. The possible
          group names are: `heuristic`, `adaptive_history`, `search_history`,
          `search_suggest`, `top_pick`, `top_site`, `remote_tab`, `addon`,
          `general`, `suggest`, `about_page` and `suggested_index`. If the group
          did not fall into any of these, this will be `unknown` and a bug
          should be filed to investigate it.
        type: string
      results:
        description: >
          Comma separated list of result types in the order they were shown to
          the user. The possible result types are: `autofill_about`,
          `autofill_adaptive`, `autofill_origin`, `autofill_url`,
          `autofill_unknown`, `bookmark`, `history`, `keyword`, `search_engine`,
          `search_suggest`, `search_history`, `url`, `action`, `tab`,
          `remote_tab`, `addon`, `tip_onboard`, `tip_persist`, `tip_redirect`,
          `tip_unknown`, `intervention_clear`, `intervention_refresh`,
          `intervention_update`, `intervention_unknown`, `tab_to_search`,
          `top_site`, `calc`, `unit`, `suggest_sponsor` and
          `suggest_non_sponsor`. If the result type did not fall into any of
          these, this will be `unknown` and a bug should be filed to investigate
          it.
        type: string
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1797265
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1805717
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1797265#c3
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1805717#c4
    data_sensitivity:
      - interaction
    notification_emails:
      - fx-search-telemetry@mozilla.com
    expires: never
  impression:
    type: event
    description: Recorded when urlbar results are shown to the user.
    extra_keys:
      reason:
        description: Reason for the impression.
        type: string
      sap:
        description: >
          `sap` is the meaning of `search access point`. It records where the
          user started the search action from. The possible values are: `urlbar`
          , `handoff`, `urlbar_newtab` and `urlbar_addonpage`.
        type: string
      interaction:
        description: >
          How the user started the search action. The possible values are:
          `typed`, `pasted`, `topsite_search` (clicked on a topsite search
          shortcut), `topsites` (selected a topsite result with empty search
          string), `returned` (The user abandoned a search, then returned to it)
          , `restarted` (The user abandoned a search, then returned to it,
          cleared it and typed a completely different string), `refined` (The
          user abandoned a search, then returned to it, and partially modified
          the string), `persisted_search_terms` (The user returned to a previous
          successful search that persisted terms in the urlbar),
          `persisted_search_terms_restarted` (The user returned to a previous
          successful search that persisted terms in the urlbar, then cleared it
          and typed a completely different string) and
          `persisted_search_terms_refined` (The user returned to a previous
          successful search that persisted terms in the urlbar, and partially
          modified the string).
        type: string
      search_mode:
        description: >
          If the urlbar is in search mode, thus restricting results to a
          specific search engine or local source, this is set to the search mode
          source. The possible sources are: `actions`, `bookmarks`, `history`,
          `search_engine`, and `tabs`. If search mode is active but the source
          did not fall into any of these categories, this will be `unknown`. If
          search mode is not active, this will be an empty string.
        type: string
      n_chars:
        description: >
          The length of string used for the search. It includes whitespaces.
        type: quantity
      n_words:
        description: >
          The length of words used for the search. The words are made by
          splitting the search string by whitespaces, thus this doesn’t support
          CJK languages. For performance reasons a maximum of 255 characters are
          considered when splitting.
        type: quantity
      n_results:
        description: >
          The number of results shown to the user. If this is high the results
          list below may be truncated due to technical limitations. Also note in
          that case not all the results may be physically visible due to the
          screen size limitation.
        type: quantity
      groups:
        description: >
          Comma separated list of result groups in the order they were shown to
          the user. The groups may be repeated, since the list will match 1:1
          the results list, so we can link each result to a group. The possible
          group names are: `heuristic`, `adaptive_history`, `search_history`,
          `search_suggest`, `top_pick`, `top_site`, `remote_tab`, `addon`,
          `general`, `suggest`, `about_page` and `suggested_index`. If the group
          did not fall into any of these, this will be `unknown` and a bug
          should be filed to investigate it.
        type: string
      results:
        description: >
          Comma separated list of result types in the order they were shown to
          the user. The possible result types are: `autofill_about`,
          `autofill_adaptive`, `autofill_origin`, `autofill_url`,
          `autofill_unknown`, `bookmark`, `history`, `keyword`, `search_engine`,
          `search_suggest`, `search_history`, `url`, `action`, `tab`,
          `remote_tab`, `addon`, `tip_onboard`, `tip_persist`, `tip_redirect`,
          `tip_unknown`, `intervention_clear`, `intervention_refresh`,
          `intervention_update`, `intervention_unknown`, `tab_to_search`,
          `top_site`, `calc`, `unit`, `suggest_sponsor` and
          `suggest_non_sponsor`. If the result type did not fall into any of
          these, this will be `unknown` and a bug should be filed to investigate
          it.
        type: string
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1800579
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1805717
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1800579#c4
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1805717#c4
    data_sensitivity:
      - interaction
    notification_emails:
      - fx-search-telemetry@mozilla.com
    expires: never