User token
On this page
User tokens are strings that uniquely identify users throughout your app. They link click and conversion events with user profiles. Algolia uses user tokens to boost the effectiveness of Search analytics and build user profiles for Personalization and Recommendations.
You should never include personally identifiable information in user tokens.
For more information about the correct format of a user token, see userToken
(Insights API).
How does the Search Insights JavaScript library handle user tokens?
The Search Insights library (version 2 and later) generates anonymous user tokens on every page load. By default, user tokens don’t persist. This helps with data protection regulations, but means you can’t distinguish new from returning users, since a new user token is generated on every page visit.
See how the user token changes when a user refreshes the page
This limits the effectiveness of Analytics and Personalization, since the generated tokens have a short lifespan. To increase the lifespan of user tokens, you should persist them across sessions.
Version 1 of the Search Insights library generates anonymous user tokens and stores them in a cookie by default.
Persistent user token
For more accurate analytics and better personalization experiences, you should persist user tokens across sessions.
Authenticated user token
If you’re using an authentication system for your users,
use the setUserToken
method to set the authenticated user token as the userToken
parameter for the Insights client.
1
2
const authenticatedUserToken = getAuthenticatedUserTokenAfterLogIn();
aa('setUserToken', authenticatedUserToken);
Your authentication system usually provides an API for getting the user token,
which is represented by the getAuthenticatedUserTokenAfterLogin()
function.
If you’re not using user authentication, use a cookie to persist the user token.
This is important because if a user initially visits a site without signing in, they’re assigned an anonymous ID. If they later sign in and receive an authenticated user ID,
their previous activity as an anonymous user would be lost.
By persisting the anonymous userToken
in a cookie, you can ensure continuity of user activity and prevent data loss during the transition from anonymous to authenticated status.
Algolia cookie
To store the userToken
in a first-party cookie with the name _ALGOLIA
on the user’s device,
set the useCookie
parameter in the init
method to true
.
This lets you identify users across sessions with the persistent, anonymous user token.
1
2
3
4
5
aa('init', {
appId: 'YourApplicationID',
apiKey: 'YourSearchOnlyAPIKey',
useCookie: true, // since v2, this is false by default
});
Before setting useCookie
to true
, you should get user consent.
For example, you can dynamically update the useCookie
parameter when the user accepts non-essential cookies.
Use the partial
parameter to only update the useCookie
option without changing the others.
1
2
3
4
5
6
7
8
9
10
11
// User accepts cookies
aa('init', {
partial: true,
useCookie: true,
});
// User rejects cookies
aa('init', {
partial: true,
useCookie: false,
});
Adjust the cookie expiration time
By default, the _ALGOLIA
cookie expires after 6 months.
To adjust the lifespan of the cookie, set the cookieDuration
parameter.
1
2
3
4
5
6
7
8
const DAY = 1000 * 60 * 60 * 24;
aa('init', {
appId: 'YourApplicationID',
apiKey: 'YourSearchOnlyAPIKey',
useCookie: true,
cookieDuration: 90 * DAY, // 90 days, in milliseconds (default: 15552000000)
});
Third-party cookies
Third-party cookies are stored on the user’s device and belong to domains other than the website the user is visiting. They enable advertisers, analytics platforms, and other third-party services to collect data about a user’s browsing behavior across multiple websites.
To maintain the reliability of the collected data, providers of third-party cookies, such as Google Analytics or Segment often use a stable user token that remains consistent across multiple websites. You can use one of these third-party cookies as a user token in the Search Insights library.
Google Analytics
Google Analytics stores its persistent, anonymous user token in a cookie called _ga
.
If you’re already using Google Analytics on your website, you can use that user token as the Search Insights library’s userToken
parameter.
The value of the _ga
cookie follows the pattern GA1.1.1900000000.1684510679
and has three components:
GA1.1.
. Indicates the version of the Google Analytics tracking library used to generate the cookie.1900000000
. A unique identifier for distinguishing individual users.1684510679
. The timestamp when the cookie was created, in Unix epoch time.
To extract the unique user ID from the cookie, you can use the following function:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
/**
* Extracts the user ID from the Google Analytics device ID.
* @example `GA1.1.xxxxxxxxxx.xxxxxxxxxx => xxxxxxxxxx_xxxxxxxxxx`
* @link https://support.google.com/analytics/answer/11397207
*/
function extractGoogleAnalyticsUserIdFromCookie(gaCookie) {
if (gaCookie) {
// Remove the Google Analytics tracker from the device ID.
const userIdParts = gaCookie.split('.').slice(-2);
if (userIdParts.length === 2) {
return userIdParts.join('_');
}
}
return undefined;
}
function getBrowserCookie(cookieName) {
// In React Native environments, `document.cookie` doesn't exist.
if (typeof document !== 'object' || typeof document.cookie !== 'string') {
return undefined;
}
const name = cookieName + '=';
const decodedCookie = decodeURIComponent(document.cookie);
const ca = decodedCookie.split(';');
for (let i = 0; i < ca.length; i++) {
let c = ca[i];
while (c.charAt(0) === ' ') {
c = c.substring(1);
}
if (c.indexOf(name) === 0) {
return c.substring(name.length, c.length);
}
}
return undefined;
}
/**
* Returns the Google Analytics User ID from a browser cookie name.
* @example `getGoogleAnalyticsUserIdFromBrowserCookie('_ga')`
*/
function getGoogleAnalyticsUserIdFromBrowserCookie(cookieName) {
const browserCookie = getBrowserCookie(cookieName);
if (!browserCookie) {
return undefined;
}
return extractGoogleAnalyticsUserIdFromCookie(browserCookie);
}
Then, you can use the user ID from the Google Analytics cookie as the userToken
for Search Insights with setUserToken
.
1
2
3
const userToken = getGoogleAnalyticsUserIdFromBrowserCookie('_ga');
aa('setUserToken', userToken);
Segment
Segment stores its persistent, anonymous user token in a cookie called ajs_anonymous_id
.
If you’re already using Segment on your website, you can use that user token as the Search Insights library’s userToken
parameter.
Using Segment’s Analytics.js 2.0 library,
you can get the user token from the function analytics.user().anonymousId()
.
Get the user token from Search Insights
With the Search Insights library, you can retrieve the userToken
by calling getUserToken
.
1
2
3
4
5
6
7
8
// Starting from v1.3.0 of the search-insights.js library
aa('getUserToken', {}, (err, userToken) => {
if (err) {
console.error(err);
return;
}
console.log(userToken);
});
Send user token with click and conversion events
The Search Insights library lets you override the default user token and send the userToken
in two ways: either globally or for each event.
To set the userToken
parameter globally, use the setUserToken
method.
This way, you don’t need to provide your user token every time you send an event.
1
2
3
4
5
6
7
8
9
// Set a global user token
aa('setUserToken', 'user-1');
// Send a click event associated with "user-1"
aa('clickedObjectIDs', {
index: 'movies',
eventName: 'Added to favorite',
objectIDs: ['movieID1'],
});
To send a user token with each event, add the userToken
parameter to the event object.
1
2
3
4
5
6
7
// Send a click event associated with "user-2"
aa('clickedObjectIDs', {
userToken: 'user-2',
index: 'movies',
eventName: 'Added to favorite',
objectIDs: ['movieID1'],
});
Exclude 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 parameters
analytics
andenablePersonalization
tofalse
to turn off these features.