Custom events

  • Updated
  • Optimizely Web Experimentation
  • Optimizely Personalization

You can create custom events to track behaviors that cannot be measured in pageviews or clicks. Custom tracking events let you 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 is not a page view or a click.

When a custom event is triggered, it calls the Optimizely Web Experimentation 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 Web Experimentation snippet must be implemented on the page where the custom event is triggered. If it is not, the ID of your custom event to your experiment or campaign results cannot be transmitted to Optimizely.

You can use custom event tracking to capture revenue. See Set up events and Set up revenue tracking in Optimizely Web Experimentation.

Specific examples of helpful custom events

  • Form submissions – For example, a form on your page does not send visitors to a unique confirmation page. You can track successful form submissions—instead of only button clicks—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 are also useful for AJAX form submissions that do not generate a new page URL.

  • Track viewed pop-ups – If you have pop-ups that display at specific instances in the flow, you can track views by triggering a custom event when the pop-up displays.

  • 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 displays.

  • Track 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.

  • Track visitor behavior on Single-Page App frameworks – Such as AngularJS, BackboneJS, or EmberJS.

Create a custom event

  1. Go to Implementation > Events.

  2. Click Create New Event.

  3. Select Custom.

  4. Enter a Name for the event

  5. (Optional) Enter a description.

  6. Enter an API Name. Based on your entry in the API Name field, the code in the API Call field populates the eventName. To ensure the custom event is tracked properly in your results, API names must be shorter than 64 characters and contain only letters, numbers, hyphens, underscores, spaces, and periods. Choose a value for API Name that correlates with the intent of your metric. For example, form_success if you are looking to track submitted forms.

  7. Add the API call to your site. See Event for more details about implementing the API call.

  8. Click Save Event.

To check if your custom event is firing, verify this using Preview during the QA process or use the browser network console for a live running experiment.

Format to add a custom event

The following is a basic format for custom events in web experiments and campaigns. Depending on the event you want to track, you can add the code to your website or the experiment or campaign's shared code. Custom events can also be called from the Project JavaScript.

See Custom event tracking for an example of implementing a common custom event metric, which lets you track scroll depth.

Adding a custom event to shared code works only if the experiment or campaign is active on the page you want to track. If you want to track custom event metrics outside the scope of the experiment or campaign, 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 or campaign.

Here is an example of the code needed to trigger a custom event metric 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 you create a custom event, the API Name automatically populates the eventName. Use that corresponding eventName in your code to track the correct custom event.

In this code snippet, the eventName is tracked and associated with the appropriate visitor, experiment, campaign, or variation.

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 must enable jQuery in your project settings or include it in your code. See jQuery and the $variable.

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

If you have a question about custom events, contact your Customer Success Manager.