Enabling Personalization

To give your users with a personalized experience, you need to include the enablePersonalization and userToken parameters in your search requests. How you do this depends on your Algolia implementation and whether you use InstantSearch.

You can also set enablePersonalization in your index settings instead of sending it as a search parameter. This way, every search on your index uses Personalization, unless you override this at query time by setting the enablePersonalization parameter to false.

If you set enablePersonalization as an index setting, you still need to include a user’s userToken in your search requests. If you don’t include the userToken, Algolia doesn’t know which user affinity profile to apply to personalize the results.

Enabling Personalization with InstantSearch

If you are using InstantSearch, it’s best to enable Personalization by using the configure widget. The configure widget lets you provide raw search parameters to the Algolia API without rendering anything.

Using the configure widget, you can set the enablePersonalization to true and include the userToken. The userToken should match the one you’re using to send click and conversion events for a particular user.

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

1
2
searcher.request.query.enablePersonalization = true
searcher.request.query.userToken = 'user-1234'

1
2
3
<ais-configure
  [searchParameters]="{ enablePersonalization: true, userToken: 'user-1234' }"
></ais-configure>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<template>
  <ais-instant-search
    index-name="instant_search"
    :search-client="searchClient"
  >
    <ais-configure :clickAnalytics="true" userToken="user-1234" />
  </ais-instant-search>
</template>

<script>
  import algoliasearch from 'algoliasearch/lite';

  export default {
    data() {
      return {
        searchClient: algoliasearch(
          'YourApplicationID',
          'YourWriteAPIKey'
        ),
      };
    },
  };
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import algoliasearch from 'algoliasearch/lite';
import { InstantSearch } from 'react-instantsearch-dom';

const searchClient = algoliasearch(
  'YourApplicationID',
  'YourWriteAPIKey'
);

const App = () => (
  <InstantSearch
    indexName="instant_search"
    searchClient={searchClient}
  >
    <Configure enablePersonalization={true} userToken="user-1234" />
  </InstantSearch>
);

1
2
searcher.query.query.enablePersonalization = true
searcher.query.userToken = 'user-1234'

Enabling Personalization using API clients

If you’re using one of the API clients to make search requests, you can include enablePersonalization and userToken as parameters in the search method. The userToken should match the one you’re using to send events for a particular user.

1
2
3
4
$index->search('query', [
  'enablePersonalization' => true,
  'userToken' => '123456'
]);

1
index.search('query', { enablePersonalization: true, userToken: '123456' })

1
2
3
4
5
6
index.search('query', {
  enablePersonalization: true,
  userToken: '123456'
}).then(({ hits }) => {
  console.log(hits);
});

1
index.search('query', {'enablePersonalization': True, 'userToken': '123456'});

1
2
3
4
5
6
7
8
9
let query = Query("query")
  .set(\.enablePersonalization, to: true)
  .set(\.userToken, to: "123456")

index.search(query: query) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
Query query = new Query("query");
query.EnablePersonalization = true;
query.UserToken = "123456";

1
2
3
Query query = new Query("query")
.setUserToken("123456")
.setEnablePersonalization(true);

1
2
3
4
5
res, err := index.Search(
  "query",
  opt.EnablePersonalization(true),
  opt.UserToken("123456"),
)

1
2
3
4
5
6
7
client.execute {
  search into "myIndex" query Query(
    query = Some("query"),
    enablePersonalization = Some(true),
    userToken = Some("123456")
  )
}

Enabling Personalization using the dashboard

You can set enablePersonalization as an index setting for the indices you want to personalize results for. This setting automatically sets enablePersonalization:true for any search requests made on this index. If you want to turn Personalization off at query time for some reason, you can include enablePersonalization:false on those search requests.

Go to Indices section of the dashboard and navigate to Configuration » Relevance Essentials » Personalization for each index you want to enable Personalization on. Here, you can set enablePersonalization to true.

Remember that unless you include a valid userToken, the engine can’t personalize results. Even if you enable Personalization on the dashboard, you still need to provide the userToken using either InstantSearch or an API Client.

That’s why you don’t automatically see personalized results if you are testing queries in the Browse section of an index where you’ve enabled enablePersonalization as an index setting. While you can add the userToken by selecting +Add Query Parameter, it’s best to simulate Personalization using the dedicated Personalization simulator. The simulator lets you compare personalized and non-personalized results and provides information to explain how Personalization affected the results.