Skip to main content


Optimizely Knowledge Base

Bring your own visitor ID

UndefinedNameError: reference to undefined name 'undefined' (click for details)
    at (Set_Up_Optimizely/Bring_your_own_visitor_ID), /content/body/div[1]/pre, line 2, column 1



  • Optimizely Web Experimentation
  • Optimizely Performance Edge
  • Identify visitors using your own IDs, rather than using the IDs Optimizely automatically provides 

You can configure Optimizely to use visitor IDs that you provide, rather than using the cookie that Optimizely automatically generates (for more information on built-in visitor identification, see Cookies and localStorage in the Optimizely snippet.)

Why bring your own visitor ID?

Bringing your own visitor ID lets you:

  • Have more fine-grained control over your ID persistence strategy (for example, as part of your mitigation of Intelligent Tracking Prevention. See also  Intelligent Tracking Prevention and Optimizely).
  • Reduce cookie bloat in the browser by consolidating identifiers.
  • If you use both Optimizely Web and Optimizely Full Stack, you can supply a known ID  so you can use the same identifier across both Web and Full Stack.
  • Avoid complicated joins between Optimizely data exports and your own first-party data source.

To ensure granular control over visitor identifiers, you configure visitor IDs on a per-snippet basis. To enable using your own visitor ID, rather than using the default optimizelyEndUserId, for a given snippet:

1. In your project, navigate to Settings.  On the Implementation tab, select your snippet.

2. In the Visitor ID section, select the identifier type and identifier name.

snippet settings - visitor ID.png

You can select from the following options for identifier type:

Identifier Type Web Performance Edge Comment

You can select an existing cookie as a visitor ID. For example, if you have a unique Google Analytics cookie identifier, you can select 'Cookie' for the identifier type, with identifier name (cookie name), '_ga' .

Note: If you implement Performance Edge using the CDN proxy method, ensure you forward the selected cookie in requests to Optimizely's Edge Decider.

query parameter

You can select a query parameter as a visitor ID. For example, if you pass a visitor's unique identifier in a query parameter as part of a URL, as in:,you can select 'Query Parameter' as the identifier type dropdown, with identifier name (query parameter name), 'visitorId'


You can select a LocalStorage key as a visitor ID. For example, if you store a unique visitor value to the localStorage key ‘visitorId,’ you can select ‘Local Storage’ as the identifier type, with identifier name (localStorage key), 'visitorId'.


Javascript variable

You can select a Javascript window variable as a visitor ID. For example, if you store a unique visitor value to the variable window.visitorId, you can select 'Javascript Variable' for the identifier type, with identifier name (variable name), 'visitorId'.


When you save the snippet with a specified identifier type and name, subsequent activations of this snippet result in the following:

  • optimizelyEndUserId is NOT created on snippet activation.
  • Any data in localStorage under the previously set unique identifier is erased. For example, if a visitor was previously identified by an optimizelyEndUserId, the initialization of the snippet with a new identifier type and value erases any previously stored data. All events and bucketing use the new identifier.
  • The snippet stops executing if Optimizely can't locate the identifier you select in your snippet settings. This means that visitors aren't activated for any experiments nor do they trigger any Optimizely instrumented events.

Changing the visitor ID settings while experiments are still running may inflate visitor counts for those experiments and/or cause a visitor to see a different experience than they did previously. Optimizely does not stop or pause experiments while you configure this setting. We recommend pausing all experiments prior to changing visitor ID settings


What kind of ID should I choose? 

We recommend selecting the same ID you primarily use to conduct data analyses, typically that of your first-party analytics provider (for example, a Google Analytics ID or Segment ID). This simplifies your downstream data analyses by avoiding complicated joins with your own proprietary data set.

Note that regardless of which ID you choose, you must ensure that the ID is set and available for visitors before the Optimizely snippet runs. 


What happens if Optimizely cannot locate my specified ID? 

The snippet stops executing if Optimizely can't locate the identifier you selected in your snippet settings. This means that visitors aren't activated for any experiments nor do they trigger any Optimizely instrumented events.

To avoid this, we recommend ensuring that IDs are set and available prior to Optimizely running. For example, if you are relying on another cookie, we recommend that you create your cookies at the CDN level instead of via document.cookie to ensure availability. This approach is also recommended given Safari ITP, which limits the lifetime of all client-side generated cookies to 7 days.


Will you be deprecating optimizelyEndUserId soon?

We anticipate that most customers will move away from optimizelyEndUserId over time given the benefits to post-experiment analysis and the constraints of more restrictive browser changes; however, we don't plan on deprecating the optimizelyEndUserId in the immediate future. 


Can I use the default optimizelyEndUserId for some projects and another identifier type/name for others?

Yes. Visitor Id settings are snippet-specific. You can configure a different identifier type/name per snippet if needed. 


Does enabling this setting affect page performance when using Web or Performance Edge?

No, performance testing indicates that enabling use of an alternate ID in Web/performance Edge does not have any meaningful impact on page speed/performance. 

Migration FAQ

What happens to existing behavioral targeting information that I have pre-migration? 

When you configure a new ID, Optimizely creates a new visitor profile for each visitor. This means that you will not be able to access store behavioral/visitor profile data that was collected under the previously set optimizelyEndUserId. 


How does this migration affect DCP usage?

The Optimizely datasource is mapped to optimizelyEndUserId; we sync the optimizelyEndUserId to the IDs designated in each uploaded datasource. When you configure your snippet to look for another ID, you can expect the following, depending on your DCP customerId:

  • If DCP customerId is the same as the newly provided identifier and is available on each page load: No changes needed. Everything should operate as expected. The first-party user ID will be sent to the DCP backend on any given page load.
  • If the DCP customerId is different from the newly provided identifier, but is generally available on every page load: Everything should work as expected. The DCP customerId will be sent to the DCP backend on any given page load.
  • If the DCP customerId is different from the newly provided identifier, is not available on every page load and the customer thus relies on DCP's "aliasing" feature: It may be difficult to target previously-seen visitors after switching to new identifier (since the DCP customerId was aliased to an optimizelyEndUserId and not to the new ID). Talk to your Optimizely account contact for help. 

How will this affect any list attributes I am currently using?

This shouldn't be an issue unless your attributes are targeting extant optimizelyEndUserIds.

How will this affect my existing analytics integrations?
The migration should not affect existing analytics integrations. Current integrations attach experiment and variation information to events. These can continue to exist even with the replacement of the optimizelyEndUserID. In fact, this should simplify custom integration if you currently pass through the optimizelyEndUserId as a property/trait/attribute in your existing custom analytics integrations to help join Optimizely results export data to your internal data. With this feature, you should be able to remove that code, since a common key will already be available for those joins.

How will this affect my existing audience integrations?

There shouldn’t be any existing integration code that would be dependent on the existence of any particular visitor identity.

How will this affect data exports?

This migration should not affect exports, though once a customer turns on this feature, visitor Id values will reflect the customer passed user id and not the previous Optimizely-generated optimizelyEndUserId. Your data export during this transitional period may contain both references to the optimizelyEnduserId and the new identifier because of caching behavior

What happens if I migrate my snippet to use a different Id while experiments are still running? 

If migration happens while experiments are still running, return visitors who were previously identified with their randomly assigned optimizelyEndUserId will then be identified with the new designated identifier. This will lead to visitor count inflation in your results. We recommend that all experiments are paused prior to changing the visitor Id settings.