Two lines of code to solve the recommendation black box

Listen to the brief:

Many of us in the ecommerce space have spent more time than we care to admit staring at a "Frequently Bought Together" carousel, wondering if it was actually doing anything. We need real data to make hypotheses and test them, and that’s just not the status quo for AI tools right now.

On a recent roadmap call with our customers and partners, you all asked for Recommendation Analytics to solve this problem, and we’re proud to announce that this feature is now being generally released for Algolia AI Recommendations customers! One of the ways we’ve made search and discovery easy for years is with the Insights API and the analytics dashboard it powers, and now it’s been expanded to include clicks and conversions from recommendations too. And the best part: it only takes two lines of code. Here they are:

clickAnalytics: true

• The context: This is a boolean you drop into your queryParameters.
• The "why": Without this, your recommendation results are just a list of items. By flipping this to true, Algolia attaches a unique queryID to every single item returned in that specific request.
• The result: That queryID is the digital glue that connects a user’s interaction back to the specific recommendation strategy that served it. It’s what allows the dashboard to say "this sale came from the PDP carousel", instead of just "someone bought this item".

sendEvent('click', item, 'Item Clicked')

• The context: This lives inside the item template of your widget. The sendEvent function has always been right there in the template context parameters; we just might need to edit the function definition slightly to make sure it’s available.
• The "why": Just having a queryID isn't enough; you have to actually tell the Insights API when a user does something with that item. By calling sendEvent on a click (or a conversion, if you're further down the funnel), you're sending that data back to Algolia’s servers.
• The result: This closes the loop. It pairs the user’s action with the queryID we generated in the previous step, so we go from "we're showing recommendations" to "we're tracking recommendation revenue".

In a full InstantSearch.js implementation, here’s what those two additions might look like:

// The first ten lines or so are boilerplate InstantSearch setup and imports
import { searchBox, hits, trendingItems } from "instantsearch.js/es/widgets";
import { carousel } from "instantsearch.js/es/templates";
import instantsearch from "instantsearch.js/es";
import { liteClient } from "algoliasearch/lite";

const search = instantsearch({
  indexName: "instant_search",
  searchClient: liteClient("APP_NAME", "API_KEY")
});

search.addWidgets([
  trendingItems({
    container: "#trending-items",
    queryParameters: {
      clickAnalytics: true, // this is the first addition
      // It tells Algolia to send queryIDs with each returned recommendation item
    },
    templates: {
      layout: carousel(),
      item: (item, { html, sendEvent }) => {
        return html`<button
          onclick="${(event) => {
            event.stopPropagation();
            event.preventDefault();

            sendEvent("click", item, "Item Clicked in Carousel"); // this is the second addition
            // It tells Algolia when an item (which contains item.queryID) was clicked or when it caused a sale
            // The final string parameter is our custom name for the event
            // This is being called inside of a button click handler
          }}"
        >
          ${item.name}
        </button>`;
      },
    },
  }),
  // The rest of the boilerplate searchbox and hits window definitions:
  searchBox({
    container: "#searchbox",
  }),
  hits({
    container: "#hits",
    templates: {
      item: (hit, { html, components }) => html`
        <article>
          <h1>${components.Highlight({ hit, attribute: "name" })}</h1>
        </article>
      `,
    },
  }),
]);

search.start();

What the two lines of code actually buy you

For a developer, the only thing that matters for a Friday afternoon deployment is low friction. It should be smooth, predictable, and most of all bug-free. No emergency rollbacks because some third-party analytics suite decided to take 18 seconds to load and ruin the frontend UX. Just a tiny PR and a problem-free deployment.

This is a huge change from the “duct-tape” analytics era where we had to bridge all these third-party tools into our search platform just to see what’s working, and even then, the numbers wouldn’t always line up. Now, you can identify which of your recommendations placements (like on the product page, home page, or cart checkout flow) is actually pulling its weight. Hopefully they’re all contributing, but you’ll have a better picture once the data reveals where your particular segment of shoppers are most willing to be recommended additional products.

The data-driven approach opens up a new strategy comparison pipeline too. Now that we can link clicks on recommendations to real revenue dollar amounts, we can compare which type of recommendation moves the needle more. For example, on the home page, you usually don’t have a reference item yet, so you could compare turning personalization on and off for global trending items. On the product page, showing related products could help users find alternatives when their first choice doesn’t seem to be working out, increasing their potential to buy something at all. But putting related products in the checkout page might make them reconsider what they were about to open their wallets for. Comparing it to Frequently Bought Together and Looking Similar models will give you a better view of what’s working where. The point is that recommendations are context-sensitive, and careful data-driven reasoning increases their verifiable potential to drive sales.

Auditing the AI

At the end of the day, recommendations shouldn’t be a speculative feature you set and forget — they should be a data-driven profit generator. AI is only as useful as your ability to audit it, so while Algolia’s models are already doing the heavy lifting of fine-tuning and ranking, running them without analytics is leaving them to work in a vacuum. Even the best-tuned models need to be viewed in the context of your specific storefront. If you can't measure exactly how a carousel is performing on your unique KPIs, you're missing out on the insights needed to actually scale what works.

If you’re already using Algolia, you should definitely flip the switch — since it’s included and can be activated with a 5-minute PR, there's no reason not to have that data at your fingertips. If you’re just starting to look into how AI can actually move the needle for your store, you can sign up here to try out AI Recommendations and see how those two lines of code look in your own stack.