Cookies and consent management (Browser SDK)

This guide covers functional and technical information on how Amplitude Browser SDK 2 works with cookies, local storage, opt-in/opt-out options, and consent management (including CNIL regulations for France).

Amplitude cookies

A "cookie" is a piece of data from a website that browsers store on users' devices. Websites retrieve cookies later to access stored data for functional or technical purposes. After initialization, Amplitude Browser SDK 2 creates cookies that begin with specific prefixes and include the first 10 digits of your project API key.

For example, if you initialize the SDK with:

import * as amplitude from "@amplitude/analytics-browser";
amplitude.init("a2dbce0e18dfe5f8e...");

Amplitude Browser SDK 2 creates cookies with the following format:

• User session cookies: AMP_ with the first 10 characters of your project's API Key appended (for example, AMP_a2dbce0e18)
• Marketing campaign cookies: AMP_MKTG_ with the first 10 characters of your project's API Key appended (for example, AMP_MKTG_a2dbce0e18)

Test cookies

During initialization, the SDK may create temporary test cookies to verify cookie functionality:

• AMP_TEST_ followed by a timestamp: Tests whether cookies work
• AMP_TLDTEST_ followed by a timestamp: Finds the appropriate subdomain for cookie storage

The SDK automatically removes these test cookies after testing completes. If they persist, you can safely delete them manually.

Cookie data

The SDK stores different types of information in cookies:

User session cookies (AMP_*)

The user session cookie contains metadata necessary for the SDK to function correctly:

• deviceId: A randomly generated string that persists across sessions
• userId: When users log in, if your app sends this value to Amplitude, the SDK stores it in the cookie. Set this to uniquely identify users. Amplitude encodes this value as Base64 before storing it.
• sessionId: A randomly generated string for each session
• lastEventTime: Time of the last event, used to decide when to expire and create a new session ID
• lastEventId: An incrementing sequence of identifiers used to distinguish events

Marketing campaign cookies (AMP_MKTG_*)

The marketing campaign cookie stores attribution data including:

• UTM parameters (utm_source, utm_medium, utm_campaign, utm_term, utm_content)
• Referrer information (referrer, referring_domain)
• Click IDs (gclid, fbclid, dclid, gbraid, wbraid, ko_click_id, msclkid, ttclid, twclid, li_fat_id, rdt_cid)

Cookie size

Cookie size can vary from approximately 60 bytes to 120 bytes per cookie. With both user session and marketing campaign cookies, expect around 240 bytes total for Amplitude cookies per project API key.

Expiration time

By default, Amplitude cookies expire after 365 days (1 year). You can customize this with the cookieOptions.expiration configuration parameter:

amplitude.init("API_KEY", {
  cookieOptions: {
    expiration: 30, // Set cookies to expire after 30 days
  },
});

Remove Amplitude cookies

To programmatically remove Amplitude cookies, run the following snippet.

const API_KEY = "1234567890abcdefghijklmnopqrstuv"; // Replace it with your API KEY
const cookieName = `AMP_${API_KEY.substring(0, 10)}`;
const cookieNameMktg = `AMP_MKTG_${API_KEY.substring(0, 10)}`;
const cookies = document.cookie.split(";");

cookies.forEach((cookie) => {
  const [name] = cookie.trim().split("=");

  if (name === cookieName || name === cookieNameMktg) {
    document.cookie = `${name}=; Max-Age=0; path=/; SameSite=Lax`;
  }
});

To anonymize users after they log out.

amplitude.reset();

reset does the following:

1. Sets userId to undefined
2. Sets deviceId to a new UUID value

With an undefined userId and a new deviceId, the user appears to Amplitude as a new user.

Disable cookies using localStorage

Set the identityStorage option to configure the SDK to use localStorage rather than cookies.

amplitude.init("API_KEY", {
  identityStorage: "localStorage",
});

Data stored in local storage

When using localStorage, the SDK stores the same user session information that would normally be in cookies, plus:

• Unsent events: Events that haven't been successfully uploaded to Amplitude
• Failed events: Events that failed to send and are queued for retry

The SDK stores data in localStorage with keys that include your project API key:

• AMP_unsent_[API_KEY]: Stores unsent events

Disable cookies and local storage (opt-out storage)

You can disable all persistent storage by setting identityStorage to none:

amplitude.init("API_KEY", {
  identityStorage: "none",
});

When you disable all storage, Amplitude creates a new device_id for that user every time they visit your site because the SDK can't find an existing ID. If the user logs in or provides other identifying information, Amplitude's identity resolution system ties the various device_id values together with that user ID.

Managing cookie consent

Certain jurisdictions require that users consent to non-essential cookies before any data can be collected. You are ultimately responsible for ensuring that you get any necessary consents and make any necessary disclosures for the personal data you collect and send to Amplitude. You're also responsible for determining how you classify the Amplitude cookies in your cookie policy based on your specific use case and the jurisdictions in which you use them.

If you use the Amplitude SDK in one of these jurisdictions, don't initialize the SDK until the user has consented to your use of cookies. This is because Amplitude functions (for example, cookie storage, local storage, and tracking events) are enabled or disabled upon SDK initialization.

Deferred initialization approach

For consent management, you can track events before cookie consent and initialize the SDK later:

// Track events
amplitude.track("Button Clicked");

// Later, when user provides consent,
// initialize the SDK
amplitude.init("API_KEY");

Configuration options related to storage

This table gives a brief overview of each option related to storage in Browser SDK 2:

Abstraction layer for storage

You can find the abstraction layer for storage and available options as well as the metadata that's stored in Amplitude's GitHub repository for the TypeScript SDK:

• Browser SDK 2 source code
• Configuration types
• Cookie storage implementation

Frequently asked questions

CNIL France - Frequently asked questions