Custom attributes: Capture visitor data through the API

  • Updated
  • Optimizely Web Experimentation
  • Optimizely Web Personalization

Visitors to your website differ by plan type, language, and other characteristics. Sometimes, segmenting the results of your experiments and personalization campaigns based on these characteristics is helpful.

For example, if you run a subscription media site and you experiment with value-messaging across the site, your results may show a "win," but you want to see how visitors on different plan types (basic, plus, and premium) responded. To see a refined view, create a custom attribute for visitors' plan types, then use it to look deeper into experiment results. You may 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 to examine experiment results and discover how differently certain segments of visitors are behaving. You can also use custom attribute values to build audiences. You can have up to 100 custom attributes.

The Experimentation terms of service prohibit you from sending any personally identifiable information (PII) such as names, social security numbers, email addresses, or any similar data to the Experimentation system through list attributes or other features.

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

  1. Go to AudiencesAttributes > and click 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.

    See also:

Create an audience

After creating a custom attribute, you can target experiments or campaigns to visitors with that attribute. See also Audiences.

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

  1. Go to Audiences > Saved > and click Create New Audience.
  2. Enter a name for your 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 also segmenting your Results page.