Bring your own visitor ID (BYOID)

  • Updated
  • Optimizely Web Experimentation
  • Optimizely Personalization
  • Optimizely Performance Edge

You can configure Optimizely Web Experimentation, Optimizely Performance Edge, and Optimizely Personalization to use your own visitor IDs rather than using the cookie that Optimizely automatically generates for projects. For information on the built-in visitor identification, see Cookies and localStorage in the Optimizely snippet

Bringing your own visitor ID (BYOID) lets you:

  • Have more control over your ID persistence strategy, such as for mitigation of intelligent tracking prevention.
  • Reduce cookie bloat in the browser by consolidating identifiers.
  • Supply a known ID if you use both Optimizely Web Experimentation and Optimizely Feature Experimentation to use the same identifier.
  • Avoid complicated joins between Optimizely data exports and your own first-party data source.

Configure visitor IDs per snippet

For more control, you can configure visitor IDs on a per-snippet basis. Follow these steps to enable using your own visitor ID instead of the default optimizelyEndUserId for a given snippet.

1. Go to your project >  Settings Implementation and select your snippet.


2. Set the Identifier Type from the drop-down list and the Identifier Name.



Identifier types

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

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


Page 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 such as you can select Page Query Parameter and name it

Local Storage – Available for Optimizely Web Experimentation and Optimizely Personalization only. 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 choose Local Storage and name it visitorId.local-storage.png

JavaScript Variable – Available for Optimizely Web Experimentation and Optimizely Personalization only. 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 and name it visitorId.javascript-variable.png

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 an optimizelyEndUserId once identified a visitor, the initialization of the snippet with a new identifier type and value erases any previously stored data. All events and bucketing use the unique identifier.
  • The snippet stops executing if Optimizely cannot locate the identifier you select in your snippet settings. This means that visitors are not activated for any experiments and campaigns or trigger any Optimizely instrumented events.

Optimizely does not stop or pause experiments or campaigns while you are configuring this setting. Changing the visitor ID settings while experiments or campaigns are still running may inflate visitor counts and/or cause a visitor to see a different experience than they did previously. Pause all experiments or campaigns before changing visitor ID settings.


What kind of ID should I choose? 

Optimizely recommends selecting a static ID. This might be the same ID you use to conduct data analysis, usually that of your first-party analytics provider like a Google Analytics ID or Segment ID. This simplifies your downstream data analysis by avoiding complicated joins with your own proprietary data set. Changing what you use as the ID often may cause strange behavior in your experiment data. 

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 cannot locate the identifier you selected in your snippet settings. This means visitors are not activated for any experiments and campaigns or trigger any Optimizely-instrumented events.

To avoid this, set IDs before Optimizely runs. For example, if you rely on another cookie, you should create your cookies at the CDN level instead of via document cookie to ensure availability. This approach also works for Safari ITP, which limits the lifetime of all client-side generated cookies to 7 days.

Is BYOID bucketing deterministic?

Yes. The same variant is guaranteed for the same user ID (in the same project) across devices/browsers. For example, a user visiting your site on desktop is assigned ID=123 and bucketed into variation A. If that same user visits your site on mobile, BYOID also sets ID=123 for that user. This user still sees variation A on mobile, just as on desktop.

Will you be deprecating optimizelyEndUserId?

Optimizely anticipates that most customers will move away from optimizelyEndUserId over time given the benefits of post-experiment analysis and the constraints of more restrictive browser changes; however, there is no plan to deprecate 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. 

What if I want to change my IDs often?

Select an ID for BYOID that is somewhat static and unchanging. Changing the ID often can cause errors or other discrepancies in your data. 

Does enabling this setting affect page performance?

No, performance testing indicates that enabling an alternate ID does not significantly impact 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 visitor profile for each visitor. This means you cannot access store behavioral/visitor profile data collected under the previously set optimizelyEndUserId.

How does this migration affect DCP usage?

The Optimizely data source is mapped to optimizelyEndUserId. Optimizely syncs the optimizelyEndUserId to the IDs designated in each uploaded data source. 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 are needed. Everything should operate as expected. The first-party user ID is sent to the DCP backend on any given page load.
  • If the DCP customerId differs from the newly provided identifier but is generally available on every page load – Everything should work as expected. The DCP customerId is sent to the DCP backend on any page load.
  • If the DCP customerId differs from the newly provided identifier and is not available on every page load  This relies on DCP's "aliasing" feature. It may be difficult to target previously-seen visitors after switching to a new identifier, since the DCP customerId was aliased to an optimizelyEndUserId and not to the new ID. Talk to your Optimizely Customer Success Manager for help. 

Does this affect any list attributes I am currently using?

List attributes should not be an issue unless your attributes are targeting extant optimizelyEndUserIds.

Does 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. 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. You should remove that code with this feature since a common key will already be available for those joins.

Does this affect my existing audience integrations?

There should not be any existing integration code that would be dependent on the existence of any particular visitor identity.

Does this affect data exports?

This migration should not affect exports. When you turn on this feature, visitor ID values reflect the customer-passed user ID and not the previous optimizelyEndUserId. Your data export during this transitional period may contain references to the optimizelyEndUserId and the new identifier because of caching behavior.

What happens if I migrate my snippet to a different Id while experiments or campaigns run? 

If migration happens while experiments or campaigns are still running, returning visitors who were previously identified with their randomly assigned optimizelyEndUserId are identified with the newly designated identifier. This leads to visitor count inflation in your results. You should pause all experiments and campaigns before changing the visitor ID settings.