Custom events in Optimizely Web Experimentation

  • Updated
This topic describes how to:
  • Create a custom event in Optimizely Web Experimentation to track behaviors that cannot 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 is not a pageview 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, there is no way to transmit the ID of your custom event to your experiment results in Optimizely.

You can use Optimizely Web Experimentation'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 want 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 implementing a common custom event goal, allowing you to track scroll depth.

For mobile and Optimizely Feature Experimentation experiments, we have a dedicated section covering custom events in our developer docs.

Adding a custom event to shared code works only 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. 
window['optimizely'].push({
  type: "event",
  eventName: "eventName"
});
When creating a custom event, the API name automatically populates 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 is 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 dashboard. 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 will 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 Web Experimentation.

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

Have a question about custom events? Contact your Customer Success Manager (CSM). 

Create a new custom event in Optimizely Web Experimentation

  1. Navigate to Implementation > Events.

    impl_events_x.png

  2. Click Create New Event.

    create_new_event_x.png

  3. Select Custom.

    create_custom_event_x.png

  4. Below 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.

    custom_event_settings_optimizely_x.png

  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.