Track user events

Experiments let you track how users react to different variations. To measure the relative success of your experiment, you must tell Optimizely which events to track. After it aggregates enough events to produce meaningful metrics, you can evaluate your flag variations on the Experiment Results page.

As part of designing your experiment, you decide which tracked events to use as metrics. Events that track a desired user action, like a purchase, signup, or form submission, are called conversion events. They can capture anything from simple clicks and page views to purchases and scroll depth. In general, you want to track events closely associated with the user experience your experiments are updating. See How Optimizely counts conversions.

📘

Note

You should develop the practice of tracking interesting events, even if they are not behind a flag, so you can create future experiments quickly.

Event properties

Event properties let you attach additional information to an event. For example, you can add information about a product or action performed to create a more specific metric on the Experiment Results page.

During the beta period, Optimizely supports event properties as a nested object within event tags. When you call the track event method, you can include event tags as an optional key-value argument. To send event properties, use the reserved key $opt_event_properties as a nested key within the tags object.

Go to Example code for implementation examples, Create events for configuration instructions, and Create a metric using the metric builder for guidance on adding event properties to metrics.

Configuration overview

🚧

Important

The Experiment Results page only shows tracked events after a Decide method is called for the user who triggered the event.

If you do not see results on the Experiment Results page, ensure you are evaluating the feature flag before tracking conversion events.

At a high level, complete the following steps to track events:

1. In the Optimizely app or REST API, create an event with a unique key string that you will reference in your code when you call the track event method. See Create events.
2. Copy the sample integration code for the track event method that the UI generates.
3. Call the track event method to record the event you want to track. To ensure your conversion event populates the metrics on the Experiment Results page, call the track event method after users are exposed to a flag variation, that is, after you evaluate the flag for that user.
4. (Recommended) Filter out third-party bots so they do not skew your experimental results. See Filter out bots.
5. Add your events to a flag rule as metrics. See Run A/B tests, Run a multi-armed bandit optimization, and Run flag deliveries.

You can track events on the server and client using an SDK or the Agent. You can also track events using the Events API if you do not have an SDK implemented. For information, see Track across platforms.

Example code

The following Swift example shows how to call the track event method, including optional user attributes.

// Track a conversion event for the provided user with attributes
let user = optimizely.createUserContext(userId: "user123", attributes: ["logged_in":true])
  
// Track a user event
try? user.trackEvent(eventKey: "purchased")

For the other SDKs, refer to the corresponding reference guides.

• Android SDK
• C# SDK
• Flutter SDK
• Go SDK
• Java SDK
• JavaScript SDK – SDK versions 6.0.0 and later.
• JavaScript (Browser) SDK – SDK versions 5.3.5 and earlier.
• JavaScript (Node) SDK – SDK versions 5.3.5 and earlier.
• PHP SDK
• Python SDK
• React SDK
• React Native SDK
• Ruby SDK
• Swift SDK

For Optimizely Agent, see Use Optimizely Agent.

Track events across platforms

You can track events using the SDKs or, for more advanced or offline use cases, an HTTP-based integration.

If you cannot install an SDK

Use one of the following options:

• Optimizely Event API – Send events directly to Optimizely using a REST API.
• Optimizely Agent – Forward events through the Agent's /track endpoint.

If you can install an SDK

SDKs provide the following benefits:

• Consistent audience targeting – All SDKs evaluate audiences the same way.
• Shared configuration – SDKs use the same datafile and user contexts to ensure consistent experiment decisions and event tracking.
• Cross-platform flexibility – Track events and run experiments across apps, services, or devices using any SDK.

For example, use a server-side SDK (such as Python, Java, or Node) to make experiment decisions and a client-side SDK (such as JavaScript, React, iOS, or Android) to track user behavior.

If you use multiple SDKs within the same project, ensure they share the same datafile and user identifiers. For guidance, see Multiple SDK implementations.

📘

Note

You can also use cross-project events to track events across your Web Experimentation and Feature Experimentation projects.

Track numeric metrics

On the Experiment Results page, you can track nonbinary metrics such as revenue or other numeric values. For information on using reserved event tags to track nonbinary metrics, see Tag events.

Next steps

After you Create events, complete the following:

• Add events to an experiment flag rule. See Run A/B tests or Run a multi-armed bandit optimization.
• Choose how events are displayed on the Experiment Results page as metrics. See Choose metrics.

More information

For information on how Optimizely handles events, see Events: Track clicks, page views, and other visitor actions.

Also, see how Optimizely attributes a single user's events over time.