How the Insights API Client for JavaScript Handles User Identifiers

Identifying users with a cookie and a userToken

To determine whether distinct events relate to the same user, each event processed by the Insights API client for JavaScript is associated with a unique user identifier: the userToken.

On initialization, the Insights API automatically creates a unique userToken. This token is randomly generated and persists across sessions in a first-party cookie named _ALGOLIA. This way, every time a user comes back to visit your app or website, their saved userToken will be used to identify them as the same person.

The following sections are specific to the Insights API client for JavaScript when used in a browser environment.

How are userTokens defined?

The Insights API client for JavaScript generates and saves a random userToken for each user in a cookie named _ALGOLIA. This approach has limitations: using cookies lets you uniquely identify a user across multiple sessions, but on a single client. It can’t identify a user across multiple devices.

To solve this issue, you can provide a custom userToken. This is the recommended option, if you have a way to uniquely identify users (for example, an authentication system).

Getting the userToken

You can access the default user token either by reading the _ALGOLIA cookie, or by calling getUserToken.

1
2
3
4
5
6
7
8
// Starting from v1.3.0 of the search-insights.js library
aa('getUserToken', null, (err, userToken) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(userToken);
});

In most common use cases, you want to access this userToken to pass it to the client.

1
2
3
4
5
6
7
8
9
10
// Starting from v1.3.0 of the search-insights.js library
const client = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

aa('getUserToken', null, (err, userToken) => {
  if (err) {
    console.error(err);
    return;
  }
  client.setExtraHeader('X-Algolia-UserToken', userToken);
});

Sending the userToken

By default, the Insights API client for JavaScript sends the userToken that you can retrieve by calling the getUserToken method. There are two ways you can override the default token: globally, or at the method level.

To override the userToken globally, you need to use the setUserToken method. When you do, you don’t have to provide your custom token every time you call a method on the Insights API.

1
2
3
4
5
6
7
8
9
// set a global userToken
aa('setUserToken', 'user-1');

// click event 'Add to favorite' is associated with `user-1`
aa('clickedObjectIDs', {
  index: 'movies_index',
  eventName: 'Add to favorite',
  objectIDs: ['objectID1', 'movieID1']
});

You can override the userToken at any time by passing the userToken parameter when calling an Insights method.

1
2
3
4
5
6
7
// click event 'Add to favorite' is associated to user `user-2`
aa('clickedObjectIDs', {
  userToken: 'user-2',
  index: 'movies_index',
  eventName: 'Add to favorite',
  objectIDs: ['objectID1', 'movieID1']
});

Setting the cookie expiration time

By default, the library sets the cookie to expire 6 months after its creation. You can change this when initializing the client.

1
2
3
4
5
aa('init', {
  appId: 'YourApplicationID',
  apiKey: 'YourSearchOnlyAPIKey',
  cookieDuration: 60 * 60 * 1000 // one hour, in milliseconds (default: 15552000000)
});

Excluding users who want to opt-out of Analytics and Personalization

The Insights API lets you exclude users who want to opt-out of the Analytics and Personalization features. By setting userHasOptedOut to true, you can silently block all requests to the Algolia Insights API.

1
2
3
4
5
aa('init', {
  appId: 'YourApplicationID',
  apiKey: 'YourSearchOnlyAPIKey',
  userHasOptedOut: true // default: false
});

Starting from version 1.6.3 of the Insights API client for JavaScript, setting userHasOptedOut: true prevents the creation of the cookie. For previous versions, userHasOptedOut: true doesn’t prevent the cookie from being created, but it ensures it isn’t used to send events for analytics or personalization purposes.