1
2"new-profile" ping
3==================
4
5This opt-out ping is sent from Firefox Desktop 30 minutes after the browser is started, on the first session
6of a newly created profile. If the first session of a newly-created profile was shorter than 30 minutes, it
7gets sent using the :doc:`../internals/pingsender` at shutdown.
8
9.. note::
10
11  We don't sent the ping immediately after Telemetry completes initialization to give the user enough
12  time to tweak their data collection preferences.
13
14Structure:
15
16.. code-block:: js
17
18    {
19      type: "new-profile",
20      ... common ping data
21      clientId: <UUID>,
22      environment: { ... },
23      payload: {
24        reason: "startup", // or "shutdown"
25        processes: { ... }
26      }
27    }
28
29payload.reason
30--------------
31If this field contains ``startup``, then the ping was generated at the scheduled time after
32startup. If it contains ``shutdown``, then the browser was closed before the time the
33ping was scheduled. In the latter case, the ping is generated during shutdown and sent
34using the :doc:`../internals/pingsender`.
35
36processes
37---------
38This section contains per-process data.
39
40Structure:
41
42.. code-block:: js
43
44    "processes" : {
45      "parent": {
46        "scalars": {...}
47      }
48    }
49
50scalars
51~~~~~~~
52This section contains the :doc:`../collection/scalars` that are valid for the ``new-profile`` ping,
53that is the ``record_into_store`` list contains ``new-profile``.
54Scalars are only submitted if data was added to them.
55The recorded scalars are described in the `Scalars.yaml <https://searchfox.org/mozilla-central/source/toolkit/components/telemetry/Scalars.yaml>`_ file.
56
57Duplicate pings
58---------------
59We expect a low fraction of duplicates of this ping, mostly due to crashes happening
60right after sending the ping and before the telemetry state gets flushed to the disk. This should
61be fairly low in practice and manageable during the analysis phase.
62
63Expected behaviours
64-------------------
65The following is a list of conditions and expected behaviours for the ``new-profile`` ping:
66
67- **The ping is generated at the browser shutdown on a new profile, after the privacy policy is displayed:**
68
69  - *for an user initiated browser shutdown*, ``new-profile`` is sent immediately using the :doc:`../internals/pingsender`;
70  - *for a browser shutdown triggered by OS shutdown*, ``new-profile`` is saved to disk and sent next time the browser restarts.
71- **The ping is generated before the privacy policy is displayed**: ``new-profile`` is saved to disk and sent
72  next time the browser restarts.
73- **The ping is set to be generated and Telemetry is disabled**: ``new-profile`` is never sent, even if Telemetry is
74  turned back on later.
75- **Firefox crashes before the ping can be generated**: ``new-profile`` will be scheduled to be generated and
76  sent again on the next restart.
77- **User performs a profile refresh**:
78
79  - *the ping was already sent*: ``new-profile`` will not be sent again.
80  - *the ping was not sent*: ``new-profile`` will be generated and sent.
81  - *the refresh happens immediately after the profile creation, before the policy is shown*: ``new-profile`` will not be sent again.
82- **Firefox is run with an old profile that already sent Telemetry data**: ``new-profile`` will not be generated
83  nor sent.
84