Event Tracking

Experiment's end-to-end platform relies on two events:

• assignment events: The specific event of converting users into registered participant.
• exposure events: The event that indicates when a user has actually experienced an experiment variant.

These two events, as well as an experiment user property for each experiment, enable experiment analysis, monitoring, and debugging.

Use the Amplitude-defined exposure or assignment events as your experiment's exposure event to ensure that the correct experiment user property is set when the exposure is ingested. Custom exposure events might be ingested before the experiment user property is set and, therefore, won't count in experiment analysis.

Experiment user properties

Experiment uses a user property per flag and experiment, which is set or unset on both assignment and exposure events. Experiment uses this user property to determine which variant the user is in for experiment analysis purposes. Amplitude supports up to 1500 experiment user properties per project.

The format of the user property is, [Experiment] <flag_key> and the value is the variant key that the user was assigned or exposed to. Use this user property in queries for non-experiment events which occur after Experiment sets the user property to segment based on the flag or experiment variant.

Assignment events

Amplitude's evaluation servers or SDKs track assignment events as a result of either remote evaluation, or local evaluation using a server-side SDK configured for automatic assignment tracking. Use assignment events as a heuristic exposure event for server-side experiments, to monitor a flag or experiment while active, and to debug any issues. For server-side experiments where client-side exposure tracking isn't possible, choose the Amplitude Assignment event as the exposure event when you set up your experiment.

You shouldn't need to track assignment events manually.

Assignment event definition

The assignment event, [Experiment] Assignment, contains an event property, [Experiment] <flag_key>.variant, for each evaluated flag or experiment, where the property value is the assigned variant key. If no variant is assigned, the property value is set to off.

The assignment event sets or unsets experiment user properties for each assigned, or unassigned variant respectively. The assignment event contains other event properties like [Experiment] Environment Name and [Experiment] <flag_key>.details which are useful for internal debugging.

{
    "user_id": "123456789",
    "event_type": "[Experiment] Assignment",
    "event_properties": {
        "[Experiment] my-flag.variant": "off",
        "[Experiment] my-experiment.variant": "treatment"
    },
    "user_properties": {
        "$set": {
            "[Experiment] my-experiment": "treatment"
        },
        "$unset": {
            "[Experiment] my-flag": "-"
        }
    }
}

Automatic assignment tracking

Experiment supports automatic assignment tracking for remote evaluation by default. Remote evaluation requests that miss the CDN cache, and which contain a valid user or device ID, will trigger an assignment event to be tracked asynchronously after evaluation.

For server-side local evaluation, you may configure the local evaluation SDK on initialization to track assignment events on evaluate(). Amplitude deduplicates assignment events sent by server-side local evaluation SDKs for each user using an insert_id that contains the user ID, device ID, hash of a canonicalized list of assigned flags and variants, and the date stamp.

In other words, you should expect one Assignment per evaluated user, per unique evaluation result, per day.

Exposure events

An exposure event is a strictly defined analytics event that informs Experiment that a user was exposed to a variant of an experiment or feature flag. Exposure events contain the flag key and the variant of the flag or experiment that the user has been exposed to in the event's event properties.

When Amplitude ingests an exposure event, it uses the flag key and variant to set or unset user properties on the user associated with the event. Setting user properties is essential for experiment analysis queries on primary and secondary success metrics.

Exposure event definition

The exposure event is simple enough to send through any analytics implementation or customer data platform without the need to manipulate user properties.

{
    "user_id": "123456789",
    "event_type": "$exposure",
    "event_properties": {
        "flag_key": "my-experiment",
        "variant": "treatment"
    }
}

Exposure transformation

When Amplitude ingests an $exposure event, it's transformed. The event type and event properties are modified for consistency with other Amplitude properties, and experiment user properties are set or unset for accurate experiment analysis.

Automatic exposure tracking

Client-side Experiment SDKs support automatic exposure tracking through an exposure tracking provider implementation. Without an integration or custom implementation, exposure events aren't tracked automatically.

Exposure tracking example

1curl --request POST \
2         --url '' \
3         --data '{"api_key":"","events":[{"event_type":"$exposure","user_id":"","device_id":"","event_properties":{"flag_key":"","variant":""}}]}'

Proxy exposure events

Proxy exposure events are a selected analytics event used to model traffic and baseline conversion before an experiment runs. They primarily power the duration estimator and related calculations. They aren’t the same as actual exposure or assignment events used during analysis after an experiment is live.

A proxy exposure event is a normal analytics event you choose that best represents when a user may be exposed to your experiment experience. Amplitude uses historical traffic to estimate experiment duration and set baselines when the flag is inactive. The duration estimator explicitly relies on the proxy exposure event’s recent traffic. The “control mean” baseline is computed based on users who completed the proxy exposure event over the previous seven days prior to starting.

The activity log tracks when proxy exposure is changed so that configuration changes are visible in the flag history.

In analysis parameters, proxy exposure events are stored as a single ExposureEvent-shaped object (distinct from the array of actual exposure events).