Distinguish users for analytics

Learn how to set the user token for better analytics.

By default, Algolia uses the IP address to distinguish users. For more accurate analytics, you can explicitly set a user token. This is especially important if you’re searching from your backend, as all searches would have the IP address of your server.

It’s best to create reliable unique identifiers that you store in your app or database. For example, you could use your own user session identifiers once users start their session.

For Personalization to work, you must send a user token with each search request.

Set the user token in InstantSearch and Autocomplete

Set the insights option to true when initializing InstantSearch or Autocomplete.

Autocomplete

import { autocomplete } from "@algolia/autocomplete-js";
import algoliasearch from "algoliasearch/lite";

const appID = "ALGOLIA_APPLICATION_ID";
const apiKey = "ALGOLIA_SEARCH_API_KEY";

const searchClient = algoliasearch(appID, apiKey);

autocomplete({
	container: "#autocomplete",
	placeholder: "Search ...",
	insights: true,
	getSources({ query }) {
		// ...
	},
});

// You can also use insights to set an anonymous user token
window.aa("setUserToken", "anonymous-user-123");

// You can also use insights to set an authenticated user token
window.aa("setAuthenticatedUserToken", "authenticated-user-123");

For more information, see:

• Send click and conversion events with Autocomplete
• Send click and conversion events with InstantSearch.js
• Send click and conversion events with React InstantSearch
• Send click and conversion events with Vue InstantSearch
• Understand the user token

If you’re using InstantSearch iOS or InstantSearch Android, add the userToken as an API parameter to your search requests:

Android

val query = query {
    userToken {
        'test-user-123'
    }
}

val searcher = HitsSearcher(client, indexName, query)

Set the user token with API clients

The user token should match the userToken in events sent to the Insights API (also known as the anonymous user token, or session user token).

To set the user token per search request:

C#

var response = await client.SearchSingleIndexAsync<Hit>(
  "ALGOLIA_INDEX_NAME",
  new SearchParams(new SearchParamsObject { Query = "query", UserToken = "user-1234" })
);

To set the user token when initializing one of the API clients:

C#

namespace Algolia;

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Text.Json;
using Algolia.Search.Clients;
using Algolia.Search.Http;
using Algolia.Search.Models.Search;

class GlobalAlgoliaUserID
{
  async Task Main(string[] args)
  {
    var client = new SearchClient(
      new SearchConfig("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
      {
        DefaultHeaders = new Dictionary<string, string>
        {
          { "X-Algolia-UserToken", "test-user-123" },
        },
      }
    );
    Console.WriteLine(client);
  }
}

If you search from your backend and don’t want to set a userToken, you can forward user IP addresses.