Relevant products:
  • Optimizely Classic
  • Optimizely X Web Experimentation
  • Optimizely X Web Personalization
  • Optimizely X Web Recommendations

This article will help you:
  • Track visitor data through the Optimizely JavaScript API so that you can target future experiments to those visitors, or segment their results on the Results Page
  • Create a custom dimension in Optimizely Classic
  • Place API calls to capture visitor dimension data, or to add/remove visitors from dimensions

This article will show you how to create custom dimensions in Optimizely Classic, which add visitor information through the API, and use them to filter your results. Want to see how to set up and use dimensions? Watch this short video.


You can add custom dimensions in Optimizely Classic and use them to segment results and create audiences in Optimizely X.

But if you're using Optimizely X, you can also create custom attributes. They're the same concept with a new name, and we've raised the limit from 10 dimensions to 100 attributes!

What are dimensions?

Visitors to your website are not all the same.  They differ by source, browser, and other important attributes. Optimizely stores data about every visitor to your page, like when they arrived, what device they use, and where they came from. Each type of information that Optimizely collects is called a dimension.

For example, you can create a dimension for "plan type" that includes the values basic, plus, and premium. Or a dimension for "favorite food" that includes the values pizza, hamburger buns, and caramel corn.

Use dimensions to segment your experiment results for more insight. This allows you to drill down into experiment results and discover how certain segments of visitors are behaving differently. This will allow you to create future experiments targeted to them.


Segmentation varies by plan type. If you don’t see the feature in your Optimizely account, or want to learn more about what’s available, please refer to our pricing matrix.

Viewing custom dimensions

You can view all dimensions that you have created by going to the Home page and clicking the Dimensions tab.

Creating custom dimensions

Customers with Enterprise plans can use Optimizely to report extra data about their visitors through custom dimensions. Dimensions will add visitors through the Optimizely JavaScript API. When you create a new custom dimension, it will apply to all your visitors going forward, but not retroactively.

Currently, Optimizely allows you to create up to 10 custom slots (depending on plan type) for filtering your results. These slots can include:

  • Audiences that you want to use to segment results
  • Custom Dimensions added through the API

You can use any combination of audiences or dimensions for filtering your results, but you have a limit of 10 slots that can be used.

To create a new custom dimension, go to the Home page and click the Overview > Dimensions Tab.

Clicking Dimensions shows you a list of all your custom dimensions. You can create new dimensions by clicking New Dimension.

Clicking New Dimension brings up the following dialog:


From this dialog, give your dimension a name and description that you'll use to identify the dimension in Optimizely and click Save. You can also optionally give the dimension a name for the API call, instead of the dimension ID. For more information, see the next section.

Adding visitors to a custom dimension

After you've created a custom dimension, the API call will automatically be generated and populated in the right-sidebar. In your site's code, you'll want to bind this API call to logic or an action that indicates that the visitor should be added to a dimension with a certain value.

The format of the call is:

window['optimizely'] = window['optimizely'] || [];
window['optimizely'].push(['setDimensionValue', 'dimensionId/Name', 'value']);

For example, if you wanted to set a dimension identifying visitors whose favorite food is hamburgers, you could set this value:

window['optimizely'] = window['optimizely'] || [];
window['optimizely'].push(['setDimensionValue', 'favorite food', 'Hamburger buns']);

If you don't specify a Dimension API name in the Create Visitor Dimension menu, then you'll use a dimension ID instead of an API name, like this:

window['optimizely'] = window['optimizely'] || [];
window['optimizely'].push(['setDimensionValue', 1791260297, 'Hamburger buns']);

Any Custom Dimension value can be set, such as 'Hamburger Buns', as long as it remains within the quotations.

Dimension values have a 20-character limit, and values over that length will be truncated. Dimension values are evaluated with a case-sensitive exact match, so the strings "Americans" and "americans" will not match. To delete an existing value, remove the value argument or supply null. Deleting a value will prevent Optimizely from counting future conversions toward that dimension value. It will not impact any past conversions, and visitors you remove will still count towards that value's unique visitor count if their visit was already logged.

For backwards compatibility, we still support adding visitors to segments via the API. These API calls will continue to work once your segments are migrated to audiences and dimensions.

Viewing results by dimension

On Optimizely's Results page, you can drill into results for a specific audience or dimension by choosing from the Segment: dropdown.  Click the specific audience or dimension for which you wish to see results, and the results will refresh with specific data.

If you click Add View to create a custom view (available for Enterprise plans), you can choose specific segments (Audiences or Dimensions) to segment by individual goals.

How are visitors counted toward dimensions?

A visitor comes to your site and will be counted as a visitor for all relevant dimensions. This means for one unique visitor you could see the same visitor show up in 2 or more dimensions. As an example, if a visitor used a mobile device and the Safari browser, then the visitor would show up in both dimensions. Similarly, if a visitor comes to your site several times, each from a different source, he will show up in each dimension.

In both instances, the visitor will still only count as one unique visitor to your unique count for the overall results.

If a visitor is included in multiple dimensions when a conversion event is triggered, the conversion will count toward any dimension in which he is active at the moment he converts. It will not count toward dimensions he has moved out of previously.

A visitor enters the experiment through and triggers a conversion event.

  • This visitor is attributed to the ‘campaign source type’ Visitor Count. This conversion is also attributed to the ‘campaign source type.’

  • The same visitor enters the experiment again through a Google search (without the utm_source parameter) and triggers a second conversion event.

  • This visitor is attributed to the ‘search source type’ Visitor Count. This conversion is also attributed to the ‘search source type.’

  • In your overall view of the experiment, this will still only count as one visitor and one conversion event since the visitor has the same unique user ID.

A visitor enters the experiment through Search but does not convert.

  • The visitor is attributed to the ‘search source type.’

  • The same visitor comes back to the experiment through a Referral and triggers a conversion event.

  • The visitor is attributed to the ‘referral source type’ and the conversion is also attributed to the referral source type’ since the visitor converted only during that particular visit.