User token

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.

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 and enablePersonalization to false to turn off these features.