Search Insights lets you report click, conversion and view metrics using the Algolia Insights API.
Are you using Google Tag Manager in your app? We provide a custom template to ease the integration.
The Search Insights library can be either loaded via jsDelivr CDN or directly bundled with your application. We recommend loading the library by adding the snippet below to all pages where you wish to track search analytics.
<script>
var ALGOLIA_INSIGHTS_SRC = "https://cdn.jsdelivr.net/npm/[email protected]";
!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>
aa('init', {
appId: 'APP_ID',
apiKey: 'SEARCH_API_KEY',
});
// Optional: set the analytics user ID
aa('setUserToken', 'USER_ID');
Option | Type | Default | Description |
---|---|---|---|
appId |
string |
None (required) | The identifier of your Algolia application |
apiKey |
string |
None (required) | The search API key of your Algolia application |
userHasOptedOut |
boolean |
false |
Whether to exclude users from analytics |
region |
'de' | 'us' |
Automatic | The DNS server to target |
useCookie |
boolean |
true |
Whether to use cookie in browser environment. The anonymous user token will not be set if false . When useCookie is false and setUserToken is not called yet, sending events will throw errors because there is no user token to attach to the events. |
cookieDuration |
number |
15552000000 (6 months) |
The cookie duration in milliseconds |
userToken |
string |
undefined (optional) |
Initial userToken. When given, anonymous userToken will not be set. |
(Node.js >= 8.16.0
required)
Insights library can be used on the backend as a Node.js module.
npm install search-insights
# or
yarn add search-insights
const aa = require('search-insights');
aa('init', {
appId: 'APPLICATION_ID',
apiKey: 'SEARCH_API_KEY'
});
On the Node.js environment, unlike the browser environment, userToken
must be specified when sending any event.
aa('clickedObjectIDs', {
userToken: 'USER_ID',
// ...
});
If you want to customize the way to send events, you can create a custom Insights client.
// via ESM
import { createInsightsClient } from "search-insights";
// OR in commonJS
const { createInsightsClient } = require("search-insights");
// OR via the UMD
const createInsightsClient = window.AlgoliaAnalytics.createInsightsClient;
function requestFn(url, data) {
const serializedData = JSON.stringify(data);
const { protocol, host, path } = require("url").parse(url);
const options = {
protocol,
host,
path,
method: "POST",
headers: {
"Content-Type": "application/json",
"Content-Length": serializedData.length
}
};
const { request: nodeRequest } =
url.indexOf("https://") === 0 ? require("https") : require("http");
const req = nodeRequest(options);
req.on("error", error => {
console.error(error);
});
req.write(serializedData);
req.end();
};
const aa = createInsightsClient(requestFn);
The Search Insights library supports both Search and Personalization Algolia features.
To enable click analytics, the search parameter clickAnalytics
must be set to true
. This tells the Algolia engine to return a queryID
on each search request.
const searchClient = algoliasearch('APPLICATION_ID', 'SEARCH_API_KEY');
const search = instantsearch({
indexName: 'INDEX_NAME',
searchClient,
searchParameters: {
clickAnalytics: true,
},
});
function getQueryID() {
return search.helper.lastResults.queryID;
}
aa('clickedObjectIDsAfterSearch', {
index: 'INDEX_NAME',
eventName: 'Click item',
queryID: getQueryID(),
objectIDs: ['object1'],
positions: [42],
});
Option | Type | Description |
---|---|---|
index |
string |
The name of the index related to the event |
eventName |
string |
The name of the event |
objectIDs |
string[] |
The list of IDs of the result that was clicked |
positions |
number[] |
The list of the absolute positions of the HTML element that was clicked (1-based and not 0-based) |
queryID |
string |
The queryID of the search sent from Algolia |
aa('convertedObjectIDsAfterSearch', {
index: 'INDEX_NAME',
eventName: 'Add to basket',
queryID: getQueryID(),
objectIDs: ['object1'],
});
Option | Type | Description |
---|---|---|
index |
string |
The name of the index related to the event |
eventName |
string |
The name of the event |
objectIDs |
string[] |
The list of IDs of the result that was clicked |
queryID |
string |
The queryID of the search sent from Algolia |
To enable personalization, the search parameter enablePersonalization
must be set to true
.
const searchClient = algoliasearch('APPLICATION_ID', 'SEARCH_API_KEY');
const search = instantsearch({
indexName: 'INDEX_NAME',
searchClient,
searchParameters: {
enablePersonalization: true,
},
});
In cases where the userToken
is generated, you need a way to access the userToken
so that you can pass it to the searchClient
.
const searchClient = algoliasearch('APPLICATION_ID', 'SEARCH_API_KEY');
aa('getUserToken', null, (err, userToken) => {
// for algoliasearch v3.x
searchClient.setExtraHeader('X-Algolia-UserToken', userToken);
// for algoliasearch v4.x
searchClient.transporter.headers['X-Algolia-UserToken'] = userToken;
});
If you want to attach a listener for userToken
change, you can call onUserTokenChange
.
aa('onUserTokenChange', (userToken) => {
console.log("userToken has changed: ", userToken);
});
onUserTokenChange
accepts callback
(required) and options
(optional).
aa('onUserTokenChange', callback, options);
Option | Type | Description |
---|---|---|
immediate |
boolean |
Fire the callback as soon as it's attached |
aa('init', { ... }); // ← This sets an anonymous user token if cookie is available.
aa('onUserTokenChange', (userToken) => {
console.log(userToken); // prints out the anonymous user token
}, { immediate: true });
aa('init', { ... });
aa('setUserToken', 'my-user-id-1');
aa('onUserTokenChange', (userToken) => {
console.log(userToken); // prints out 'my-user-id-1'
}, { immediate: true })
With immediate: true
, onUserTokenChange
will be immediately fired with the token which is set beforehand.
aa('clickedObjectIDs', {
index: 'INDEX_NAME',
eventName: 'Add to basket',
objectIDs: ['object1'],
});
Option | Type | Description |
---|---|---|
index |
string |
The name of the index related to the event |
eventName |
string |
The name of the event |
objectIDs |
string[] |
The list of IDs of the result that was clicked |
aa('clickedFilters', {
index: 'INDEX_NAME',
eventName: 'Filter on facet',
filters: ['brand:Apple'],
});
Option | Type | Description |
---|---|---|
index |
string |
The name of the index related to the event |
eventName |
string |
The name of the event |
filters |
string[] |
The list of filters that was clicked as '${attr}${op}${value}' |
aa('convertedObjectIDs', {
index: 'INDEX_NAME',
eventName: 'Add to basket',
objectIDs: ['object1'],
});
Option | Type | Description |
---|---|---|
index |
string |
The name of the index related to the event |
eventName |
string |
The name of the event |
objectIDs |
string[] |
The list of IDs of the result that was clicked |
aa('convertedFilters', {
index: 'INDEX_NAME',
eventName: 'Filter on facet',
filters: ['brand:Apple'],
});
Option | Type | Description |
---|---|---|
index |
string |
The name of the index related to the event |
eventName |
string |
The name of the event |
filters |
string[] |
The list of filters that was clicked as '${attr}${op}${value}' |
aa('viewedObjectIDs', {
index: 'INDEX_NAME',
eventName: 'Add to basket',
objectIDs: ['object1'],
});
Option | Type | Description |
---|---|---|
index |
string |
The name of the index related to the event |
eventName |
string |
The name of the event |
objectIDs |
string[] |
The list of IDs of the result that was clicked |
aa('viewedFilters', {
index: 'INDEX_NAME',
eventName: 'Filter on facet',
filters: ['brand:Apple'],
});
Option | Type | Description |
---|---|---|
index |
string |
The name of the index related to the event |
eventName |
string |
The name of the event |
filters |
string[] |
The list of filters that was clicked as '${attr}${op}${value}' |
The following examples assume that the Search Insights library is loaded.
To run the examples and the code, you need to run two separate commands:
yarn dev
runs webpack and the Node.js serveryarn build:dev
runs Rollup in watch mode
To release, go on master
(git checkout master
) and use:
yarn run release
It will create a pull request for the next release. When it's reviewed, approved and merged, then CircleCI will automatically publish it to npm.
Search Insights is MIT licensed.