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 setAuthenticatedUserToken method to set the authenticated user token as the authenticatedUserToken parameter for the Insights client.

1
2
const authenticatedUserToken = getAuthenticatedUserTokenAfterLogIn();
aa('setAuthenticatedUserToken', authenticatedUserToken);

Your authentication system usually provides an API for getting the user token, which is represented by the getAuthenticatedUserTokenAfterLogin() function.

It is important to set the authenticatedUserToken parameter for authenticated users rather than userToken, which is intended to be used for anonymous tokens. 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, setting the userToken to the authenticated user ID would overwrite the anonymous ID, meaning their previous activity as an anonymous user won’t be associated with the authenticated user. By sending the anonymous and authenticated user tokens in separate parameters, you can ensure continuity of user activity and prevent data loss during the transition from anonymous to authenticated status.

If you’re not using user authentication, use a cookie to persist the anonymous user token in the userToken parameter.

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 anonymous user token 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);
});

Similarly, you can retrieve an authenticated user token by calling getAuthenticatedUserToken.

1
2
3
4
5
6
7
8
// Starting from v2.9.0 of the search-insights.js library
aa('getAuthenticatedUserToken', {}, (err, authenticatedUserToken) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(authenticatedUserToken);
});

Send user token with click and conversion events

The Search Insights library sets a default anonymous userToken. You can also manually set the userToken or authenticatedUserToken parameter in two ways: either globally or for each event.

To set userToken or authenticatedUserToken globally, you can pass them on init or use the setUserToken or setAuthenticatedUserToken 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
10
11
12
13
14
15
16
17
18
19
// Set a global anonymous user token before a user is identified
aa('setUserToken', 'anonymous-1');

// Send a click event associated with "anonymous-1"
aa('clickedObjectIDs', {
  index: 'movies',
  eventName: 'Added to favorite',
  objectIDs: ['movieID1'],
});

// Set a global authenticated user token, for example, after a user logs in
aa('setAuthenticatedUserToken', 'user-1');

// Send a click event associated with both "anonymous-1" and and "user-1"
aa('clickedObjectIDs', {
  index: 'movies',
  eventName: 'Added to favorite',
  objectIDs: ['movieID1'],
});

To send user tokens with each event, add the userToken and authenticatedUserToken parameters to the event object.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// Send a click event associated with "anonymous-2"
aa('clickedObjectIDs', {
  userToken: 'anonymous-2',
  index: 'movies',
  eventName: 'Added to favorite',
  objectIDs: ['movieID1'],
});

// Send a click event associated with both "anonymous-2" and "user-2"
aa('clickedObjectIDs', {
  userToken: 'anonymous-2',
  authenticatedUserToken: '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.