Search Insights

Search Insights lets you report click, conversion and view metrics using the Algolia Insights API.

Table of Contents

• Getting started
  • Browser
  • Node.js
• Use cases
  • Search (Click Analytics and A/B testing)
  • Personalization
• Examples
• Contributing
• License

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/search-insights@1.4.0";

!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
cookieDuration	number	15552000000 (6 months)	The cookie duration in milliseconds

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-insights

2. 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',
  // ...
});

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;
});

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}'

Examples

The following examples assume that the Search Insights library is loaded.

• InstantSearch.js
• AlgoliaSearch Helper

Contributing

To run the examples and the code, you need to run two separate commands:

• yarn dev runs webpack and the Node.js server
• yarn build:dev runs Rollup in watch mode

License

Search Insights is MIT licensed.