Distinguish users for analytics

By default, Algolia uses IP addresses to distinguish users. To get more accurate analytics, set a userToken on search requests. If you send searches from your backend, set a userToken to avoid grouping many users under the same server IP address. To learn what a user token is, how to generate it, and how to handle anonymous and authenticated users, see User token.

A userToken is also required for Personalization.

Before you begin

Use the same userToken for searches and click and conversion events so analytics can associate activity with the same user.

Set the user token in InstantSearch and Autocomplete

Set the insights option to true when initializing InstantSearch or 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 }) {
		// ...
	},
});

// Set an anonymous user token
window.aa("setUserToken", "ANONYMOUS_USER_TOKEN");

// Set an authenticated user token
window.aa("setAuthenticatedUserToken", "AUTHENTICATED_USER_TOKEN");

import instantsearch from "instantsearch.js";

const search = instantsearch({
	indexName: "INDEX_NAME",
	searchClient,
	insights: {
		insightsInitParams: {
			// Set anonymous user token
			userToken: "ANONYMOUS_USER_TOKEN",

			// Set authenticated user token
			authenticatedUserToken: "AUTHENTICATED_USER_TOKEN",
		},
	},
});

// Set an anonymous user token
window.aa("setUserToken", "ANONYMOUS_USER_TOKEN");

// Set an authenticated user token
window.aa("setAuthenticatedUserToken", "AUTHENTICATED_USER_TOKEN");

import { InstantSearch } from "react-instantsearch";

<InstantSearch
	indexName="INDEX_NAME"
	searchClient={searchClient}
	insights={{
		insightsInitParams: {
			// Set your own user token
			userToken: "ANONYMOUS_USER_TOKEN",

			// Set an authenticated user token
			authenticatedUserToken: "AUTHENTICATED_USER_TOKEN",
		},
	}}
>
	{/* ... */}
</InstantSearch>;

// Set an anonymous user token
window.aa("setUserToken", "ANONYMOUS_USER_TOKEN");

// Set an authenticated user token
window.aa("setAuthenticatedUserToken", "AUTHENTICATED_USER_TOKEN");

<template>
  <ais-instant-search
    :index-name="INDEX_NAME"
    :search-client="searchClient"
    :insights="insights"
  >
    <!--  widgets  -->
  </ais-instant-search>
</template>

<script>
// Set an anonymous user token
window.aa("setUserToken", "ANONYMOUS_USER_TOKEN");

// Set an authenticated user token
window.aa("setAuthenticatedUserToken", "AUTHENTICATED_USER_TOKEN");

export default {
  data() {
    return {
      insights: {
        insightsInitParams: {
          // Set your own user token
          userToken: "ANONYMOUS_USER_TOKEN",

          // Set an authenticated user token
          authenticatedUserToken: "AUTHENTICATED_USER_TOKEN",
        },
      },
    };
  },
};
</script>

For more information, see:

Set the user token in InstantSearch iOS and Android

Add the userToken as an API parameter to your search requests:

val query = query {
    userToken {
        'ANONYMOUS_USER_TOKEN'
    }
}

val searcher = HitsSearcher(client, indexName, query)

let query = Query()
query.userToken = "ANONYMOUS_USER_TOKEN"
let searcher = HitsSearcher(index: index, query: query)

Set the user token with API clients

Use the same userToken in search requests and click and conversion events. To set the user token per search request:

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

final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    query: "query",
    userToken: "user-1234",
  ),
);

response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
  "INDEX_NAME").WithSearchParams(search.SearchParamsObjectAsSearchParams(
  search.NewEmptySearchParamsObject().SetQuery("query").SetUserToken("user-1234"))))
if err != nil {
  // handle the eventual error
  panic(err)
}

SearchResponse response = client.searchSingleIndex(
  "INDEX_NAME",
  new SearchParamsObject().setQuery("query").setUserToken("user-1234"),
  Hit.class
);

const response = await client.searchSingleIndex({
  indexName: 'indexName',
  searchParams: { query: 'query', userToken: 'user-1234' },
});

var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = SearchParamsObject(query = "query", userToken = "user-1234"),
  )

$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['query' => 'query',
        'userToken' => 'user-1234',
    ],
);

response = client.search_single_index(
    index_name="INDEX_NAME",
    search_params={
        "query": "query",
        "userToken": "user-1234",
    },
)

response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(query: "query", user_token: "user-1234")
)

val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        query = Some("query"),
        userToken = Some("user-1234")
      )
    )
  ),
  Duration(100, "sec")
)

let response: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "INDEX_NAME",
    searchParams: SearchSearchParams.searchSearchParamsObject(SearchSearchParamsObject(
        query: "query",
        userToken: "user-1234"
    ))
)

To set the user token when you initialize an API client:

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);
  }
}

import 'package:algolia_client_search/algolia_client_search.dart';

void globalAlgoliaUserID() async {
  final client = SearchClient(
      appId: 'ALGOLIA_APPLICATION_ID',
      apiKey: 'ALGOLIA_API_KEY',
      options: ClientOptions(
        headers: {
          'X-Algolia-User-ID': 'test-user-123',
        },
      ));
  print(client.options.headers);
}

package main

import (
	"fmt"

	"github.com/algolia/algoliasearch-client-go/v4/algolia/search"
)

func globalAlgoliaUserID() {
	client, err := search.NewClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
	if err != nil {
		fmt.Println(err)
	}

	client.AddDefaultHeader("X-Algolia-UserToken", "test-user-123")
}

package com.algolia;

import com.algolia.api.SearchClient;
import com.algolia.config.*;
import com.algolia.model.search.*;

public class globalAlgoliaUserID {

  public static void main(String[] args) throws Exception {
    SearchClient client = new SearchClient(
      "ALGOLIA_APPLICATION_ID",
      "ALGOLIA_API_KEY",
      ClientOptions.builder().addDefaultHeader("X-Algolia-UserToken", "test-user-123").build()
    );
    client.close();
  }
}

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY', {
  baseHeaders: {
    'X-Algolia-User-ID': 'test-user-123',
  },
});
console.log(client);

import com.algolia.client.api.SearchClient
import com.algolia.client.configuration.*
import com.algolia.client.extensions.*
import com.algolia.client.model.search.*
import com.algolia.client.transport.*

suspend fun globalAlgoliaUserID() {
  val client =
    SearchClient(
      appId = "ALGOLIA_APPLICATION_ID",
      apiKey = "ALGOLIA_API_KEY",
      options = ClientOptions(defaultHeaders = mapOf("X-Algolia-User-ID" to "test-user-123")),
    )
  println(client.options.defaultHeaders)
}

<?php

require __DIR__.'/../vendor/autoload.php';
use Algolia\AlgoliaSearch\Api\SearchClient;

$config = SearchConfig::create('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY');
$config->setDefaultHeaders(['X-Algolia-UserToken' => 'test-user-123']);
$client = SearchClient::createWithConfig($config);
echo $client->getClientConfig()->getDefaultHeaders();

from algoliasearch.search.client import SearchClientSync
from algoliasearch.search.config import SearchConfig


_config = SearchConfig("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
_config.headers["x-algolia-userToken"] = "test-user-123"
_client = SearchClientSync.create_with_config(_config)
print(_client)

import(time)

require "algolia"

client = Algolia::SearchClient.create(app_id, api_key)
client.api_client.config.header_params["X-Algolia-UserToken"] = "test-user-123"
puts(client.api_client.config.header_params)

import algoliasearch.api.SearchClient
import algoliasearch.config.*
import algoliasearch.extension.SearchClientExtensions

def globalAlgoliaUserID(): Unit = {
  val client = SearchClient(
    appId = "ALGOLIA_APPLICATION_ID",
    apiKey = "ALGOLIA_API_KEY",
    clientOptions = ClientOptions(
      defaultHeaders = Map("X-Algolia-UserToken" -> "test-user-123")
    )
  )
  println(client)
}

If you can’t set a user token

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

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Distinguish users for analytics

Before you begin

Set the user token in InstantSearch and Autocomplete

Set the user token in InstantSearch iOS and Android

Set the user token with API clients

If you can’t set a user token

​Before you begin

​Set the user token in InstantSearch and Autocomplete

​Set the user token in InstantSearch iOS and Android

​Set the user token with API clients

​If you can’t set a user token

Before you begin

Set the user token in InstantSearch and Autocomplete

Set the user token in InstantSearch iOS and Android

Set the user token with API clients

If you can’t set a user token