Skip to main content

Everything you need to learn Optimizely X in one place: See our resource pages for Web Experimentation and Personalization.

Optimizely Knowledge Base

Custom events in Optimizely X

This article is about Optimizely X. If you're using Optimizely Classic, check this article out instead.
relevant products:
  • Optimizely X Web Experimentation
  • Optimizely X Web Personalization

  • Create a custom event in Optimizely X to track behaviors that can't be measured in pageviews or clicks
  • Add your custom event to an experiment

Custom tracking events allow you to capture and report on visitor actions or events that might not be related exclusively to clicks or page views. Using custom events lets you track an element that isn’t a pageview or a click. 

When a custom event is triggered, it calls the Optimizely snippet and passes along the ID of the event. The snippet takes that ID and uses it to generate an HTTP request that attributes the conversion event to your experiment results.

The Optimizely snippet must be implemented on the page where the custom event is triggered. If it isn't, there is no way to transmit the ID of your custom event to your experiment results in Optimizely.

You can use Optimizely’s custom event tracking to capture revenue. For additional details on how to set this up, check out our article on revenue tracking.

Specific examples where custom events are helpful

  • Form submissions. For example, maybe there is a form on your page that does not send visitors to a unique confirmation page. You can track successful form submissions - rather than just clicks on the button - by tying a custom event to the logic on your page that qualifies the form submission and sends the user to the next step in the process. Custom events would also be useful for AJAX form submissions that do not generate a new page URL.

  • Tracking viewed pop-ups. If there is a pop-up that appears at specific instances in the flow, you can track views by triggering a custom event when the pop-up is shown.

  • Content is added to the page as the user moves through a flow, but the URL does not change. You can use the bind() function to attach event handlers to the documents element of the page, or you can bind a custom event that listens for the presence of clicks on the element when it appears.

  • Tracking dropoff within forms. If you want to track dropoff within a form and learn which fields visitors tend to fill out before clicking away, you can do so by tying a custom event to actions taken in a specific input field.

  • Tracking visitor behavior on Single-Page App frameworks, such as AngularJS, BackboneJS or EmberJS.

Format to add a custom event for web experiments

The basic format for custom events in web experiments is shown below. Depending on the event you’d like to track, you can either add the code to your website or you can add it to your experiment's shared code. Custom events can also be called from the project JavaScript.

"Shared code" refers to custom JavaScript that is shared by all variations in an experiment. "Project JavaScript" is custom JavaScript that is accessible to all projects. "Custom code" usually refers to custom CSS or JavaScript that is only used by a single variation.

Our developer docs include an example of the implementation of a common custom event goal, allowing you to track scroll depth.

For mobile app experiments, we have a dedicated section covering custom events in our developer docs, for iOS and Android

Adding a custom event to shared code will only work if the experiment is active on the page in question. If you want to track custom event goals outside the scope of the experiment, the code must be placed natively on the page.

Here is an example of the code needed to trigger a custom event goal on your page: 

// ensures the optimizely object is defined globally using
window['optimizely'] = window['optimizely'] || [];

// sends a tracking call to Optimizely for the given event name. 
  type: "event",
  eventName: "eventName"

In this code snippet, the “eventName” will be tracked and associated with the appropriate visitor/experiment/variation. Choose a value for “eventName” that correlates with the intent of your goal, for example “form_success” if you are looking to track form submits. 

Write down the value you choose for “eventName,” as you will need it later when you create the custom event in the Optimizely dashbaord. This is covered in the Create a new custom event section below. 

You can also include the call inside of a function that is called elsewhere.

var trackCustomEvent = function() {   
window['optimizely'] = window['optimizely'] || [];window['optimizely'].push({
  type: "event",
  eventName: "eventName"

You can manually trigger the Custom Event to track the number of actions that complete a specific action using jQuery.

 window['optimizely'] = window['optimizely'] || [];
$("#ButtonID").bind("mousedown", function() {     
   type: "event",
   eventName: "eventName"

Create a new custom event

  1. From the left-hand rail in the Campaigns dashboard, click Implementation. The Implementation dashboard will open.

  2. Click the Events tab to see a list of all available events. To begin adding a new custom event, click Create New Event.

  3. Next, select Custom from the list of event types. Fill in a name, an API name (it helps if the API name is similar to the event name), and choose an event category from the drop-down list.

    Notice how the code in the API Call box changes to match the name you type into the API Name field.

    Optimizely automatically updates the API call code with the name you give the API as a way of ensuring your custom event registers with your experiment whenever it's triggered. Otherwise, you might forget to make this small but critical change, which would lead to a failure to collect any of the data you need.

  4. Click Save Event to save your new custom event.

  5. Add the code in the API Call box to your site. For more information on how you or your developer would approach this, see our developer documentation.

Nice work - you've successfully created a custom event!

Have a question about custom events? Visit the Optimizely Community to post a discussion and see what others are talking about. Also, check out the Optimizely developer showcase for tips and tricks.