Send Personalization Events with InstantSearch
On this page
Introduction
InstantSearch allows developers to collect personalization events.
Click and conversion events sent can be used for personalization purposes as well. Some events however can only be used for personalization purposes.
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
10
11
12
13
14
15
<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");
// 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.
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.
Using insights with Node.js
Since version 1.3.0
, you can use search-insights
with NodeJS.
With NPM:
$
npm install search-insights
with Yarn:
$
yarn add search-insights
You can now use require
to import the package in your code.
1
2
const aa = require('search-insights');
// The rest is the same.
Prepare the Events
userToken
By default, InstantSearch sends a default userToken
(a random string) when sending personalization events.
However, if you have to identify a user across different devices, you can send a custom userToken
along with the eventName
, index
and objectIDs
parameters when sending personalization events.
To get the default userToken
provided by InstantSearch, you can call the getUserToken
method on the Insights library.
1
2
3
4
5
6
7
8
9
10
// Starting from v1.3.0 of the search-insights.js library
let userToken = '';
window.aa('getUserToken', null, (err, algoliaUserToken) => {
if (err) {
console.error(err);
return;
}
userToken = algoliaUserToken;
});
objectID
When sending an event, you’ll need to provide the objectID. You can add it to the template of your hits in order to make it easily accessible for future reference by using data-tags, for 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
31
32
33
34
35
36
37
38
search.addWidgets([
instantsearch.widgets.hits({
container: '#hits',
templates: {
item(hit) {
return `
<article>
<h3>
${instantsearch.highlight({
attribute: 'name',
hit,
})}
</h3>
<button
class="button-click"
data-object-id="${hit.objectID}"
>
Details
</button>
<button
class="button-view"
data-object-id="${hit.objectID}"
>
View
</button>
<button
class="button-convert"
data-object-id="${hit.objectID}"
>
Add to cart
</button>
<article>
`;
},
}
})
]);
Sending Click Events
1
2
3
4
5
6
7
8
9
document.addEventListener('click', event => {
if (event.target.matches('.button-click')) {
aa('clickedObjectIDs', {
eventName: 'CLICK_HIT',
index: 'INDEX_NAME',
objectIDs: [event.target.getAttribute('data-object-id')]
});
}
});
Sending Conversion Events
1
2
3
4
5
6
7
8
9
document.addEventListener('click', event => {
if (event.target.matches('.button-convert')) {
aa('convertedObjectIDs', {
eventName: 'CONVERT_HIT',
index: 'INDEX_NAME',
objectIDs: [event.target.getAttribute('data-object-id')]
});
}
});
Sending View Events
1
2
3
4
5
6
7
8
9
document.addEventListener('click', event => {
if (event.target.matches('.button-view')) {
aa('viewedObjectIDs', {
eventName: 'VIEW_HIT',
index: 'INDEX_NAME',
objectIDs: [event.target.getAttribute('data-object-id')]
});
}
});