Guides / Getting insights and analytics / Search analytics / Click-through and conversion analytics

Send Click and Conversion Events with InstantSearch.js

On this page

Requirements

Install the Search-Insights Library

To make use of analytics, the search-insights library has to be added to your application.

The Insights library can either be loaded via jsDelivr CDN or from your own static fileserver. If you choose the latter, you have to update the ALGOLIA_INSIGHTS_SRC variable to point to the URL of the file on your own fileserver. We recommend loading the library by adding this snippet in the <head> of your HTML file.

Copy 
1
2
3
4
5
6
7
8
9

<script>
  var ALGOLIA_INSIGHTS_SRC = "https://cdn.jsdelivr.net/npm/search-insights@1.6.3";

  !function(e,a,t,n,s,i,c){e.AlgoliaAnalyticsObject=s,e[s]=e[s]||function(){
  (e[s].queue=e[s].queue||[]).push(arguments)},i=a.createElement(t),c=a.getElementsByTagName(t)[0],
  i.async=1,i.src=n,c.parentNode.insertBefore(i,c)
  }(window,document,"script",ALGOLIA_INSIGHTS_SRC,"aa");

</script>

jsDelivr is a third-party CDN. We are not able to provide support regarding third party services.

If you’re using a module bundler (Webpack, Parcel, etc.), you can import the library like the following:

Copy 
1

import aa from 'search-insights';

Create the insights middleware

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

const insightsMiddleware = instantsearch.middlewares.createInsightsMiddleware({
  insightsClient: window.aa,
});

// or

import {
  createInsightsMiddleware,
} from 'instantsearch.js/es/middlewares';

const insightsMiddleware = createInsightsMiddleware({
  insightsClient: aa,
});

Connect InstantSearch with the insights middleware

Copy 
1
2
3
4
5
6

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

search.use(insightsMiddleware);

Whenever sending an event to Algolia, you need to include the queryID of the most recent search.

By default, the search response doesn’t contain a queryID. To retrieve it, the clickAnalytics parameter must be true, which the insights middleware handles for you.

Set the userToken

By default, we set an anonymous token and store it in cookie. However, we highly recommend setting the userToken yourself to reliably identify users (e.g., an internal identifier for logged-in users).

Copy 
1

aa('setUserToken', yourUserToken);

If you don’t have access to that information right away, you can set it later from your code. The insights middleware ensures to pass the token in every subsequent search call as soon as you set it.

Default events

When using any of the following connectors, the insights middleware automatically sends default events whenever facets are added or hits are rendered.

Refinements

These connectors send click events whenever a facet is added. If you customize a widget using connectors, it will send events too. You can disable this behavior or modify the default payload.

Results

These connectors send view events whenever hits are rendered. If you customize a widget using connectors, it will send events too. You can disable this behavior or modify the default payload.

In addition, hits and infiniteHits expose a bindEvent function, so that you can hook user actions to custom events (click or conversion) at the template level.

Hook a user action to an Insights event

In most cases you’ll want to send events when the user interacts with search results. This implies you’ll want to send the events from either the hits or the infiniteHits widget.

In this example we set up the hits widget.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

search.addWidget(
  instantsearch.widgets.hits({
    container: '#hits',
    templates: {
      item(hit, bindEvent) {
        return `
            <article>
              <h3> ${instantsearch.highlight({ attribute: 'name', hit })} </h3>
            </article>
          `;
      }
    }
  })
);

Now for the payoff, sending the event. The item template exposes a bindEvent function which returns a data attribute on clickable items.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<button
  type="button"
  ${bindEvent('click', hit, 'Product Added')}
>
  Add to cart
  <!-- this button will send a click event when user clicks -->
</button>

<button
  type="button"
  ${bindEvent('conversion', hit, 'Product Ordered')}
>
  Order
  <!-- this button will send a conversion event when user clicks -->
</button>

Insights events (click, conversion, view) used for analytics and/or personalization do not take immediate effect. The delay can range from 10 to 60 minutes depending on how long after the search they are sent. For precise times, see our page on when Insights events take effect.

Based on the type of event you send, you need different data. For example, a conversion event does not need the position attribute, but the click event does, because position determines the average click position. Thanks to the integration with InstantSearch, this is all handled for you: InstantSearch will inject all the necessary data based on the event we send and the context of the current query.

If you’re sending these events with our Personalization feature, it’s important to decide which events to send, and when to send them. Please read our guide if you’re unsure about how event-sending works.

When sending a conversion event, you’re not always on the search page (such as a product detail page). Therefore, you need to pass the queryID to the detail page.

How To Keeping Track of the Query ID for Conversion Events

Full example

Copy 
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

search.addWidget(
  instantsearch.widgets.hits({
    container: '#hits',
    templates: {
      item(hit, bindEvent) {
        return `
            <article>
              <h3>
                ${instantsearch.highlight({ attribute: 'name', hit })}
              </h3>

              <button
                type="button"
                ${bindEvent('click', hit, 'Product Added')}
              >
                Add to cart
              </button>
              
              <button
                type="button"
                ${bindEvent('conversion', hit, 'Product Ordered')}
              >
                Order
              </button>
            <article>
          `;
      }
    }
  })
);

Advanced

The insights middleware lets you disable default events, modify the default event payloads, send events from your own custom widgets, and send events to third-party trackers. Please check the insights documentation to learn how to do so.

Did you find this page helpful?

InstantSearch.js v4