Cookie implementation options

  • Updated
  • Optimizely Web Experimentation
  • Optimizely Personalization

Optimizely Web Experimentation and Optimizely Personalization offer multiple ways to gate Optimizely on visitor consent. Use these options to comply with regulations such as the General Data Protection Regulation (GDPR). Whether consent is legally required is your decision and should be made in consultation with your legal team. Optimizely does not provide legal advice.

Choose an implementation option

The following decision tree shows how to choose an implementation option based on whether you can set the optimizelyEndUserId cookie before visitor consent and whether you can send event data to Optimizely before consent. Each terminal in the tree maps to one or more of the numbered options that follow.

Decision tree of cookie consent implementation paths where branches show choices based on whether you can set the optimizelyEndUserId cookie before consent and whether you can send data to Optimizely before consent.

Each outcome in the preceding diagram corresponds to one or more numbered options in the following sections:

  • Load Optimizely without consent gating – See Option 1.
  • Disable Optimizely until consent is given – See Option 2 or Option 3.
  • Use holdEvents or sendEvents – See Option 4.
  • Use a tag manager with a consent overlay – See Option 5.

Option 1: Load Optimizely without consent gating

You do not need to gate the Optimizely snippet on consent if any of the following apply:

  • You have classified the optimizelyEndUserId cookie as strictly necessary.
  • You have obtained consent through another mechanism.
  • Your data protection requirements do not apply.

To implement this option:

  1. Place the Optimizely snippet at the top of <head> so it executes as early as possible.
  2. (Optional) Add preload or preconnect tags to reduce snippet download time.

This implementation has two visible effects:

  • Experiments load for all visitors with no flicker.
  • All events are sent to Optimizely for all visitors.

This is the simplest implementation. If you later need Optimizely's data collection to align with other consent-gated analytics tools so that results compare cleanly across systems, see Option 4: Hold events until consent.

Option 2: Disable Optimizely by default

Use this option when you cannot set any Optimizely cookie before visitor consent, for example, when your data protection requirements classify the optimizelyEndUserId cookie as non-essential. Disable Optimizely from running automatically by calling the optOut API or executing Optimizely's disable API call.

Use the optOut API

Use the optOut API to opt a visitor out of Optimizely tracking by disabling Optimizely Web Experimentation or Optimizely Personalization. You must execute the API call before the Optimizely snippet runs to stop Optimizely Experimentation or Optimizely Personalization from executing on the first page load.

  1. Add the following code above the Optimizely snippet to set the optimizelyOptOut cookie or use the optOut API. A common implementation for the opt-out API option is to set the cookie optimizelyOptOut through a consent manager.

    function getCookie(name){
   var match = document.cookie.match(name + '=([^;]*)');
   return match ? match[1] : undefined;
}
if (!getCookie('consent')) {
   window["optimizely"].push({
      "type": "optOut",
      "isOptOut": true
   });
}
  2. Load the Optimizely snippet as normal.
    • Optimizely immediately checks for the optimizelyOptOut cookie. If the cookie:
      • optimizelyOptOut = true – Optimizely does not execute further JavaScript.
      • optimizelyOptOut = false – Optimizely executes the rest of the JavaScript and deletes the optimizelyOptOut cookie.
      • optimizelyOptOut does not exist – Optimizely executes the rest of the JavaScript.
  3. Implement code so that when a visitor consents, there is something your optOut logic can read from (cookie, local storage value, JavaScript variable, and so on) to know whether the visitor consented and execute the optOut API accordingly.
  4. Use JavaScript to toggle the cookie value from true to false, or delete the cookie, when a visitor gives explicit consent.

Visitors see the control variation (the original content) until they consent.

For Optimizely Experimentation or Optimizely Personalization to start working, when explicit consent is given, you must:

  • Reload the page programmatically.
  • Wait until the visitor reloads the page.
  • Wait until the visitor goes to another page.

This option does not let you test on the first page viewed or the landing page when the visitor has not given explicit consent.

Use the disable API call

Use the disable API call before the Optimizely snippet runs. The API stops Optimizely Web Experimentation or Optimizely Personalization from executing and tracking the visitor on the first page load.

Add the following code before the Optimizely snippet or in the project's Project JavaScript. The code checks whether the visitor has consented: 

function getCookie(name){
  var match = document.cookie.match(name + '=([^;]*)');
  return match ? match [1] : undefined;
}

if (!getCookie('consent')) {
  window.optimizely = window.optimizely || [];
  window.optimizely.push({
    "type": "disable"
  });
}

The code must execute before the Optimizely Experimentation snippet or inside the project's Project JavaScript so that the disable API call does not execute if the visitor consents. If the visitor has not consented, execute the disable API call. Implement code so that when a visitor consents, there is something your disable logic can read from (for example, cookie, local storage value, JavaScript variable, and so on) to know that the visitor consented.

Visitors see the control variation (the original content) until they consent. For Optimizely Experimentation or Optimizely Personalization to start working, when explicit consent is given, you must:

  • Reload the page programmatically.
  • Wait until the visitor reloads the page.
  • Wait until the visitor goes to another page.

This option does not let you test on the first page viewed or the landing page when the visitor has not given explicit consent.

If the visitor has not given explicit consent, you can disable Optimizely and show a full page covering the original page. On this page, consent options are shown to the visitor for analytical tools that require consent, including Optimizely.

When the visitor consents, the page reloads and the consent overlay does not display again. Authorized tools start working normally after the page reloads. 

For an example, see Option 5: Use a tag manager.

Option 3: Do not automatically execute the Optimizely snippet

Choose this option when you want Optimizely Support to modify your snippet directly rather than wrap it in custom consent logic. Contact Support to change the snippet so Optimizely Web Experimentation or Optimizely Personalization does not run until you call the activate API.

After Support makes the change, implement logic that only lets the activate API call execute:

  • When the visitor has already consented upon page load.
  • (Optional) When the visitor consents.

Example activate API call:

window.optimizely = window.optimizely || []; 
window.optimizely.push({
   "type": "activate" 
});
Calling the activate API when the visitor consents can cause flickering if the visitor is in a variation that changes a visible element.

Option 4: Hold events until consent

Use the holdEvents and sendEvents APIs to control when the Optimizely snippet sends events to the logging endpoint. Place the holdEvents call above the Optimizely snippet or in the project's Project JavaScript so it runs before the snippet loads. The snippet then does the following:

  1. Bucket a visitor into the experiment (so they see the variation changes).
  2. Set an optimizelyEndUserId cookie on the visitor (if the project is not using Bring your own visitor ID (BYOID)).
  3. Hold all events from being sent to Optimizely until the sendEvents API is called, which can be coded to execute when explicit consent is granted. If explicit consent is not granted, those events are never sent.
    • Optimizely still collects events in the visitor's browser local storage before consent, but does not send them until consent is granted. Events are sent after explicit consent is granted, and the sendEvents API is called (including those with timestamps before consent is granted).
    • Queued events from holdEvents accumulate in local storage. Implement logic to clear Optimizely's local storage object at the start of each session, or sooner if the visitor has not consented yet.

The benefit of this option is that visitors see the variation changes immediately without any tracking events being sent to Optimizely before consent. The downside is that Optimizely still buckets visitors and writes the optimizelyEndUserId cookie before consent. In jurisdictions with strict pre-consent cookie requirements, this option might not satisfy compliance review.

Option 5: Use a tag manager

Use a tag manager or a consent manager on your site. Configure conditional logic in the tag or consent manager to load the Optimizely snippet only if a visitor consents.

  • Visitors see the control variation (the original content) until they consent.
  • For Optimizely Experimentation or Optimizely Personalization to start working, when a visitor gives explicit consent, you must do the following:
    • Reload the page programmatically.
    • Wait until the visitor reloads the page.
    • Wait until the visitor goes to another page.
  • This solution does not let you test on the first page viewed or the landing page when a visitor has not given consent.

If a visitor has not consented, do not inject the Optimizely snippet. Instead, display a full-page overlay covering the original page. The page shows consent options for analytical tools that require consent, including Optimizely. Authorized tools start working normally after the page reloads. Because the overlay hides the original variation from the visitor, you can experiment on the first page they view.

Screenshot of a full-page consent overlay where the visitor selects which analytical tools, including Optimizely, can run on the site.