# Experiment Annotation (deprecated)

:::{important}
Legacy Telemetry collection APIs are now deprecated.
Please use Glean instead.
:::

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.

```js
TelemetryEnvironment.setExperimentActive(id, branch, [options={}}])
```

This removes the annotation for the experiment with the provided `id`.

```js
TelemetryEnvironment.setExperimentInactive(id)
```

This synchronously returns a dictionary containing the information for each active experiment.

```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).