# Cookies and client-side identity management

## How it works[](#how-it-works)

The JavaScript library stores some information in cookies and local storage on the client to manage user identity. By default, we store up to five cookies on the client. You can recall this information when you need to reuse it and change whether we persist data to protect your audience’s personal information.

Cookie

Contains

`ajs_anonymous_id`

A user’s anonymous ID, set automatically when someone visits your site. This value is used to track anonymous activity and associate anonymous activity with an identified person.

`ajs_user_id`

The ID of the user, set when you `identify` a person.

`ajs_group_id`

The ID of a group, set when you associate a person with a `group`.

`ajs_user_traits`

Contains user attributesInformation that you know about a person, captured from `identify` events in Data Pipelines. Traits are analogous to *attributes* in Customer.io Journeys.—values associated with a person—that you set when you `identify` a person.

`ajs_group_traits`

Contains group traits—values associated with an [objectAn object is a non-person entity that you can associate with one or more people—like a company, account, or online course.](/journeys/objects/)—that you set when you associate a person with a `group`.

 Our JavaScript client only sets first-party cookies. However, [direct integrations](/integrations/data-out/getting-started/#connection-modes) might choose to set their own cookies—like [Meta Pixel](/integrations/data-out/connections/meta-pixel/) or [Google Analytics 4](/integrations/data-out/connections/google-analytics-4/). See your integration’s Cookie & Privacy Policy for more information.

## User ID and local storage[](#user-id-and-local-storage)

To ensure the fidelity of customer data, we write your audience’s IDs to both local storage and cookies whenever possible. Local storage is designed for this type of first-party customer information.

If a user returns to your site after our `ajs_user_id` cookie expires, Analytics.js looks for an ID in the user’s `localStorage`. If we find an ID there, we set it as the user’s ID again in a new cookie. This ensures that people stay “identified” in most cases.

But if a user clears their cookies *and* `localStorage`, they’ll remove all their identifying information and get a completely new `anonymousID` the next time they visit your website.

## Cookie settings[](#cookie-settings)

Our JavaScript client sets properties when creating cookies for user or group identities. You can override the default cookie properties when you load Analytics.js by passing a `cookie` object to the load method. You can modify the following parameters.

Parameter

Description

Default

`domain`

The domain for the cookie. This must match the domain of the JavaScript origin. If an Analytics.js cookie already exists at the top-level domain, we carry the same cookie value to any subdomains, despite `domain` configuration.

Top-level domain

`maxage`

The maximum time (in days) before the cookie expires on its own.

365 days (1 year)

`path`

The path the cookie is valid for.

`"/"`

`sameSite`

Prevents the browser from sending the cookie along with cross-site requests.

`Lax`

`secure`

Boolean determining whether cookies must be transferred over secure protocols (https) or not.

`false`

```js
cioanalytics.load('writeKey', {
  cookie: {
    domain: 'sub.site.example',
    maxage: 7, // 7 days
    path: '/',
    sameSite: 'Lax',
    secure: true
  }
})
```

 Chrome limits cookies to 400 days

If you try to set the `maxage` value beyond 400 days, then Chrome sets the upper limit to 400 days instead of rejecting it.

## Cross-site cookie support[](#cross-site-cookie-support)

To enable cross-site cookie support, initialize the SDK with the following cookie settings:

```js
analytics.load('YOUR_WRITE_KEY', {
  cookie: {
    sameSite: 'None',
    secure: true
  }
});
```

The `sameSite: 'None'` setting allows the cookie to be sent in cross-site requests. The `secure: true` setting ensures the cookie is only transmitted over HTTPS connections, which is required when using `sameSite: 'None'`.

Cross-site tracking may not work for all users. Some browsers, like Safari, block cross-site tracking by default through privacy settings.

### User settings[](#user-settings)

When you identify a person, we automatically persist their ID and traits locally. You can override how and where you want to store the user ID and traits when you load Analytics.js by passing a `user` object to the load method.

Option

Description

Default

`persist`

When `true`, Analytics.js stores information locally.

`true`

`cookie.key`

The name of the cookie that stores the user ID.

`ajs_user_id`

`cookie.oldKey`

The name of a cookie that previously stored the user ID. Analytics.js will read this cookie if `cookie.key` isn’t found.

`ajs_user`

`localStorage.key`

The name of the key that stores user traits in localStorage.

`ajs_user_traits`

```js
cioanalytics.load('writeKey', {
  user: {
    persist: true,
    cookie: {
      key: 'ajs_user_id'
    },
    localStorage: {
      key: 'ajs_user_traits'
    }
  }
})
```

### Group settings[](#group-settings)

We automatically persist your audience’s associated group ID and group properties locally. You can override how and where you want to store the group ID and properties by passing in a `group` object to the load method when you load Analytics.js.

Field

Description

Default

`persist`

When `true`, Analytics.js stores group information locally.

`true`

`cookie.key`

Name of the cookie that stores the group id.

`ajs_group_id`

`localStorage.key`

Name of the key that stores user traits in localStorage.

`ajs_group_properties`

```js
cioanalytics.load('writeKey', {
  group: {
    persist: true,
    cookie: {
      key: 'ajs_group_id'
    },
    localStorage: {
      key: 'ajs_group_properties'
    }
  }
})
```

## Persistent retries[](#persistent-retries)

By default, Analytics.js automatically retries on network and server errors. When the client is offline or your application can’t connect to Customer.io, Analytics.js stores events in `localStorage` and falls back to in-memory storage when `localStorage` is unavailable.

## Disable identity persistence[](#disable-identity-persistence)

By default, Analytics.js automatically persists user and group identities in cookies and local storage. You can change this behavior using the `disableClientPersistence` setting. `disableClientPersistence` is a boolean that defaults to `false`, meaning that we’ll persist identity in local storage, cookies, and memory. Setting to `true` disables all persistence.

```js
// Disable all persistence methods
cioanalytics.load('writeKey', { disableClientPersistence: true })
```

Disabling client persistence means you won’t be able to track people across pages. You might do this in situations where you customers’ data is extremely sensitive. But you can still track people on each page. See the sections below for more details.

### Identify[](#identify)

When `disableClientPersistence` is set to `true`, Analytics.js cannot automatically keep track of a user’s identity when they go to different pages.

You can still manually track identity by calling `cioanalytics.identify()` with the known identity on each page load, or you can pass in identity information to each page using [query strings](/integrations/data-in/connections/javascript/js-source/#querystring-methods).

### Event retries[](#event-retries)

Under normal circumstances, Analytics.js tries to determine when your audience might close a page and saves pending events to `localStorage`. When your audience goes to another page in the same domain, Analytics.js attempts to send any events it finds in localStorage.

When `disableClientPersistence` is set to `true`, Analytics.js won’t store pending events in `localStorage`.

## Client-side cookie methods (get, set, clear)[](#client-side-cookie-methods-get-set-clear)

When you invoke a standard method for Analytics.js (identify, track, group, etc), the client-side library automatically sets cookies and local storage for you. The following methods help you get or assign values to cookies outside the standard JavaScript methods. You might want to do this to use your audience’s data to personalize elements on pages or to sanitize your audience’s data.

To get a cookie’s value, pass an empty `()` at the end of the method.

```js
//return the user ID cookie (ajs_user_id) value
cioanalytics.user().id()
```

To assign a cookie’s value, include the string value inside those parenthesis, for example, `('123-abc')`. To clear or remove the value for a specific field, pass in an empty value of its type. For example, for string `('')`, or for object `({})`.

```js
//clear a user trait
cioanalytics.user().traits({'redacted-pii': ''})
```

Field

Cookie Name

Analytics.js Method

Local Storage Method

Set Example

Clear Example

`userId`

`ajs_user_id`

`cioanalytics.user().id();`

`window.localStorage.ajs_user_id`

`cioanalytics.user().id('123-abc');`

`cioanalytics.user().id('');`

`anonymousId`

`ajs_anonymous_id`

`cioanalytics.user().anonymousId();`

`window.localStorage.ajs_anonymous_id`

`cioanalytics.user().anonymousId('333-abc-456-dfg');`

`cioanalytics.user().anonymousId('');`

`user traits`

`ajs_user_traits`

`cioanalytics.user().traits();`

`window.localStorage.ajs_user_traits`

`cioanalytics.user().traits({firstName:'Jane'});`

`cioanalytics.user().traits({});`

`groupId`

`ajs_group_id`

`cioanalytics.group().id();`

`window.localStorage.ajs_group_id`

`cioanalytics.group().id('777-qwe-098');`

`cioanalytics.group().id('');`

`group traits`

`ajs_group_properties`

`cioanalytics.group().traits()`

`window.localStorage.ajs_group_properties`

`cioanalytics.group().traits({name:'Customer.io'})`

`cioanalytics.group().traits({})`

## Storage Priority[](#storage-priority)

By default, Analytics.js uses `localStorage` as its preferred storage location with Cookies as a fallback when `localStorage` is not available or not populated. An in-memory storage is used as a last fallback if all the previous ones are unavailable for any reason.