Custom events

9 min

Optimizely Web Experimentation

Optimizely Performance Edge

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.

Warning

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 eventsSet up events and Set up revenue tracking in Optimizely Web ExperimentationSet 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

Go to Implementation > Events.

Click Create New Event.

Select Custom.

Enter a Name for the event

(Optional) Enter a description.

The API Name field automatically populates based on the N****ame, but uppercase characters are converted to lowercase, and non-alphanumeric characters are replaced with underscores.

Note

You can edit the automatically generated 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 alphanumeric characters and underscores. 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.

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

Click Save Event.

Note

To check if your custom event is firing, verify this using PreviewPreview during the QA process or use the browser network consolebrowser 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 JavaScriptProject JavaScript.

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

Note

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. 
window['optimizely'].push({
  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 $variablejQuery and the $variable.

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

Note

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

Add 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 when using the event on the Optimizely Experimentation Results pageOptimizely Experimentation Results page.

Currently, Optimizely Web Experimentation only supports event properties for custom events.

First, add the custom event properties in the UI (see the Create a custom event section). Next, in the pushpush call, add the required properties anywhere in your site code, Google Tag Manager, or through Optimizely (see the following example). You can send up to 15 event properties per specific event.

window['optimizely'] = window['optimizely'] || [];
window['optimizely'].push({
   type: "event",
   eventName: "conversion_event",
   properties: {
      Display: "true",
      Category: "jackets",
      Subcategory: "womens",
      Color: "purple",
      Location1: "top menu",
      Location2: "bottom CTA",
      Type: "sale"
    }
});

The Optimizely Web UI has five pre-defined properties (Category, Subcategory, Text, URL, and SKU) and ten custom properties. You must first create any custom properties in the UI before using or sending them Optimizely.

See Create a metricCreate a metric for information on filtering metrics by event properties.