# "update" ping

This opt-out ping is sent from Firefox Desktop when a browser update is ready to be applied and after it was correctly applied.

Structure:

```js
{
  type: "update",
  ... common ping data
  clientId: <UUID>,
  profileGroupId: <UUID>,
  environment: { ... },
  payload: {
    reason: <string>, // "ready", "success"
    targetChannel: <string>, // "nightly" (only present for reason = "ready")
    targetVersion: <string>, // "56.0a1" (only present for reason = "ready")
    targetBuildId: <string>, // "20080811053724" (only present for reason = "ready")
    targetDisplayVersion: <string>, // "56.0a1" (only present for reason = "ready")
    previousChannel: <string>, // "nightly" or null (only present for reason = "success")
    previousVersion: <string>, // "55.0a1" (only present for reason = "success")
    previousBuildId: <string>, // "20080810053724" (only present for reason = "success")
  }
}
```

## payload.reason

This field supports the following values:

- `ready` meaning that 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.

## payload.targetChannel

The Firefox channel the update was fetched from (only valid for pings with reason "ready").

## payload.targetVersion

The Firefox version the browser is updating to. Follows the same format as application.version (only valid for pings with reason "ready").

## payload.targetBuildId

The Firefox build id the browser is updating to. Follows the same format as application.buildId (only valid for pings with reason "ready").

## payload.targetDisplayVersion

The Firefox display version the browser is updating to. This may contain a different value than `targetVersion`, e.g. for the `Beta` channel this field will report the beta suffix while `targetVersion` will only report the version number.

## payload.previousChannel

The Firefox channel the profile was on before the update was applied (only valid for pings with reason "success").
This can be `null`.

## payload.previousVersion

The Firefox version the browser is updating from. Follows the same format as application.version (only valid for pings with reason "success").

## payload.previousBuildId

The Firefox build id the browser is updating from. Follows the same format as application.buildId (only valid for pings with reason "success").

## Expected behaviours

The following is a list of conditions and expected behaviours for the `update` ping:

- **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.