Set up Algolia Recommend

Recommending items to your users involves these steps:

1. Prepare your data
2. Select and train the Recommend models
3. Show recommendations in your user interface

Prepare your data

Your data is the foundation of the recommendations. Your Algolia index is the source of the recommendations, and events indicate which recommendations are most relevant.

Collect click and conversion events for Algolia Recommend

To collect enough events for Algolia Recommend, check that you send these different events to Algolia:

• Events related to Algolia—for example, on search results, and category pages
• Events unrelated to Algolia—for example, product-detail pages, checkout pages

To speed up the collection of events, you can upload past events with a CSV file.

If you collect enough events but still get an error that prevents you from starting the training:

• Check the Events debugger in the Algolia dashboard for error messages.

• Check that you set up the userToken correctly. Make sure you’re not using the same userToken for all users.

  For authenticated users, use the user ID as their userToken for Algolia. For non-authenticated users, set the userToken to a session-based ID. You can generate a random ID for each session and discard it once the session ends.

Train the Recommend models

If you have enough events, you can start training the Recommend models.

1. Go to the Algolia dashboard and select your Algolia application.

2. On the left sidebar, select Recommend.

3. On the Recommend page, select the type of recommendations you want to generate and click Start using.

   

4. In the Select data source section, select an index you want to use as a source for recommendations. By default, events associated with your data source index are used to train the model.

   

5. Optional: add more sources for user events. Select additional indices or replicas from your app, or upload a CSV file.

   

6. Optional for Related Products: define key attributes for content-based filtering.

   

   Content-based filtering works best with attributes that contain textual information, such as the title or description.

   For more information, see content-based filtering.

7. Optional for Trends: select which type of trend you want to use for recommendations.

   

   • Trending items. Generate recommendations from popular items in your product catalog. After selecting Trending items, you can select Also enable trending items per facet values to get trending items per facet value.
   • Trending facet values. Generate recommendations for popular facet values.

8. Click Start training. Training a model can take up to two hours.

9. When the training finishes, you can see a summary:

   

You can use more than one model to generate recommendations, and select the best recommendations for your use case.

Models are re-trained every day.

Preview the recommendations

Once the model is trained, you can preview its recommendations by searching for items in your index. Each recommendation displays a confidence score from the model, ranging from 0 to 100. The closer the score is to 100, the more relevant the recommendations are.

Integrate Recommend into your user interface

To show recommendations in your app, you have the following options:

• React. Use React InstantSearch.
• Other JavaScript frontends. Use InstantSearch.js.
• Native app or backend implementation. Use the Recommend API client or the Recommend API.

Show recommendations in your user interface

To show recommendations in your user interface, follow these steps:

With InstantSearch.js

1. Install and set up InstantSearch.js.
2. Add a container element for your recommendations to your HTML.
3. Add the widget for the Recommend model. You can also declare how each recommendation renders by providing an item template.

The following example adds recommendations from the Related Products model to an HTML element with the ID relatedProducts:

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
import algoliasearch from 'algoliasearch/lite';
import instantsearch from 'instantsearch.js';
import { relatedProducts } from 'instantsearch.js/es/widgets';

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

const search = instantsearch({
  indexName: 'instant_search',
  searchClient,
});

search.addWidgets(
  relatedProducts({
    container: '#relatedProducts',
    objectIDs: ['YOUR_PRODUCT_OBJECT_ID'],
    templates: {
      item(recommendation, { html }) {
        return html`
          <h2>${recommendation.name}</h2>
          <p>${recommendation.description}</p>
        `;
      },
    },
  });
);

search.start();

With React InstantSearch

1. Install and set up React InstantSearch.
2. Add the widget for the Recommend model. You can also declare how each recommendation renders by providing an itemComponent component.

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
import React from 'react';
import algoliasearch from 'algoliasearch/lite';
import { InstantSearch, RelatedProducts } from 'react-instantsearch';

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

function App() {
  return (
    <InstantSearch searchClient={searchClient} indexName="instant_search">
      <RelatedProducts
        objectIDs={['YOUR_PRODUCT_OBJECT_ID']}
        itemComponent={Item}
      />
    </InstantSearch>
  );
}

function Item({ item }) {
  return (
    <>
      <h2>{item.name}</h2>
      <p>{item.description}</p>
    </>
  );
}

For more information, see the InstantSearch documentation.

Refine your recommendations

Often, you want to refine your recommendations—for example, to only recommend in-stock products or to ensure all recommendations are from the same product category.

To refine your recommendations, pass facetFilters to the component by using queryParameters.

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

1
2
3
4
5
6
7
8
9
<RelatedProducts
  // ...
  queryParameters={{
    facetFilters: [
      `category:${selectedProduct.category}`,
      `inStock:true`,
    ],
  }}
/>

To refine the recommendations by numeric values—for example, a price range, use numericFilters.

You can also apply Rules to your recommendations for further refinement or manual curation.

Adjust the number of displayed recommendations

By default, Algolia Recommend shows up to:

• 3 recommendations for Frequently Bought Together
• 30 recommendations for other models

You can adjust this number by using the limit attribute.

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

1
2
3
4
<RelatedProducts
  // ...
  limit={5}
/>

Show fallback recommendations for Related Products or Related Content

Sometimes, Algolia Recommend can’t generate enough recommendations from the model. For Related Products and Related Content models, you can show fallback recommendations from your data source index instead.

To show fallback recommendations, pass the facetFilters parameter to fallbackParameters.

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

1
2
3
4
5
6
7
8
9
<RelatedProducts
  // ...
  fallbackParameters={{
    facetFilters: [
      `category:${selectedProduct.category}`,
      `inStock:true`,
    ],
  }}
/>

To pass numeric filters, use the numericFilters parameter.

To increase the number of recommendations and coverage of your Related Products model, consider using content-based filtering when training the model.

The Frequently Bought Together model only makes sense for items that are actually bought together. That’s why there are no fallback recommendations.