Guides / Getting insights and analytics / Search analytics / Click-through and conversion analytics

How the Insights API for JavaScript Client Handles User Identifiers

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?

By default, the engine uses the IP address that initiated the request as the userToken. This is, however, only a fallback mechanism to ensure there’s a value. We strongly recommend that you always specify a custom userToken.

When using the Insights API client for JavaScript, a random userToken is generated and saved for you 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 (e.g., 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 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']
});

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
});

Did you find this page helpful?