Generating UserToken

All events need to include a userToken that relates a user profile to an event. Algolia uses this token to build user-specific affinity profiles for Personalization and Recommend. You should always send pseudonymous or anonymous userToken.

You should never include personally identifiable information in a userToken.

How does the JavaScript API client handle userToken?

The Insights API client for JavaScript generates and saves a random userToken for each user in a first-party 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 should generate and send your own userToken. Often, you already use some method to identify users, for example, via an authentication system.

Since v2, search-insights doesn’t generate and store anonymous user token in the _ALGOLIA cookie by default. If you wish to keep the behavior, you can pass useCookie: true to init method.

Getting the userToken

In search-insights@v1, an anonymous user token is generated and stored in cookie by default. You can access it 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
11
12
13
14
15
// Starting from v1.3.0 of the search-insights.js library
const client = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

let userToken;

aa('getUserToken', null, (err, newUserToken) => {
  if (err) {
    console.error(err);
    return;
  }
  userToken = newUserToken;
});

// API client setup and configuration
client.search([{indexName: '...', params: {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
6
aa('init', {
  appId: 'YourApplicationID',
  apiKey: 'YourSearchOnlyAPIKey',
  useCookie: true,  // since v2, this is false by default
  cookieDuration: 60 * 60 * 1000 // one hour, in milliseconds (default: 15552000000)
});

Excluding users who want to opt out of Analytics, Recommend, and Personalization

To allow users to opt out of Analytics, Recommend, and Personalization features:

• Don’t instantiate the Insights API client for users that have opted out.
• Make sure to set the search parameters analytics and enablePersonalization to false to turn off these features.