Cookies and client-side identity management

Updated

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. As a part of the analytics.load method, you can override cookie settings and the local data to meet your needs and secure your audience’s personal information.

CookieContains
ajs_anonymous_idA 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_idThe ID of the user, set when you identify a person.
ajs_group_idThe ID of a group, set when you associate a person with a group.
ajs_user_traitsContains user traitsInformation 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_traitsContains group traits—values associated with a group—that you set when you associate a person with a group.

 Our JavaScript client only sets first-party cookies. However, direct destinations might choose to set their own cookies—like Meta Pixel or Google Analytics 4. See your destination’s Cookie & Privacy Policy for more information.

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.

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.

ParameterDescriptionDefault
domainThe 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
maxageThe maximum time (in days) before the cookie expires on its own.365 days (1 year)
pathThe path the cookie is valid for."/"
sameSitePrevents the browser from sending the cookie along with cross-site requests.Lax
secureBoolean determining whether cookies must be transferred over secure protocols (https) or not.false
analytics.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.

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.

OptionDescriptionDefault
persistWhen true, Analytics.js stores information locally.true
cookie.keyThe name of the cookie that stores the user ID.ajs_user_id
cookie.oldKeyThe 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.keyThe name of the key that stores user traits in localStorage.ajs_user_traits
analytics.load('writeKey', {
  user: {
    persist: true,
    cookie: {
      key: 'ajs_user_id'
    },
    localStorage: {
      key: 'ajs_user_traits'
    }
  }
})

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.

FieldDescriptionDefault
persistWhen true, Analytics.js stores group information locally.true
cookie.keyName of the cookie that stores the group id.ajs_group_id
localStorage.keyName of the key that stores user traits in localStorage.ajs_group_properties
analytics.load('writeKey', {
  group: {
    persist: true,
    cookie: {
      key: 'ajs_group_id'
    },
    localStorage: {
      key: 'ajs_group_properties'
    }
  }
})

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 all client-side persistence

You can disable local data persistence. This forces analytics.js to store data in-memory and disables automatic identity tracking across pages. You might want to do this in situations where your customers’ data is extremely sensitive.

You can completely disable client-side persistence when you load Analytics.js by setting disableClientPersistence to true.

analytics.load('writeKey', { disableClientPersistence: true })

Identity

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 analytics.identify() with the known identity on each page load, or you can pass in identity information to each page using query strings.

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.

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.

//return the user ID cookie (ajs_user_id) value
analytics.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 ({}).

//clear a user trait
analytics.user().traits({'redacted-pii': ''})
FieldCookie NameAnalytics.js MethodLocal Storage MethodSet ExampleClear Example
userIdajs_user_idanalytics.user().id();window.localStorage.ajs_user_idanalytics.user().id('123-abc');analytics.user().id('');
anonymousIdajs_anonymous_idanalytics.user().anonymousId();window.localStorage.ajs_anonymous_idanalytics.user().anonymousId('333-abc-456-dfg');analytics.user().anonymousId('');
user traitsajs_user_traitsanalytics.user().traits();window.localStorage.ajs_user_traitsanalytics.user().traits({firstName:'Jane'});analytics.user().traits({});
groupIdajs_group_idanalytics.group().id();window.localStorage.ajs_group_idanalytics.group().id('777-qwe-098');analytics.group().id('');
group traitsajs_group_propertiesanalytics.group().traits()window.localStorage.ajs_group_propertiesanalytics.group().traits({name:'Customer.io'})analytics.group().traits({})

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 disabled.

LocalStorage > Cookies > InMemory

But you can change the storage priority in the Analytics.js client using the storage property. You might need to do this if:

  • Your app moves the user across different subdomains
  • Your app/server needs control over user data
  • Your audience doesn’t consent to cookie collection

The storage property accepts an array of supported storage names (localStorage, cookie, memory) in the order you want to use them.

analytics.load('writeKey', {
  // Global Storage Priority: Both User and Group data
  storage: {
    stores: ['cookie', 'localStorage', 'memory']
  },
  // Specific Storage Priority
  user: {
    storage: {
      stores: ['cookie', 'localStorage', 'memory']
    }
  },
  group: {
    storage: {
      stores: ['cookie', 'localStorage', 'memory']
    }
  },
}
Copied to clipboard!
  Contents
Is this page helpful?