Experiment Event Tracking

Amplitude Experiment's end-to-end platform relies on two events, assignment and exposure, and an experiment user property per experiment, to enable experiment analysis, monitoring, and debugging.

Amplitude recommends you to use Amplitude defined exposure or assignment events as your experiment's exposure event to ensure the correct experiment user property is set when the exposure is ingested. Custom exposure events may be ingested before the experiment user property is set, which don'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. You can have up to 700 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 feasible, 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 sent to Amplitude to inform Amplitude 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¶

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

Result: