Search Insights
Search Insights lets you report click, conversion and view metrics using the Algolia Insights API.
Table of Contents
Cookie usage
You're looking at the documentation of search-insights v2, which is the new major version. (Click here for v1.x documentation.)
v2 introduces a breaking change which is useCookie being false by default. If it's false, search-insights doesn't generate anonymous userToken. It means no event will be sent until setUserToken is explicitly called.
Payload validation
Since v2.0.4, search-insights no longer validates event payloads. You can visit https://algolia.com/events/debugger instead.
Getting started
Are you using Google Tag Manager in your app? We provide a custom template to ease the integration.
Browser
1. Load the library
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>2. Initialize the library
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 |
false |
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. |
Note for Require.js users
When using Require.js, the default UMD build might conflict and throw with a "Mismatched anonymous define() modules" message. This is a known Require.js issue.
To work around this problem and ensure you capture all interactions occurring before the library is done loading, change ALGOLIA_INSIGHTS_SRC to point to the IIFE build, and load it via a <script> tag.
<script>
var ALGOLIA_INSIGHTS_SRC = "https://cdn.jsdelivr.net/npm/[email protected]/dist/search-insights.iife.min.js";
!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>Node.js
(Node.js >= 8.16.0 required)
1. Install the library
Insights library can be used on the backend as a Node.js module.
npm install search-insights
# or
yarn add search-insights2. Initialize the library
const aa = require('search-insights');
aa('init', {
appId: 'APPLICATION_ID',
apiKey: 'SEARCH_API_KEY'
});Add userToken
On the Node.js environment, unlike the browser environment, userToken must be specified when sending any event.
aa('clickedObjectIDs', {
userToken: 'USER_ID',
// ...
});Customize the client
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);Use cases
The Search Insights library supports both Search and Personalization Algolia features.
Search (Click Analytics and A/B testing)
Initialize
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;
}Report a click event
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 |
Report a conversion event
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 |
Personalization
Initialize
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,
},
});Access userToken
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;
});Listen to userToken change
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', { ..., useCookie: true }); // ← 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.
Report a click event
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}' |
Report a conversion event
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}' |
Report a view event
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}' |
Batch Events
You can send multiple events in a single HTTP request, by using sendEvents method.
aa('sendEvents', [
{
eventType,
eventName,
userToken,
...
}
]);| Option | Type | Description |
|---|---|---|
eventType |
'view' | 'click' | 'conversion' |
The name of the index related to the event. |
eventName |
string |
The name of the event. |
userToken |
string (optional) |
search-insights uses anonymous user token or a token set by setUserToken method. You can override it by providing a userToken per event object. |
Examples
The following examples assume that the Search Insights library is loaded.
Contributing
To run the examples and the code, you need to run two separate commands:
yarn devruns webpack and the Node.js serveryarn build:devruns Rollup in watch mode
To release, go on master (git checkout master) and use:
yarn run releaseIt will create a pull request for the next release. When it's reviewed, approved and merged, then CircleCI will automatically publish it to npm.
License
Search Insights is MIT licensed.