Guides / Personalization / Advanced Personalization / Configure personalization / Prerequisites

Apr 30, 2025

Prepare your search implementation

Attach user tokens to queries

To ensure that the Advanced Personalization feature can understand each user’s journey and continuously improve their personalization experience, attach a user token to each query. The user tokens attached to the queries must match the user tokens sent with events.

This feature isn’t available on every plan. Refer to your pricing plan to see if it’s included.

Attach user tokens with InstantSearch

To include the userToken in your search queries using InstantSearch, use the configure widget to set the userToken search parameter.

Copy

1
2
3
instantsearch.widgets.configure({
  userToken: 'user-1234',
});

1
2
3
4
5
final hitsSearcher = HitsSearcher.create(
  applicationID: 'YourApplicationID',
  apiKey: 'YourSearchOnlyApiKey',
  state: const SearchState(userToken: 'user-1234'),
);

Attach user tokens with an API client

To include the userToken in your search queries with an API client, use the search method to send the userToken search parameter.

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

Persist user tokens

For user profiles to be found and retrieved at search time, you should persist anonymous user tokens and authenticated user tokens across sessions.

Avoid enabling personalization at query time

Rather than using the enablePersonalization search parameter at query time, set it in the index settings when moving to production. This lets you A/B test the impact of personalization without having to modify code.

Next step

Now that you’ve prepared your index structure, event implementation and search implementation, Advanced Personalization can build a holistic view of each user’s journey and personalize search results accordingly.

You’re ready to configure Advanced Personalization indices without additional code changes.

Prepare your event implementation

Consider requirements and limits

Did you find this page helpful?