40

Cookies and client-side identity management

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.

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

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.

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

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.

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.

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.

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.

//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': ''})

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']
    }
  },
}