# 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.
      The feature began rolling out to all users with Firefox 115, and was
      permanently enabled in Firefox 119.
    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
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1851495
    data_reviews:
      - 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=1851495
    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
      is_private:
        description:
          Indicates if the page was loaded while in Private Browsing Mode.
          Added in Firefox 120.
        type: boolean
      is_signed_in:
        description:
          Indicates if the page was loaded while the user is signed in to a
          provider's account. Added in Firefox 127.
        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
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1849371
    data_reviews:
      - 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=1849371
    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`,
          `clicked_accept`,
          `clicked_reject`,
          `clicked_more_options`,
          `expanded`,
          `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`,
          `cookie_banner`,
          `incontent_searchbox`,
          `non_ads_link`,
          `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
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1849371
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1816728
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1849371
    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`,
          `cookie_banner`,
          `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

  categorization:
    type: event
    description: >
      A high-level categorization of a SERP (a best guess as to its topic),
      using buckets such as "sports" or "travel".
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1868476
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1869064
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1887686
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1892267
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1868476
    data_sensitivity:
      - stored_content
    notification_emails:
      - fx-search-telemetry@mozilla.com
      - rev-data@mozilla.com
    expires: never
    extra_keys:
      sponsored_category:
        description: >
          An index corresponding to a broad category for the SERP, derived from
          sponsored domains.
        type: quantity
      sponsored_num_domains:
        description: >
          The total number of sponsored domains used in the categorization
          process for the SERP.
        type: quantity
      sponsored_num_unknown:
        description: >
          The count of sponsored domains extracted from the SERP that are not
          found in the domain-to-categories mapping.
        type: quantity
      sponsored_num_inconclusive:
        description: >
          The count of sponsored domains extracted from the SERP that are found
          in the domain-to-categories mapping but are deemed inconclusive.
        type: quantity
      organic_category:
        description: >
          An index corresponding to a broad category for the SERP, derived from
          organic domains.
        type: quantity
      organic_num_domains:
        description: >
          The total number of organic domains used in the categorization
          process for the SERP.
        type: quantity
      organic_num_unknown:
        description: >
          The count of organic domains extracted from the SERP that are not
          found in the domain-to-categories mapping.
        type: quantity
      organic_num_inconclusive:
        description: >
          The count of organic domains extracted from the SERP that are found
          in the domain-to-categories mapping but are deemed inconclusive.
        type: quantity
      region:
        description: >
          A two-letter country code indicating where the SERP was loaded.
        type: string
      channel:
        description: >
          The type of update channel, for example: “nightly”, “beta”, “release”.
        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
      app_version:
        description: >
          The Firefox major version used, for example: 126.
        type: quantity
      mappings_version:
        description: >
          Version number for the Remote Settings attachments used to generate
          the domain-to-categories map used in the SERP categorization process.
        type: quantity
      is_shopping_page:
        description: >
          Indicates if the page is a shopping page.
        type: boolean
      num_ads_hidden:
        description: >
          Number of ads hidden on the page at the time of categorizing the
          page.
        type: quantity
      num_ads_loaded:
        description: >
          Number of ads loaded on the page at the time of categorizing the
          page.
        type: quantity
      num_ads_visible:
        description: >
          Number of ads visible on the page at the time of categorizing the
          page.
        type: quantity
      num_ads_clicked:
        description: >
          Number of ads clicked on the page.
        type: quantity
    send_in_pings:
      - serp-categorization

search_with:
  reporting_url:
    type: url
    description: >
      The external url to report this interaction to.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1870138
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1870138
    data_sensitivity:
      - web_activity
    notification_emails:
      - mkaply@mozilla.com
    expires: never
    send_in_pings:
      - search-with

  context_id:
    type: uuid
    description: >
      An identifier for Contextual Services user interaction pings. This is
      used internally for counting unique users as well as for anti-fraud. It
      is shared with other Contextual Services. It is not shared externally.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1870138
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1870138#c3
    data_sensitivity:
      - technical
    notification_emails:
      - mkaply@mozilla.com
    expires: never
    send_in_pings:
      - search-with