07 Dec 2018



The personalization feature is not yet released and will be accessible on the 18th of December and will be available for all customers on the Enterprise plan.

Personalization - A 2-Minute Video

General and User-Based Relevance

Personalization is significant to any conversational search, as it adds a personal layer to the overall relevance experience. By integrating analytics-based user preferences into the query experience, you expand the possibilities of search. Personalized search is an essential addition to Algolia’s full set of relevance tools, which include proper indexing, custom ranking, analytics, and merchandising with query rules.

Relevance has two goals

Effective relevance benefits you in two ways: first, it enables your end users to see products and services that match their expectations; and second, it provides results that align with your business needs. These twin goals are accomplished with a well-structured and smartly configured index. This happens all before you personalize results. Your initial focus is on all users, not individual ones. You want to make sure that the same search on the same index always returns the same results.

But we also know that users greatly benefit from seeing individualized results. Queries mean different things for different people. For example, a user who searches for “harry”, and has a preference for children’s literature, will want to see “Harry Potter” appear on the first page. Political journalists, however, will be more interested in seeing “Harry Truman” instead of “Harry Potter” in their results.

It benefits you as well. Personalization encourages people to stay longer on your website, leads to more discovery and item views, and potentially generates more sales.

Introducing Personalization

Algolia’s Personalization feature introduces user-based relevance, an additional layer on top of Algolia’s relevance strategy. First, there is textual relevance - an intelligent and robust textual matching mechanism that includes typo tolerance, synonyms, filtering, and a host of other settings; second, business relevance - a business-centric relevance that ranks results according to your business metrics; and third, merchandising - promoting specific items, and displaying banners and top results. All of these contribute, in different ways, to producing relevant results that apply equally to everybody. Personalization - and more broadly Algolia’s Insights & Analytics - adds a fourth layer by injecting user preferences into the relevance formula.

Three Steps to Take

All three steps are of equal importance. They are summarized here. We go into more detail in the following section.

1. Gather user events

Personalization starts with gathering data about your user’s actions. You can send us any type of events that you think are relevant for Personalization. For example, you can send an event when the user clicks on a product, bookmarks, likes, visits a category page, adds something to their cart, watches a video, reads an article, etc.

To gather data, you’ll need to add single-line snippets of code to different parts of your front end. This gives Algolia the user-based information it needs to construct user preferences. Algolia needs to know what actions your users take, and which products they take these actions on.

Read more on gathering user events

2. Build a list of preferences for each user

You can use the dashboard to define how the user events should be interpreted. There, you create distinct scores for each type of user action, making some actions more important than others (for example, purchasing a product is a stronger signal than liking it). As you’ll see, this comparative scoring forms the basis of determining user preferences.

Read more on building a list of preferences for each user

3. Activate the user preferences at query time

Here we come to the main objective: to have user preferences directly impact the finding and ranking of personally relevant results. This can be done for each query, and requires the least amount of effort on your part. All you need is to tell Algolia whether or not to apply the current user’s preferences. You can set it on and off for each individual search.

Read more on activating the user preferences at query time

Step 1 - Gathering User Events Through Insights

The first step is to gather the events and actions from your users. This is done using Algolia’s Insights API. Personalization relies on the Insights API event capturing mechanism, which allows you to track events that will eventually form the basis of every profile.

As soon as the Personalization feature is released, you will be able to use our Search Insights with our web, Android, and iOS libraries, to push those events as well.

There are 2 kinds of events:

Capturing actions on an item

Action-based events include bookmarking an item, viewing a product page, putting a product on a wish list or shopping cart, buying a product, reading an article, and many other events that you consider useful in defining user preferences. For this to work, you need to make sure that these events are captured every time they occur.

To capture an event, you need to add code to your front end that sends the following information:

You can send events related not only to a particular item but to a group of items, identified by a filter. For this, you send the filter along with its associated action. For example, if a user visits the category page “Electronics” of an e-commerce website, it could be interesting to capture this as a filter event, to boost this category as an insight.

Here’s what you need to send:

Note: For this to work, the filter has to be set up as an attribute for faceting.

To conclude, you should send user actions that you consider relevant to building an understanding of your user’s preferences. These events can be either their interactions with the items in your index, or with a group of items identified by a filter.

Examples of events worth tracking


  • A user viewed a product page
  • A user viewed a landing page of all Apple products

Clicks (queryID is optional)

  • A user clicked on a item on the home page
  • A user clicked on a item on a category page
  • A user clicked on a item on a newsletter email
  • A user clicked on a search result
  • A user clicked on a filter as they search
  • A user clicked on a menu item related to a filter

Conversions (queryID is optional)

  • A user bookmarked, or liked, or recommended an object
  • A user added to cart, or purchased an item
  • A user watched a video, read an article
  • A user followed a playlist, an author, a brand

List of objects

Also, each of the events related to an object also accepts a list of objects. For example, it is possible to send a “purchase” event containing the list of objects that were purchased together.

Step 2 - Scoring Events, Building User Preferences

In the first step, you should have collected a comprehensive list of actions to build an understanding of each user. This is what allows you to personalize their search results.

Via the Dashboard

This step is usually done using Algolia’s Dashboard. It can also be done via the API. Thus, coding is not required. It’s up to you to decide.

Let’s say you’ve set up 2 events - liking a product and buying a product - and you have a large amount of instances of these events. Now you’ll be able to configure how these events should be interpreted, and how they will influence the personalization strategy. The Dashboard lets you rate the importance of each of these events. For example, you can make “liking a product” 10 times more important than “buying a product”. Or vice-versa.

Recall what you’re doing here. You’re trying to create a profile that reflects, in the most accurate way possible, a user’s preferences. So you first choose the action and then gather relevant events that best capture these preferences. Next, you want to score each event in a way that most accurately measures preferences. You ask yourself, What is more indicative of preference - buying or liking a product?

Configuring the importance of each event

You use the Dashboard to score individual events. You score each event in reference to their importance. If you score “liking” at 10 and “buying” at 90, you’ve just told Algolia that “buying” is 9 times more indicative of preference than “liking”. If you do the math, that would mean that a user who likes 9 Apple phones and purchases 1 Samsung phone would be seen - in this example - as having the same level of preference for Apple and Samsung.

Note: On the Dashboard’s Personalization screen, there are two main sections: one for events, and the other for filters.

Configuring the importance of each facet attribute

After having configured the importance of each event, you now need to configure the importance of each facet attribute of your objects. For example, let’s say that a users buys a “red iPhone”, what does it imply about its preferences? Is this user likely to buy another product from Apple? Probably, so you should give a high coefficient to the attribute brand. Is this user likely to buy another product of color red? Probably not, so you should give a low coefficient to the attribute color.

FYI: There is a second way your facets get included in user profiles. But for this, you don’t need to do anything. It’s done automatically whenever you send a product. When Algolia receives an event with a product ID, it not only saves the user, event, and product, it also saves all of the product’s facet filters.

Step 3 - Enabling Profiles at Query Time

Now you are ready to enable these profiles and personalize the search results based on a user’s preferences. You do this by adding two pieces of information to your query request:

  • a single true/false flag (using the setting enablePersonalization)
  • the user token that you used when capturing the events for the current user

When you set personalization to true, user preferences are taken into account. When false, the query runs as before, with no user preferences.

You can enable profiles right away, or wait until you get enough data. You can test them out on some users before applying them more globally. You can also have a selective implementation and only enable personalization in some predefined scenarios or for only some categories of users.

In other words, you control the application of personalization at query time. Note that even if you have not enabled the profiles, and therefore are not taking into account user preferences, the data gathering and scoring continue in the background.

Technical Specs

What follows is a summary of the personalization parameters. The full technical documentation can be found in our Personalization Rest API reference page.

Unique user identifier

It can be any kind of userToken, for example a user ID that you manage on your back end, or the user’s HTTP request IP.

Event type

The eventType helps categorize your events. Events fall into three categories: View, Click, and Conversion. See explanation and examples above.

Event name

The eventName can be a name of your choosing. See examples above.

The record’s objectID

The objectID of the item in your index that you wish to associate with the event.

The search’s queryID

The queryID is the ID of the currently active query.

Filters you consider relevant

The filters parameter is the exact name of the attribute that you use for filtering and faceting.


The boolean flag used during query time to allow user preferences to be used as part of the relevance and ranking process. When flagged as true, user preferences are taken into account, when false, user preferences are ignored.

Example Use Cases

Let’s see two basic examples to illustrate how it works.

Example 1: Movies added to watch list

On a website like Netflix, you can add movies to your watch list. Movies in your watch list are movies that you want to see later. Let’s say for example that you’ve added the movie Ocean’s Thirteen to your watch list. If later you search for Ocean, it will make sense to have this specific movie show up at the top of the result list.

To implement this, you need to:

  1. Every time someone adds something to their watch list, send us the following event:
    • userID: The user identifier
    • eventType: “Favorite”
    • eventName: “Add to watch list”
    • objectID: The movie identifier
  2. Configure a high score for the event “Add to watch list”, and a low score for every other event

  3. Send us the userID of the user when making a search

  4. That’s it! Movies added to a user’s watch list will now be ranked higher in their search results.

Example 2: Recurring purchases on a fashion e-commerce website

On a website like Asos, where users return to shop often, it makes sense to showcase the type of products that corresponds to their usual taste.

To implement this, you need to:

  1. Every time someone makes a purchase, send us the following event:
    • userID: The user identifier
    • eventType: “Conversion”
    • eventName: “Purchase”
    • objectID: The movie identifier
  2. Configure a high score for the event “Purchase”, and a low score for every other event

  3. Configure a high score for all characteristics of products that are relevant to find related items (brand, tags, size, etc.), and a low score for the others (price, color, etc.)

  4. Send us the userID of the user when making a search

  5. That’s it!
© Algolia - Privacy Policy