Skip to main content


Optimizely Knowledge Base

Custom events in Optimizely

  • Create a custom event in Optimizely 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.

This article explains how to set up a custom event.

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 and full stack experiments, we have a dedicated section covering custom events in our developer docs

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.  Because the project JavaScript editor runs before Optimizely activates, it can be used to run custom events outside of the experiment.

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"

When creating a custom event, the API name will automatically populate the “eventName” in the API Call. To ensure that the custom event is tracked properly in your results, API names may only contain letters, numbers, hyphens, underscores, spaces and periods, and must be shorter than 64 characters.

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. You'll need to enable jQuery in project settings or include it in your code. Check out this article to learn more about jQuery and the $ variable in Optimizely.

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

Have a question about custom events? Visit the Optimizely questions on Stack Overflow to post a discussion, see what others are talking about, and check out some tips and tricks. 

Create a new custom event 

  1. Navigate to Implementation > Events.


  2. Click Create New Event.


  3. Select Custom.


  4. Under New Custom Event, enter a name for the event and an API name. Based on your entry in the API Name field, the code in the API Call field will populate the eventName.


  5. Add the API call to your site. For more information about implementing the API call, see our developer documentation.

  6. Click Save Event.

To check if your custom event is firing you can verify this within preview mode feed during the QA process and/or via the browser network console for a live running experiment.