Distinguish users for analytics

Set the user token in InstantSearch and Autocomplete

If you’re using Autocomplete, InstantSearch.js, React InstantSearch, or Vue InstantSearch, set the insights option to true when initializing the library.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import { autocomplete } from "@algolia/autocomplete-js";
import algoliasearch from "algoliasearch/lite";

const appID = "YourApplicationID"
const apiKey = "YourSearchAPIKey"

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import instantsearch from 'instantsearch.js';

const search = instantsearch({
  indexName: "YourIndexName",
  searchClient,
  insights: {
    insightsInitParams: {
      // Set anonymous user token
      userToken: 'anonymous-user-123',

      // Set authenticated user token
      authenticatedUserToken: 'authenticated-user-123',
    },
  }
})

// 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");

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import { InstantSearch } from "react-instantsearch";

<InstantSearch
  indexName="YourIndexName"
  searchClient={searchClient}
  insights={{
    insightsInitParams: {
      // Set your own user token
      userToken: 'anonymous-user-123',

      // Set an authenticated user token
      authenticatedUserToken: 'authenticated-user-123',
    },
  }}
>
  {/* ... */}
</InstantSearch>

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

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

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
<template>
  <ais-instant-search
    :index-name="<index-name>"
    :search-client="searchClient"
    :insights="insights"
  >
    <!-- widgets -->
  </ais-instant-search>
</template>

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

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

export default {
  data() {
    return {
      insights: {
        insightsInitParams: {
          // Set your own user token
          userToken: 'anonymous-user-123',

          // Set an authenticated user token
          authenticatedUserToken: 'authenticated-user-123',
        }
      }
    }
  }
}
</script>

Guides 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 Angular InstantSearch, InstantSearch iOS, or InstantSearch Android, add the userToken as an API parameter to your search requests:

Copy

1
2
3
4
5
6
7
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:

Copy

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

1
2
3
4
5
6
7
final response = await client.searchSingleIndex(
  indexName: "ALGOLIA_INDEX_NAME",
  searchParams: SearchParamsObject(
    query: "query",
    userToken: "user-1234",
  ),
);

1
2
3
4
5
6
7
response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
  "ALGOLIA_INDEX_NAME").WithSearchParams(search.SearchParamsObjectAsSearchParams(
  search.NewEmptySearchParamsObject().SetQuery("query").SetUserToken("user-1234"))))
if err != nil {
  // handle the eventual error
  panic(err)
}

1
2
3
4
5
6
7
var response = client.searchSingleIndex(
  indexName = "ALGOLIA_INDEX_NAME",
  searchParams = SearchParamsObject(
    query = "query",
    userToken = "user-1234",
  ),
)

1
2
3
4
5
6
7
response = client.search_single_index(
    index_name="ALGOLIA_INDEX_NAME",
    search_params={
        "query": "query",
        "userToken": "user-1234",
    },
)

1
2
3
4
5
6
7
8
9
10
11
12
val response = Await.result(
  client.searchSingleIndex(
    indexName = "ALGOLIA_INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        query = Some("query"),
        userToken = Some("user-1234")
      )
    )
  ),
  Duration(100, "sec")
)

1
2
3
4
5
6
7
let response: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "ALGOLIA_INDEX_NAME",
    searchParams: SearchSearchParams.searchSearchParamsObject(SearchSearchParamsObject(
        query: "query",
        userToken: "user-1234"
    ))
)

To set the user token when initializing the API client:

Copy

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

1
2
3
4
5
6
7
8
9
10
11
12
13
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);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
package main

import (
	"fmt"

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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();
  }
}

1
2
3
4
5
6
7
8
import { algoliasearch } from 'algoliasearch';

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import com.algolia.client.api.SearchClient
import com.algolia.client.configuration.*
import com.algolia.client.transport.*
import com.algolia.client.extensions.*

import com.algolia.client.model.search.*

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

1
2
3
4
5
6
7
8
9
<?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();

1
2
3
4
5
6
7
8
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)

1
2
3
4
5
6
7
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)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import Foundation
#if os(Linux) // For linux interop
    import FoundationNetworking
#endif

import Core
import Search

func globalAlgoliaUserID() async throws {
    let configuration = try SearchClientConfiguration(
        appID: "ALGOLIA_APPLICATION_ID",
        apiKey: "ALGOLIA_API_KEY",
        defaultHeaders: ["X-Algolia-UserToken": "test-user-123"]
    )
    let client = SearchClient(configuration: configuration)
    print(client)
}

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

Did you find this page helpful?

Distinguish users for analytics

On this page

Set the user token in InstantSearch and Autocomplete

Set the user token with API clients

On this page