Adding upstream version 115.7.0esr.upstream/115.7.0esr

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 41 insertions, 0 deletions

diff --git a/toolkit/components/telemetry/docs/collection/experiments.rst b/toolkit/components/telemetry/docs/collection/experiments.rst
new file mode 100644
index 0000000000..d9c926fcea
--- /dev/null
+++ b/toolkit/components/telemetry/docs/collection/experiments.rst
@@ -0,0 +1,41 @@
+=====================
+Experiment Annotation
+=====================
+This API allows privileged JavaScript to annotate the :doc:`../data/environment` with any experiments a client is participating in.
+
+The experiment annotations are sent with any ping that includes the :doc:`../data/environment` data.
+
+The JS API
+==========
+Privileged JavaScript code can annotate experiments using the functions exposed by ``TelemetryEnvironment.sys.mjs``.
+
+The following function adds an annotation to the environment for the provided ``id``, ``branch`` and ``options``. Calling this function repeatedly with the same ``id`` will overwrite the state and trigger new subsessions (subject to throttling).
+``options`` is an object that may contain ``type`` to tag the experiment with a specific type or ``enrollmentId`` to tag the enrollment in this experiment with an identifier.
+
+.. code-block:: js
+
+    TelemetryEnvironment.setExperimentActive(id, branch, [options={}}])
+
+This removes the annotation for the experiment with the provided ``id``.
+
+.. code-block:: js
+
+    TelemetryEnvironment.setExperimentInactive(id)
+
+This synchronously returns a dictionary containing the information for each active experiment.
+
+.. code-block:: js
+
+    TelemetryEnvironment.getActiveExperiments()
+
+.. note::
+
+    Both ``setExperimentActive`` and ``setExperimentInactive`` trigger a new subsession. However
+    the latter only does so if there was an active experiment with the provided ``id``.
+
+Limits and restrictions
+-----------------------
+To prevent abuses, the content of the experiment ``id`` and ``branch`` is limited to
+100 characters in length.
+``type`` is limited to a length of 20 characters.
+``enrollmentId`` is limited to 40 characters (chosen to be just a little longer than the 36-character long GUID text representation).