# 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 :: Search'

newtab.search:
  issued:
    type: event
    description: >
      When Firefox was asked to issue a search from a Search Access Point (SAP)
      on a newtab page.
      Doesn't record searches in Private Browsing Mode unless
      `browser.engagement.search_counts.pbm` is set to `true`.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1766887
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1786670
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1817105
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1766887
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1786670#c3
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1817105#c11
    data_sensitivity:
      - interaction
    notification_emails:
      - anicholson@mozilla.com
      - chutten@mozilla.com
      - mmccorquodale@mozilla.com
      - najiang@mozilla.com
      - lina@mozilla.com
    expires: never
    extra_keys:
      newtab_visit_id: &newtab_visit_id
        description: >
          The id of the newtab visit that originated the search.
          Should always be present for handoff searches.
          TODO(bug 1774597): for searches done without handoff (e.g. with
          `browser.newtabpage.activity-stream.improvesearch.handoffToAwesomebar`
          set to `false`), the active newtab visit id is unknown.
        type: string
      search_access_point: &search_access_point
        description: >
          One of the search access points available on the new tab like
          * `urlbar_handoff`
          * `about_home`
          * `about_newtab`
        type: string
      telemetry_id: &telemetry_id
        description: >
          The search engine's `telemetryId`, like `google-b-d`.
          This is set to be a telemetry-specific id for app-provided engines,
          and is `other-<name>` for others (where `<name>` is the engine's
          WebExtension name).
        type: string
    send_in_pings:
      - newtab

newtab.search.ad:
  impression:
    type: event
    description: >
      Recorded when a newtab visit resulted in a search that
      loaded a Search Engine Result Page (SERP) that contains an ad link.
      And the SERP is visible.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1766887
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1786670
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1817105
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1766887
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1786670#c3
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1817105#c11
    data_sensitivity:
      - interaction
    notification_emails:
      - anicholson@mozilla.com
      - chutten@mozilla.com
      - mmccorquodale@mozilla.com
      - najiang@mozilla.com
      - lina@mozilla.com
    expires: never
    extra_keys:
      newtab_visit_id: *newtab_visit_id
      search_access_point: *search_access_point
      is_follow_on: &is_follow_on
        description: >
          Whether the preceding search happened on a search results page.
        type: boolean
      is_tagged: &is_tagged
        description: >
          Whether the preceding search was tagged with a partner code.
        type: boolean
      telemetry_id: *telemetry_id
    send_in_pings:
      - newtab

  click:
    type: event
    description: >
      Recorded when an ad link is clicked on a Search Engine Result Page (SERP)
      which was loaded by a seach that began on a newtab page.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1766887
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1786670
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1817105
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1766887
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1786670#c3
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1817105#c11
    data_sensitivity:
      - interaction
    notification_emails:
      - anicholson@mozilla.com
      - chutten@mozilla.com
      - mmccorquodale@mozilla.com
      - najiang@mozilla.com
      - lina@mozilla.com
    expires: never
    extra_keys:
      newtab_visit_id: *newtab_visit_id
      search_access_point: *search_access_point
      is_follow_on: *is_follow_on
      is_tagged: *is_tagged
      telemetry_id: *telemetry_id
    send_in_pings:
      - newtab

serp:
  impression:
    type: event
    description: >
      Recorded when a search engine results page (SERP) is shown to a user.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1813162
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1824543
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1816736
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1816738
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1829953
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1813162
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1824543
    data_sensitivity:
      - interaction
    notification_emails:
      - fx-search-telemetry@mozilla.com
      - rev-data@mozilla.com
    expires: never
    extra_keys:
      impression_id: &impression_id
        description: >
          A uuid to link SERP events to user's engagement events.
        type: string
      provider:
        description: >
          The name of the provider.
        type: string
      tagged:
        description: >
          Whether the search is tagged (true) or organic (false).
        type: boolean
      partner_code:
        description: >
          Any partner_code parsing in the URL or an empty string if not
          available.
        type: string
      source:
        description: >
          How the user arrived at the SERP.
          Possible values are:
          `urlbar`, `urlbar_handoff`, `urlbar_searchmode`, `urlbar_persisted`,
          `searchbar`, `contextmenu`, `webextension`, `system`, `reload`,
          `tabhistory`, `follow_on_from_refine_on_incontent_search`,
          `follow_on_from_refine_on_SERP`, `opened_in_new_tab`, `unknown`.
          This will be `unknown` if we cannot determine the source.
        type: string
      shopping_tab_displayed:
        description:
          Indicates if the shopping tab is displayed.
        type: boolean
      is_shopping_page:
        description:
          Indicates if the page is a shopping page.
        type: boolean

  engagement:
    type: event
    description: >
      Recorded user actions on a SERP.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1814773
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1816730
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1816735
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1814773
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1816730
    data_sensitivity:
      - interaction
    notification_emails:
      - fx-search-telemetry@mozilla.com
      - rev-data@mozilla.com
    expires: never
    extra_keys:
      impression_id: *impression_id
      action:
        description: >
          The action taken on the page.
          Possible values are `clicked`, `expanded`, and `submitted`.
        type: string
      target:
        description: >
          The target component used to trigger the action.
          Possible values are:
          `ad_carousel`,
          `ad_image_row`,
          `ad_link`,
          `ad_sidebar`,
          `ad_sitelink`,
          `incontent_searchbox`,
          `refined_search_buttons`,
          `shopping_tab`.
        type: string

  ad_impression:
    type: event
    description: >
      Recorded when a user loads a SERP and ads are detected.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1816728
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1816729
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1816728
    data_sensitivity:
      - interaction
    notification_emails:
      - fx-search-telemetry@mozilla.com
      - rev-data@mozilla.com
    expires: never
    extra_keys:
      impression_id: *impression_id
      component:
        description: >
          Type of components on a SERP. Possible values are:
          `ad_carousel`,
          `ad_image_row`,
          `ad_link`,
          `ad_sidebar`,
          `ad_sitelink`,
          `refined_search_buttons`,
          `shopping_tab`.
          Defaults to `ad_link`.
        type: string
      ads_loaded:
        description: >
          Number of ads loaded for this component. They may or
          may not be visible on the page.
        type: quantity
      ads_visible:
        description: >
          Number of ads visible for this component. An ad can be
          considered visible if was within the browser window
          by the time the impression was recorded.
        type: quantity
      ads_hidden:
        description: >
          Number of ads hidden for this component. These are ads that
          are loaded in the DOM but hidden via CSS and/or Javascript.
        type: quantity

  abandonment:
    type: event
    description: >
      Recorded when there is no engagement with the SERP before the tab is
      closed, the window is closed, the app is closed, or the tab is navigated
      away from.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1814776
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1814776
    data_sensitivity:
      - interaction
    notification_emails:
      - fx-search-telemetry@mozilla.com
      - rev-data@mozilla.com
    expires: never
    extra_keys:
      impression_id: *impression_id
      reason:
        description: >
          Why the SERP is deemed abandoned.
          Possible values are:
          `tab_close`, `window_close`, `navigation`
        type: string

  categorization_duration:
    type: timing_distribution
    time_unit: millisecond
    description: >
      The time it takes to categorize elements on a SERP.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1834100
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1834100
    data_sensitivity:
      - technical
    notification_emails:
      - fx-search-telemetry@mozilla.com
    expires: never