Client-side persistence in Analytics.js

This page explains what data Analytics.js stores on the client and how to override and change what and how this data is stored.

Segment ID persistence

To ensure high fidelity, first-party customer data, Segment writes the user’s IDs to the user’s local storage and uses that as the Segment ID on the cookie whenever possible. Local storage is for storing this type of first-party customer information.

If a user returns to your site after the cookie expires, Analytics.js looks for an old ID in the user’s localStorage, and if one is found, it sets as the user’s ID again in the new cookie. If a user clears their cookies and localStorage, all of the IDs are removed, and the user gets a completely new anonymousID when they next visit the page.

Cookie settings

Analytics.js sets some default properties when creating cookies for user or group identities. You can override the default cookie properties in code when loading Analytics.js by passing in a cookie object to the load method.

Here is the full list of available parameters with their default values:

Example:

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

To set cookie values using the NPM package, use the following code snippet:

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

Device-mode destination cookies

Segment doesn’t control cookie management for device-mode destinations. As a result, the way cookies are used and managed is solely determined by each individual SDK. For example, if you have concerns about destinations setting third-party cookies, Segment recommends that you consult directly with the destination providers for clarification. For instance, Amplitude, one of the destinations in the Segment catalog, provides an informative article on this topic.

User settings

Analytics.js automatically persists the user’s ID and traits locally. You can override how and where the user ID and traits are stored when loading Analytics.js by passing in a user object to the load method.

The user object has the following fields and default values:

Example:

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

Group settings

Analytics.js automatically persists the user’s group ID and group properties locally. You can override how and where the group ID and properties are stored when loading Analytics.js by passing in a group object to the load method.

The group object has the following fields and default values:

Example:

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

Persistent retries

When enabled, Analytics.js automatically retries network and server errors. When the client is offline or your application can’t connect to Segment’s API, Analytics.js stores events in localStorage and falls back to in-memory storage when localStorage is unavailable.

Disable all client-side persistence

Analytics.js supports disabling persisting any data locally. This will force analytics.js to store data in-memory only and disables automatic identity tracking across pages.

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

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

Identity

When disableClientPersistence is set to true, Analytics.js won’t be able to automatically keep track of a user’s identity when navigating to different pages. This can cause increased MTU usage if the anonymous usage can’t be associated with a userId.

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 the querystring API.

Event retries

Analytics.js tries to detect when a page is about to be closed and saves pending events to localStorage. When the user navigates to another page within 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 any pending events into localStorage.

Client-side cookie methods (get, set, clear)

To access or assign a value to a cookie outside of the standard Segment methods (track/identify/page/group), you can use the following methods. To access the cookie’s value, pass an empty () at the end of the method. To assign the 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 ({}).

To retrieve a specific user trait using the Analytics.js Get method, you can access the trait by invoking analytics.user().traits().firstName. This returns the firstName trait of the user.

To retrieve a specific group trait, you can use the method analytics.group().traits().companyName. This returns the companyName trait of the group.

When you access specific traits stored in the browser’s localStorage, you need to utilize the JSON.parse() method because the stored data is typically in string format.

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.

Default Storage Priority:

LocalStorage -> Cookie -> InMemory

Some scenarios might require a switch in the storage systems priority:

• Apps that move the user across different subdomains
• Apps where the server needs control over the user data
• User Consent
• Availability

You can configure the storage priority in the Analytics.js client using the storage property, either globally or only for user or group data.

The storage property accepts an array of supported storage names (localStorage, cookie, memory) to be used in the priority order of the array.

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