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

Send Click and Conversion Events with InstantSearch.js

On this page

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
10
11
12
13
14
15

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

  !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");


  // Initialize library
  aa('init', {
    appId: 'YourApplicationID',
    apiKey: 'YourSearchOnlyAPIKey'
  });
</script>

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

Connect InstantSearch with the Insights client for JavaScript

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

const search = instantsearch({
  searchClient,
  indexName: 'INDEX_NAME',
  insightsClient: window.aa,
});

search.addWidgets([
  instantsearch.widgets.configure({
    clickAnalytics: true,
  }),
]);

When sending an event to Algolia, you need to include the queryID of the most recent search. However, by default, the search response does not contain a queryID. Therefore, to retrieve it, the custom search parameter clickAnalytics must be set to true and needs to be added when instantiating the search.

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) {
        return `
            <article>
              <h3> ${instantsearch.highlight({ attribute: 'name', hit })} </h3>
            </article>
          `;
      }
    }
  })
);

Now for the payoff, sending the event. InstantSearch exposes a function insights which you can use in the following way.

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

<button
  ${instantsearch.insights('clickedObjectIDsAfterSearch', {
    eventName: 'Details',
    objectIDs: [hit.objectID]
  })}
  >
  Details
  <!-- this button will send a click event when user clicks -->
</button>

<button
  ${instantsearch.insights('convertedObjectIDsAfterSearch', {
    eventName: 'Add to cart',
    objectIDs: [hit.objectID]
  })}
>
    Add to cart
    <!-- 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
31
32
33
34

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

              <button
                ${instantsearch.insights('clickedObjectIDsAfterSearch', {
                  eventName: 'Details',
                  objectIDs: [hit.objectID]
                })}
              >
                Details
              </button>

              <button
                ${instantsearch.insights('convertedObjectIDsAfterSearch', {
                  eventName: 'Add to cart',
                  objectIDs: [hit.objectID]
                })}
              >
                Add to cart
              </button>
            <article>
          `;
      }
    }
  })
);

Did you find this page helpful?

InstantSearch.js v4