Manage user IDs in browser-based SDKs

8 min

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 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 necessary or consent has not been given yet.

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

When using cookies, ensure they are scoped correctly across domains and use 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

Use edge logic provided by your CDN to assign or inject user IDs.

Edge worker – Runs a function on the edge that will add a user ID cookie to the HTTP response headers.

Edge-side includes (ESI) – Serves a JavaScript snippet that generates and persists a user ID.

Considerations

Optimize edge logic for performance.

Ensure cookie management at the edge complies with your organization’s privacy and security policies.

Check your CDN’s capabilities for header or cookie manipulation.

Privacy considerations

Be transparent about how you use userIds in experiments.

Use a cookie banner or other consent mechanism to capture and verify consent.

Check for consent before storing persistent identifiers.

Implement user ID logic with code samples

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;
}

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

Provide a clear name – 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.