Cookies and consent management

This guide covers functional and technical information on how Amplitude 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 stored on a user's web browser. Websites retrieve cookies later, to access data stored for functional or technical purposes. After initialization, the Amplitude SDK creates a cookie that begins with the prefix AMP_ and ends with this first 10 digits of your project API key. You can customize this prefix with the constant COOKIE_PREFIX in the SDK's constants.js file. The SDK defines the cookie's value in amplitude-client.js.

For example, if you use the default value for the prefix with the following:

1amplitude.getInstance().init("a2dbce0e18dfe5f8e...")

The Amplitude Browser 2.0 SDK creates a cookie with the format AMP_ with the first 10 characters of your project's API Key appended.

In previous versions of the SDK, you could customize the key for this cookie upon initialization, using the option cookieName. This no longer works, but if you use older SDK versions, the cookie name may differ from the indicated standard name

If another cookie appears with the key amplitude_cookie_test followed by a suffix of a random base64 string, the cookie is used to test whether the user has cookies enabled, and the SDK should remove it when the test completes. For more information, see the detail in the SDK's base-cookie.js file.

Sometimes, the SDK may not remove the amplitude_test_cookie cookie. In this case, the cookie remains in the cookie list, but isn't used. You can customize the key of this cookie with the COOKIE_TEST_PREFEX constant in the SDK's constants.js file.

The cookie is used to keep track of certain metadata for the SDK:

• deviceId: A randomly generated string
• userId: Upon user log-in, if your app sends this value to Amplitude, it's stored in the cookie. You should set this to uniquely identify users. Amplitude encodes this value as Base64 before storing it.
• optOut: A flag to opt this device out of Amplitude tracking. If this flag is set, Amplitude stores no extra information about the user.
• 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
• eventId: An incrementing sequence of identifiers used to distinguish events
• identifyId: An incrementing sequence of identifiers used to distinguish identify calls
• sequenceNumber: A sequence number used to order events and identifies and properly sequence them

When the Amplitude JavaScript SDK loads, it checks the cookie to see if there is an Amplitude device_id (if user is a returning user and generated a device_idin a previous visit). If so, it uses that value. If not (either because it's a new user or the user recently cleared cookies), the SDK randomly generates a device_id, and also saves it to the cookie.

Cookie size

The cookie size can vary, going from a minimum of 60 bytes to some 120 bytes. Knowing that Amplitude can store 2 of them (amp_* and amp_*.organization.domain), you can assume a 120 bytes as a safe average size for Amplitude cookies per project API key.

Expiration time

The Amplitude SDK has a cookieExpiration option to allows you to set the number of days until a cookie expires. Before SDK version 7.0, the default value was 10 years. After SDK version 7.0, cookieExperiation defaults to one year. Most browsers limit the lifetime of cookies set using document.cookie from one to seven days.

Remove Amplitude cookies

To programmatically remove the Amplitude cookie, use the method JavaScript SDK's clearStorage() method. This method clears all cookies, and deletes any metadata stored on them.

Deprecated cookies

The following cookie keys are deprecated in the latest SDK versions:

• amplitude_id_<API_KEY>.your_org_domain: In previous versions of the Amplitude JavaScript SDK, the cookie key was set by default to amplitude_id; this may appear in projects that use an SDK version prior to 6.0.0. In that case, the cookie is set under the key amplitude_id_<PROJECT_API_KEY>.organization.domain.

  

• amplitude_test.your_org_domain: The Amplitude SDK uses this cookie to test more thoroughly if cookies are available. By default, the key is used as amplitude_cookie_test, but as mentioned above, the SDK should remove this cookie after the test.

Disable cookies using LocalStorage (opt-out cookies)

The cookie contains data necessary for Amplitude to function correctly. It saves deviceId, sessionId, and the last event's timestamp. You can set disableCookies to true in the SDK's options.js file to store this information in a user's local storage.

Data stored in local storage

Besides the information that managed in the cookie, Amplitude uses this storage to store:

• Online events: Controlled by the option saveEvents in the SDK's options.js (defaults to true), Amplitude stores every event sent it receives, and then removes it upon successful upload. If set to false, events may be lost if the user navigates quickly to another page before the events are uploaded.
• Offline events: The option savedMaxCount in the SDK's options.js manages the number of offline events (defaults to 1000). If Amplitude logs more than 1000 events when offline, the oldest events are removed from the storage.
  Failed events: Any failed event is stored here to retry.

This data is stored in the next keys:

• amplitude_unsent_<PROJECT_API_KEY>: Stores unsent events. You can customize its name with the unsentIdentifyKey option in the SDK's options.js.
• amplitude_unsent_identify_<PROJECT_API_KEY>: Stores unsent identify calls. You can customize its name with theunsentKey option in the SDK's options.js.

The rest of auto captured properties are unaffected by the fact of using LocalStorage instead of cookie you can refer to this article for full detail.

This action disables cookie storage, but Amplitude stores this same data in the user’s browser Local Storage. It's not a valid option for a user that wants to fully opt out.

Disable cookies and local storage / session storage (opt-out storage)

When you disable cookies, and the user disables local storage and session storage, Amplitude creates a new device_id for that user every time the visit your site because it 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. The user must log in on each visit to enable Amplitude to merge identifiers.

Disabling tracking (opt out tracking)

Users may wish not only to opt out of cookies, which prevents Amplitude from storing any data in the cookie, but also opt out of tracking completely, which means that Amplitude does not store events or records of their browsing history. The Amplitude SDK provides an optOut as a way to fulfill this request. To programmatically opt out of tracking the SDK provides the method amplitude.setOptOut(true).

“Do not track” setting on browsers (DNT flag)

Some browsers have a setting “Do not track” that's intended to block all tracking. Amplitude doesn't adhere to this setting. The DNT standard isn’t widely supported and it isn’t clear what it’s meant to disable. If you want to consider that setting, write your own code to test for the DNT flag and then set the optOut option in the SDK.

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 the Amplitude functions (for example, cookie storage, local storage, and tracking events) are enabled or disabled upon SDK initialization.

To allow for this, the JavaScript SDK offers an option called deferInitialization (defaults to null). If set to true, it disables the core function of the SDK, including saving a cookie (or anything to the local storage) and all tracking, until explicitly enabled. The SDK instance loads without storage and tracking until you call amplitude.getInstance().enableTracking().

When you call amplitude.getInstance().enableTracking(), the option deferInitialization is set to false and Amplitude creates the cookie with the options values you configured, as in the code in client.js:

 1/**
 2* Enable tracking via logging events and dropping a cookie
 3* Intended to be used with the deferInitialization configuration flag
 4* This will drop a cookie and reset initialization deferred
 5* @public
 6*/
 7AmplitudeClient.prototype.enableTracking = function enableTracking() {
 8   // This will call init (which drops the cookie) and will run any pending tasks
 9   this._initializationDeferred = false;
10   f(this);
11   this.runQueuedFunctions();
12 };
13 
14/**
15* Saves deviceId, userId, event meta data to amplitude cookie
16* @private
17*/
18var _saveCookieData = function _saveCookieData(scope) {
19   const cookieData = {
20     deviceId: scope.options.deviceId,
21     userId: scope.options.userId,
22     optOut: scope.options.optOut,
23     sessionId: scope._sessionId,
24     lastEventTime: scope._lastEventTime,
25     eventId: scope._eventId,
26     identifyId: scope._identifyId,
27     sequenceNumber: scope._sequenceNumber,
28   };
29    if (scope._useOldCookie) {
30     scope.cookieStorage.set(scope.options.cookieName + scope._storageSuffix, cookieData);
31   } else {
32     scope._metadataStorage.save(cookieData);
33   }
34 };

This doesn't affect users who have an Amplitude cookie, as shown in the code from amplitude-client.js: at some point, the user provided consent, which is all Amplitude needed to create the cookie legitimately. To opt that user out of tracking, you must remove any amplitude cookies that were already set for that user.

The presence of an Amplitude Analytics cookie is what determines whether Amplitude tracks a user's events. For users that have one, consider the following:

1. If you manually define cookieExpiration to be a short lifespan, you may need to run amplitude.getInstance().enableTracking() when the Amplitude Analytics cookie expires, or when the user logs in.

2. If the user removes all cookies, they should see the consent banner again the next time they visit your app. Since there won’t be any Amplitude Analytics cookie yet set, the flow will go as described earlier, and the initialization of storage and tracking options will wait if using deferInitialization = true.

3. If the user consented to the Amplitude Analytics cookie at some point in the past, and that consent has expired for any reason (website cookie deletion, consent tracking expired), Amplitude will prompt the user for consent again. If the user declines, the Amplitude Analytics cookie must explicitly be removed. Otherwise, it will continue to collect the user’s information, this time against their will.

Getting the SDK initialization options per project

From any site that uses Amplitude JavaScript SDK, you can know which initialization options are set. Run the next command from the JavaScript console on the browser you use to access the site:

1amplitude.getInstance().options

Options are displayed alongside their values. For example, on amplitude.com you may see the following:

API options in Amplitude Event Explorer Chrome extension

If you use the Amplitude Event Explorer Chrome extension, you can access the initialization options values in the “API Options” tab by first selecting the project you're interested in:

If the Amplitude object instance isn't stored in the window object, it won’t be available to extract this information, neither from the console nor from the Chrome extension; this usually happens when using Node.js instead of the JavaScript SDK.

The error in the console appears like this:

Storage options explained

This table gives a brief overview of each option related to storage.

Abstraction layer for storage

The abstraction layer for storage and available options as well as the metadata that's stored can be found in Amplitude's GitHub:

• constants.js
• options.js
• cookiestorage.js
• cookie.js
• base-cookie.js
• localstorage.js
• metadata-storage.js

As indicated, the options are set on initialization; for cookie and metadata storage, this happens in the method Init for the Amplitude client:

• amplitude-client.js

 1this.options.apiKey = apiKey;
 2this._storageSuffix =
 3   '_' + apiKey + (this._instanceName === Constants.DEFAULT_INSTANCE ? '' : '_' + this._instanceName);
 4this._storageSuffixV5 = apiKey.slice(0, 6);
 5 
 6this._oldCookieName = this.options.cookieName + this._storageSuffix;
 7this._unsentKey = this.options.unsentKey + this._storageSuffix;
 8this._unsentIdentifyKey = this.options.unsentIdentifyKey + this._storageSuffix;
 9 
10this._cookieName = Constants.COOKIE_PREFIX + '_' + this._storageSuffixV5;
11 
12this.cookieStorage.options({
13   expirationDays: this.options.cookieExpiration,
14   domain: this.options.domain,
15   secure: this.options.secureCookie,
16   sameSite: this.options.sameSiteCookie,
17});
18 
19this._metadataStorage = new MetadataStorage({
20   storageKey: this._cookieName,
21   disableCookies: this.options.disableCookies,
22   expirationDays: this.options.cookieExpiration,
23   domain: this.options.domain,
24   secure: this.options.secureCookie,
25   sameSite: this.options.sameSiteCookie,
26   storage: this.options.storage,
27});
28 
29const hasOldCookie = !!this.cookieStorage.get(this._oldCookieName);
30const hasNewCookie = !!this._metadataStorage.load();
31this._useOldCookie = !hasNewCookie && hasOldCookie && !this.options.cookieForceUpgrade;
32const hasCookie = hasNewCookie || hasOldCookie;

Frequently asked questions

 1/**
 2* Sets whether to opt current user out of tracking.
 3* @public
 4* @param {boolean} enable - if true then no events will be logged or sent.
 5* @example: amplitude.setOptOut(true);
 6*/
 7AmplitudeClient.prototype.setOptOut = function setOptOut(enable) {
 8if (this._shouldDeferCall()) {
 9    return this._q.push(['setOptOut'].concat(Array.prototype.slice.call(arguments, 0)));
10}
11    if (!utils.validateInput(enable, 'enable', 'boolean')) {
12    return;
13}
14    try {
15    this.options.optOut = enable;
16    _saveCookieData(this);
17} catch (e) {
18    utils.log.error(e);
19}
20};

CNIL France - Frequently asked questions