Guides / Sending events / Implementing events / Best practices

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.

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

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, 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.

Did you find this page helpful?