User token

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 of search requests
• Recommend collaborative filtering.

You should always use pseudonymous or anonymous information in a userToken and never include personally identifiable information.

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: cookies let 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, with an authentication system.

Since v2, search-insights doesn’t generate and store anonymous user tokens 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 a 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);
});

You usually want to access this userToken and 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. You can override the default token in two ways: 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.

  JavaScript

  Copy

  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.

  JavaScript

  Copy

  1
  2
  3
  4
  5
  6
  7
  // click event 'Add to favorite' is associated with `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 six 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.
• Set the search parameters analytics and enablePersonalization to false to turn off these features.