Guides / Algolia AI

If you’ve used Recommend in beta, please see the migration guide. The docs for the Recommend beta version are deprecated. The beta infrastructure will run until August 30, 2021.

Only customers on the latest plans can access Algolia Recommend.

Algolia Recommend lets you display recommendations on your website to encourage your users to expand their search and browse more broadly. If the item they’re looking at isn’t what they were searching for they can quickly jump to similar items or find items that would complement their current selection.

Algolia Recommend offers two recommendation models:

  • Frequently Bought Together
  • Related Products

Algolia Recommend generates recommendations by looking at:

  • Your data indexed into Algolia
  • Your users’ interactions captured through the Insights API

Frequently Bought Together

Frequently Bought Together recommends items that are often bought together. For a given item, it recommends a list of items based on the conversion events your users perform on your platform.

The Frequently Bought Together model recommends up to 3 items.

Related Products recommends items that are related to each others. For a given item, it returns a list of items based on the clicks and conversion events your users perform on your platform.

The Related Product model recommends up to 30 related items.

How it works

Under the hood recommendations rely on supervised machine learning models and the Algolia foundation.

For both models, the data corresponding to the past 30 days is collected. This results in a matrix where columns are userTokens and rows are objectIDs. Each cell represents the number of interactions (click and/or conversions) between a userToken and an objectID. Then, Algolia Recommend applies a collaborative filtering algorithm: for each item, it finds other items that share similar buying patterns across customers. Items would be considered similar if the same users set interacted with them. Items would be considered bought together if the same set of users bought them.

Getting started

Getting recommendations is a four-step process:

  1. Sending your data
  2. Capturing your users events
  3. Training the models
  4. Building your recommendation UI

Sending your data

Before you can get recommendations, you need to send your data to Algolia. Algolia provides recommendations based on the data in your index, which Algolia hosts on its servers.

If you didn’t send your data to Algolia yet, there’re a full section you can follow to do so.

Capturing your users events

There are two families of user events you can capture with the Insights API:

  • Events that happened following an interaction with Algolia results
  • Events that happened following an interaction unrelated to Algolia results

Events can have the following types:

  • Clicks
  • Conversions

Algolia Recommend models use both types of events. You can follow the guide explaining how to send users events to Algolia to help you set it up on your platform.

Training the models

The first thing you have to choose is which models you are interested in. Using both Frequently Bought Together and Related Products at the same time is also possible.

Recommendations are refreshed every 24 hours and use your users’ interactions from the last 30 days.

The setup process is the same for all models.

Select data source

You need to specify the main index containing the items you want to generate recommendations for. You can also add replicas to include additional events in the same model.

Collect Insights events

The underlying models use the events made on the index specified on the “select data source” step.

  • Frequently Bought Together requires at least 1,000 conversions with two or more items within the last 30 days. Conversions with at least two objectIDs come from looking at the list of objectIDs in a single event, then grouping events from the same userToken and date together.
  • Related Products requires at least 10,000 clicks or conversions within in the last 30 days.

If the minimum number of Insights API events sent to the selected index isn’t reached, an error message is displayed and the model training can’t start.

If you’re getting such an error despite sending enough events:

  1. Check out the guide explaining how to validate and debug events.
  2. Take a look at your userToken implementation and make sure you’re not setting the same value for all users.
    • For authenticated users, use the ID of the user as their userToken.
    • For non-authenticated users, set the userToken to a session-level ID. You can generate such an ID randomly and discard it once the session ends.

Machine learning models

Once the previous steps are done you can click on the Start training button to start generating the recommendations.

This step can take several hours, usually around 1 to 2 hours.

Once completed, you are able to know:

  • The number of items for which the model generated recommendations
  • The coverage: the percentage of recommended items over the full catalog

Preview

Once the model is trained you can preview its recommendations by searching any items from your index.

Each recommendation displays the confidence score from the model. This score goes from 0 to 100. The closer it’s to 100, the more relevant.

The preview module in the Recommend dashboard page

You’re done with the setup of Algolia Recommend. Now it’s time to display them on your site.

Building your recommendation UI

Algolia Recommend comes with a Recommend UI library that packages ready to use widgets for JavaScript and React. This is the fastest, most straightforward way to get Algolia Recommend up and running on your site.

To integrate Algolia Recommend in a non-JavaScript front end (like native mobile), or using back-end search, you can either use the Algolia Recommend client or the Recommend REST API directly.

Getting started with the Recommend library

When using the Recommend library, adding recommendations to your site only takes a few lines of code.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import { relatedProducts } from '@algolia/recommend-js';
import algoliarecommend from '@algolia/recommend';
import { itemComponent } from './itemComponent';

const recommendClient = algoliarecommend(
  YourApplicationID,
  YourSearchOnlyAPIKey
);

relatedProducts({
  container: '#relatedProducts',
  recommendClient,
  indexName: 'YourIndexName',
  objectIDs: ['YOUR_PRODUCT_OBJECT_ID'],
  itemComponent,
});

Refine your recommendations by passing filters

It can be useful to pass some filters to the recommendations. For instance, you might want to ensure never to recommend any out of stock products, or that all recommendations belong to the same category.

To do so, you can pass facetFilters to the component via queryParameters.

1
2
3
4
5
6
7
8
9
relatedProducts({
  // ...
  queryParameters: {
    facetFilters: [
      `category:${selectedProduct.category}`,
      `inStock:${selectedProduct.inStock}`,
    ],
  },
});

Similarly, you can use the numericFilters parameter, for example if you want to filter on a price range.

Choose how many recommendations to display

If the Algolia Recommend models have enough user data to work with for a given product, they produce a maximum of:

  • 3 recommendations for Frequently Bought Together
  • 30 recommendations for Related Products

By default, they return up to this amount of recommendations. You can change this number to suit your needs by using the maxRecommendations attribute.

1
2
3
4
relatedProducts({
  // ...
  maxRecommendations: 5,
});

Displaying fallback recommendations

When they don’t have enough user events, the Algolia Recommend models might not be able to compute any or enough recommendations. In such cases, you can decide to fall back on content-based recommendations, leveraging your Algolia index. You can do this using the facetFilters parameter in fallbackParameters.

1
2
3
4
5
6
7
8
9
relatedProducts({
  // ...
  fallbackParameters: {
    facetFilters: [
      `category:${selectedProduct.category}`,
      `inStock:${selectedProduct.inStock}`,
    ],
  },
});

As with queryParameters, you can use the numericFilters parameter in fallbackParameters.

Migrating from beta

Storage and format

For the beta, recommendations live in an Algolia index with the following naming convention: ai_recommend_${modelName}_${indexName}.

For example:

  • ai_recommend_bought-together_mysourceindex
  • ai_recommend_related-products_mysourceindex

Since June 30, 2021, Algolia Recommend is generally available and recommendations are stored directly in the engine. You can retrieve them via the Recommend endpoint or the UI libraries.

Make sure to accept terms and conditions before August 30, 2021. After this date, beta indices won’t receive any updates. Once you completed the migration you can delete those indices.

Updating your UI

If you’ve used the Recommendations React component in the beta, please visit the upgrade guide for detailed instructions.

If you’ve developed a custom component, please refer to the Recommend endpoint and returned response to update your UI accordingly.

Did you find this page helpful?