Send Click and Conversion Events with InstantSearch.js
On this page
Requirements
- Use search-insights v1.6.2 or later.
- Use InstantSearch.js v4.8.3 or later.
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.
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:
1
import aa from 'search-insights';
Create the insights
middleware
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
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).
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
connectHierarchicalMenu
:hierarchicalMenu
connectMenu
:menu
andmenuSelect
connectNumericMenu
:numericMenu
connectRange
:rangeInput
andrangeSlider
connectRatingMenu
:ratingMenu
connectRefinementList
:refinementList
connectToggleRefinement
:toggleRefinement
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
connectAutocomplete
:autocomplete
connectGeoSearch
:geoSearch
connectHits
:hits
connectInfiniteHits
:infiniteHits
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.
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.
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 (view, click, and conversion) don’t take immediate effect. The delay can range from a few minutes to an hour, depending on whether they are sent after a search or not, and how long after a search they are sent. For precise timeframes, 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.
Full example
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.