How the Insights API for JavaScript Client Handles User Identifiers

Identifying users with a Cookie and a User Token

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.

Using cookies allows you to uniquely identify a user across multiple sessions, on a single client. It cannot uniquely identify a user interacting with your app or website through multiple devices. If this is your case, and if you have your own authentication system, you can provide a userToken based on the ID of your user.

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
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
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 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, we’ve set our 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
});