Event tracking

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

• Assignment events: convert users into registered participants.
• Exposure events: indicate when a user experiences an experiment variant.

These two events, along with an experiment user property for each experiment, power experiment analysis, monitoring, and debugging.

Use the Amplitude-defined exposure or assignment events as your experiment's exposure event so Amplitude sets the correct experiment user property when it ingests the exposure. Amplitude might ingest custom exposure events before setting the experiment user property, so those events don't count in experiment analysis.

• Assignment:
  • Experiment tracks an assignment event when it assigns a user through remote evaluation (fetch()) or server-side local evaluation (evaluate()).
  • Contains assignment information for one or more flags and experiments.
  • Useful for monitoring and debugging, or as an exposure heuristic for server-side experiments.
• Exposure:
  • Experiment tracks an exposure event when a user encounters a variant. Typically on the client side when code accesses a variant from the SDK (variant()).
  • Contains exposure information for a single flag or experiment.
  • Acts as the exposure event for client-side experiments.
  • Sets the experiment user property for the exposed flag or experiment.

Experiment user properties

Experiment uses a user property for each flag and experiment, and exposure events set or unset this property. The user property lets Experiment determine which variant the user is in for experiment analysis. Amplitude supports up to 1500 experiment user properties for each project.

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

Assignment events

Amplitude's evaluation servers or SDKs track assignment events through 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 an active flag or experiment, and to debug issues. For server-side experiments where client-side exposure tracking isn't possible, choose the Amplitude Assignment event as the exposure event when you configure 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. The property value is the assigned variant key, or off when Experiment assigns no variant.

The assignment event also contains properties such as [Experiment] Environment Name and [Experiment] <flag_key>.details, which support internal debugging.

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

Automatic assignment tracking

Experiment supports automatic assignment tracking for remote evaluation by default. Remote evaluation requests that miss the CDN cache and contain a valid user or device ID trigger an asynchronous assignment event after evaluation.

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

Expect one assignment per evaluated user, per unique evaluation result, per day.

Exposure events

An exposure event is a strictly defined analytics event that tells Experiment a user encountered a variant of an experiment or feature flag. Exposure events carry the flag key and the variant the user encountered in the event's properties.

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

Exposure event definition

You can send the exposure event through any analytics implementation or customer data platform without manipulating user properties.

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

Exposure transformation

When Amplitude ingests an $exposure event, Amplitude transforms it. Amplitude renames the event type and event properties for consistency with other Amplitude properties, then sets or unsets experiment user properties 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, Experiment doesn't track exposure events automatically.

<!--vale off-->

Exposure tracking example

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

Proxy exposure events

A proxy exposure event is a normal analytics event you select to model traffic and baseline conversion before an experiment runs. Proxy exposure events power the duration estimator and related calculations. Proxy exposure events aren't the same as the actual exposure or assignment events Amplitude uses during analysis after an experiment goes live.

Choose a proxy exposure event that best represents when a user might encounter your experiment experience. Amplitude uses historical traffic to estimate experiment duration and set baselines when the flag is inactive. The duration estimator relies on the proxy exposure event's recent traffic. Amplitude computes the "control mean" baseline from users who completed the proxy exposure event during the seven days before the experiment starts.

The activity log records proxy exposure changes, so configuration changes appear in the flag history.

Amplitude stores proxy exposure events in analysis parameters as a single ExposureEvent-shaped object, distinct from the array of actual exposure events.