Manage user IDs in browser-based SDKs

Optimizely Feature Experimentation requires a consistent and unique user ID to assign users to variations and ensure they receive a consistent experience across sessions and devices.

For browser-based SDKs like JavaScript (Browser) and React, you are responsible for generating and persisting the user ID. The following sections describe how to implement that logic using cookies, local storage, and CDN tools.

📘

Note

These strategies apply only to browser-based SDKs. For server-side or mobile SDKs such as Swift, Android, or Python, see Handle user IDs and platform-specific documentation.

Choose a storage strategy

Store user IDs in cookies

Cookies are the most common way to persist user IDs across sessions.

• Persistent cookies – Remain on the browser until they expire. Use these to preserve the user ID across visits.
• Session cookies – Cleared when the browser session ends. Use when long-term tracking is not needed or consent has not been given yet.

  📘

  Note

  Using session cookies may increase your monthly active users (MAUs) consumption. See Monitor MAUs.
  Note that this can increase your MAU consumption

When using cookies, make sure the cookie is scoped correctly across domains and uses secure attributes.

Use local storage for same-origin persistence

localStorage lets you persist a user ID across sessions, but only for the same domain.

Use localStorage when

• your application is limited to a single domain.
• you do not need to share the user ID across subdomains.

Avoid it if you require cross-subdomain persistence or need to read the ID server-side.

Manage user IDs at the edge with a CDN

You can also assign or inject user IDs using edge logic provided by your CDN.

• Edge worker – Run a function on the edge that will add a user ID cookie to the HTTP response headers.
• Edge-side includes (ESI) – Serve a JavaScript snippet that generates and persists a user ID.

Considerations

• Optimize edge logic for performance.
• Make sure cookie management at the edge complies with your organization’s privacy and security policies.
• Check your CDN’s capabilities for header or cookie manipulation.

Best practices

• Be transparent about how you use userIds in experiments.
• Use a cookie banner or other consent mechanism to capture and verify consent.
• Always check for consent before storing persistent identifiers.

Implement user ID logic with code samples

With NPM packages (js-cookie and uuid)

import {v4} from 'uuid';
import cookies from 'js-cookie';

function getOptimizelyId() {
  const visitorId = cookies.get('visitorId') || v4();
  cookies.set('visitorId', visitorId, {expires: 365, domain: '.example.com'});
  return visitorId;
}

Without NPM packages (with custom cookie functions)

function getOptimizelyId() {
  const visitorId = getCookie('visitorID') || uuidv4();
  setCookie('visitorId', visitorId, 365, '.example.com');
  return visitorId;
}

function getCookie(cname) {
  let name = cname + "=";
  let decodedCookie = decodeURIComponent(document.cookie);
  let ca = decodedCookie.split(';');
  for (let i = 0; i < ca.length; i++) {
    let c = ca[i].trim();
    if (c.indexOf(name) == 0) {
      return c.substring(name.length, c.length);
    }
  }
  return "";
}

function setCookie(cname, cvalue, exdays, domain) { 
  const d = new Date();
  d.setTime(d.getTime() + (exdays * 24 * 60 * 60 * 1000));
  let expires = "expires=" + d.toUTCString();
  document.cookie = `${cname}=${cvalue}; ${expires}; domain=${domain}; path=/`;
}

function uuidv4() {
	return "10000000-1000-4000-8000-100000000000".replace(/[018]/g, c => 
  	(c ^ crypto.getRandomValues(new Uint8Array(1))[0] & 15 >> c / 4).toString(16)
  );
}

With local storage

import { v4 } from "uuid";

function getOptimizelyId() {
  const visitorId = localStorage.getItem('visitorId') || v4();
  localStorage.setItem('visitorId', visitorId);
  return visitorId;
}

Best practices

• Name cookies clearly – Avoid using "optimizely" in the cookie name to reduce ad blocker interference.
• Use secure cookie attributes – Set Secure and SameSite attributes where appropriate.
• Centralize ID logic – Create a single utility or service that handles userId generation and storage.
• Check before generating – Avoid overwriting an existing userId.
• Refresh expiration – Extend the cookie expiration date for returning users to keep their ID active.
• Comply with regulations – Ensure your storage logic integrates with your consent mechanism and privacy policy.

By following these guidelines, you can effectively manage user identifiers in browser-based Optimizely Feature Experimentation SDKs, ensuring accurate bucketing and consistent user experiences across sessions.