User token
On this page
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:
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 thesetUserToken
method. When you do, you don’t have to provide your custom token every time you call a method on the Insights API.Copy1 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 theuserToken
parameter when calling an Insights method.Copy1 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
andenablePersonalization
tofalse
to turn off these features.