
Common ping format
==================

This defines the top-level structure of a Telemetry ping.
It contains basic information shared between different ping types, which enables proper storage and processing of the raw pings server-side.

It also contains optional further information:

* the :doc:`environment data <../data/environment>`, which contains important info to correlate the measurements against
* the ``clientId``, a UUID identifying a profile and allowing profile-oriented correlation of data
* the ``profileGroupId``, a UUID identifying the profile's group on a single device and allowing user-oriented correlation of data

*Note:* These are not submitted with all ping types due to privacy concerns. This and the data it that can be correlated against is inspected under the `data collection policy <https://wiki.mozilla.org/Firefox/Data_Collection>`_.

Finally, the structure also contains the `payload`, which is the specific data submitted for the respective *ping type*.

Structure:

.. code-block:: js

    {
      type: <string>, // "main", "activation", "optout", "saved-session", ...
      id: <UUID>, // a UUID that identifies this ping
      creationDate: <ISO date>, // the date the ping was generated
      version: <number>, // the version of the ping format, currently 4

      application: {
        architecture: <string>, // build architecture, e.g. x86
        buildId: <string>, // "20141126041045"
        name: <string>, // "Firefox"
        version: <string>, // "35.0"
        displayVersion: <string>, // "35.0b3"
        vendor: <string>, // "Mozilla"
        platformVersion: <string>, // "35.0"
        xpcomAbi: <string>, // e.g. "x86-msvc"
        channel: <string>, // "beta"
      },

      clientId: <UUID>, // optional
      profileGroupId: <UUID>, // optional
      environment: { ... }, // optional, not all pings contain the environment
      payload: { ... }, // the actual payload data for this ping type
    }
