# 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/.

# This file is for pings reported by both Firefox Desktop and the Background
# Updater task.

---
$schema: moz://mozilla.org/schemas/glean/pings/2-0-0

update:
  description: |
    This ping is sent from Firefox Desktop when a browser update is ready
    to be applied and after it was correctly applied.

    Specific expected behaviours include:
      - **The ping is generated once every time an update is downloaded, after it was verified:**
        - *for users who saw the privacy policy*,
          the ``update`` ping is sent immediately;
        - *for users who did not see the privacy policy*,
          the ``update`` ping is saved to disk and sent after the policy is displayed.
      - **If the download of the update retries or other fallback occurs**:
        the ``update`` ping will not be generated multiple times,
        but only one time once the download is complete and verified.
      - **If automatic updates are disabled**:
        when the user forces a manual update, no ``update`` ping will be generated.
      - **If updates fail to apply**:
        in some cases the client will download the same update blob and generate a new
        ``update`` ping for the same target version and build id, with a different document id.
      - **If the build update channel contains the CCK keyword**,
        the update ping will not report it but rather report a vanilla channel name
        (e.g. ``mozilla-cck-test-beta`` gets reported as ``beta``).
      - **If a profile refresh occurs before the update is applied**,
        the update ping with ``reason = success`` will not be generated.
      - **If the update is applied on a new profile, different then the one it was downloaded in**,
        the update ping with ``reason = success`` will not be generated.
      - **If a newer browser version is installed over an older**,
        the update ping with ``reason = success`` will not be generated.
  include_client_id: true
  send_if_empty: false
  reasons:
    ready: |
      The ping was generated after an update was downloaded and marked as ready to be processed.
      For non-staged updates this happens as soon as the download finishes
      and is verified while for staged updates this happens before the staging step is started.
    success: |
      The ping was generated after the browser was restarted and the update correctly applied.
  bugs:
    - https://bugzilla.mozilla.org/show_bug.cgi?id=1963871
  data_reviews:
    - https://bugzilla.mozilla.org/show_bug.cgi?id=1963871
  notification_emails:
    - install-update@mozilla.com