Custom Attributes: Capture visitor data through the API

  • Updated
This topic describes how to:
  • Capture specific attributes of visitors, like plan type
  • Target experiments or Optimizely Web Personalization campaigns to those attributes with audience conditions
  • Segment your Results page by that attribute to view how certain visitors behave differently

Visitors to your website are not all the same. They differ by plan type, language, and other characteristics. Sometimes, it's helpful to be able to segment the results of your experiments and Personalization campaigns based on these characteristics.

For example, imagine that you run a subscription media site and you're experimenting with value messaging across the site. Your results show a "win," but you'd like to see how visitors on different plan types (basic, plus, and premium) responded. For a more granular view, you'd create a custom attribute for visitors' plan types, then use it to dive deeper into experiment results. Maybe you'd find that your change performs well for basic and plus plans, but premium users reacted negatively. This insight would influence your next round of experiments and decision-making. 

Use custom attributes to segment your experiment results for more insight. This lets you drill down into experiment results and discover how certain segments of visitors are behaving differently. You can also use custom attribute values to build audiences.

In Optimizely Web Experimentation, you can have up to 100 custom attributes.

Use the Optimizely Web Experimentation JavaScript API to set the custom value of an attribute for a visitor. For example:

// This line is required if the custom event is triggered before Optimizely is 
defined on the page or if triggered in Project JavaScript
 window.optimizely = window.optimizely || [];
  "type": "user",
  "attributes": {
    "123": "custom attribute value",
    "customAttributeApiName": "this is also a custom attribute value"

Create a custom attribute

To create a custom attribute, scroll down for step-by-step instructions:


  1. Go to the Audiences dashboard. Click Attributes > Create New Attribute

  2. Name the attribute and enter the API Name. The API Name must be unique.

  3. Click Save Attribute.

Now you can make an API call for custom attributes. Use the Optimizely Web Experimentation JavaScript API to set the value of a custom attribute for each visitor.

Create an audience

After you create a custom attribute, you can target experiments or campaigns to visitors who have that attribute.

To use attributes to define an audience, follow the instructions.

Screen Recording 2019-10-10 at 12.48 pm.gif

  1. Go to the Audiences dashboard and click Create New Audience.

  2. Enter a name for your new audience.

  3. Click Custom Attributes and select the attribute you want to add. Drag and drop the attribute under Audience Conditions to define your audience conditions.

  4. Click Save Audience.

The custom attribute creates an audience. Use the audience to show experiments or campaigns to visitors who have that attribute.

Segment by custom attributes

You can use custom attributes to filter your entire Results page or the results for an individual metric; this is called segmenting. Segmenting results helps you get more out of your data by generating valuable insights about your visitors. See segmenting your Results page.