Library for detecting front-end search metrics

Algolia insights client allows developers to report click, conversion and view metrics related using the Insights REST API

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>
  !function(e,a,t,n,s,i,c){e.AlgoliaAnalyticsObject=s,e.aa=e.aa||function(){(e.aa.queue=e.aa.queue||[]).push(arguments)},i=a.createElement(t),c=a.getElementsByTagName(t)[0],i.async=1,i.src="https://cdn.jsdelivr.net/npm/[email protected]",c.parentNode.insertBefore(i,c)}(window,document,"script",0,"aa");

  // Initialize library
  aa('init', {
    appId: 'APPLICATION_ID',
    apiKey: 'SEARCH_API_KEY',
    userHasOptedOut?: boolean; // Optional. Default: false
    region?: "de" | "us"; // Optional. Default auto
    cookieDuration?: 10 * 24 * 60 * 60 * 1000; // in milliseconds. Optional. Default: 15552000000ms (6 months)
  })

  // optional
  aa('setUserToken', 'id-of-user');
</script>

In order for the Algolia engine to return a queryID on each search request, some special query parameters clickAnalytics=true and enablePersonalization=true should be set.

const search = instantsearch({
  appId: "APPLICATION_ID",
  apiKey: "SEARCH_API_KEY",
  indexName: "INDEX_NAME",
  searchParameters: {
    clickAnalytics: true,
    enablePersonalization: true
  }
});

const search = instantsearch({
  appId: "APPLICATION_ID",
  apiKey: "SEARCH_API_KEY",
  indexName: "INDEX_NAME",
  searchParameters: {
    clickAnalytics: true
  }
});
function getQueryID() {
  return search.helper.lastResults.queryID;
}

aa("clickedObjectIDsAfterSearch", {
  index: "INDEX_NAME",
  eventName: "Clicked item",
  queryID: getQueryID(),
  objectIDs: ["object1"],
  positions: [42]
});

• index: name of the index searched. *required
• eventName: name of the event. *required
• objectIDs: it is the ID of the result that has been clicked. *required
• positions: absolute position of the clicked element inside the DOM. (The value is 1 based and not 0 based!) *required
• queryID: queryID of the related search *required

aa('convertedObjectIDsAfterSearch', {
    index: 'INDEX_NAME'
    eventName: 'Add to basket',
    queryID: getQueryID(),
    objectIDs: [ 'object1' ]
});

• index: name of the index searched. *required
• eventName: name of the event. *required
• objectIDs: it is the ID of the result that has been clicked. *required
• queryID: queryID of the related search *required

const search = instantsearch({
  appId: "APPLICATION_ID",
  apiKey: "SEARCH_API_KEY",
  indexName: "INDEX_NAME",
  searchParameters: {
    enablePersonalization: true
  }
});

aa('clickedObjectIDs', {
    index: 'INDEX_NAME'
    eventName: 'Add to basket',
    objectIDs: [ 'object1' ]
});

• index: name of the index searched. *required
• eventName: name of the event. *required
• objectIDs: it is the ID of the result that has been clicked. *required

aa('clickedFilters', {
    index: 'INDEX_NAME'
    eventName: 'Filter on facet',
    filters: [ 'brand:Apple' ]
});

• index: name of the index searched. *required
• eventName: name of the event. *required
• filters: it is the facet that has been clicked. *required

aa('convertedObjectIDs', {
    index: 'INDEX_NAME'
    eventName: 'Add to basket',
    objectIDs: [ 'object1' ]
});
aa('convertedFilters', {
    index: 'INDEX_NAME'
    eventName: 'Filter on facet',
    filters: [ 'brand:Apple' ]
});

aa('viewedObjectIDs', {
    index: 'INDEX_NAME'
    eventName: 'Add to basket',
    objectIDs: [ 'object1' ]
});
aa('viewedFilters', {
    index: 'INDEX_NAME'
    eventName: 'Filter on facet',
    filters: [ 'brand:Apple' ]
});

All library examples are done with an assumption, that you have already completed the first step of loading the library.

• InstantSearch.js example
• algoliasearch-helper example
• React-instantsearch example

To run all examples and play around with the code you have to run two separate commands:

• yarn dev - runs webpack and node dev server
• yarn build:dev - runs rollup in watch mode - livereload if you do changes to the insights library

• applicationID is now called appId, to stay consistent with our other js libraries.

Before:

  aa('init', {
    applicationID: 'APPLICATION_ID',
    apiKey: 'SEARCH_API_KEY'
    // other props
  })

After:

  aa('init', {
    appId: 'APPLICATION_ID',
    apiKey: 'SEARCH_API_KEY'
    // other props
  })

This method was previously used to pass getQueryID helper. Now you need to explicitly call this helper and pass the result to methods that require it (namely clickedObjectIDsAfterSearch and convertedObjectIDsAfterSearch) ``

Before:

 aa('initSearch', {
    getQueryID: () => search.helper.lastResults.queryID
 })

After:

  const getQueryID = () => search.helper.lastResults.queryID

To make it clear that they are intended to be called in the context of a search:

• click is now clickedObjectIDsAfterSearch
• convert is now convertedObjectIDsAfterSearch

The signatures have also changed:

• On clickedObjectIDsAfterSearch

  • eventName: string is now required
  • index: string is now required
  • objectID: number | string is now objectIDs : Array<number | string>
  • queryID: string is now required, use the getQueryID helper documented
  • position: number is now positions : Array<number>

• On convertedObjectIDsAfterSearch

  • eventName: string is now required
  • index: string is now required
  • objectID: number | string is now objectIDs : Array<number | string>
  • queryID: string is now required, use the getQueryID helper documented

Before:

aa("click", {
  objectID: "object1",
  position: 42
});
aa("convert", {
  objectID: "object1",
  position: 42
});

After:

aa("clickedObjectIDsAfterSearch", {
  index: "INDEX_NAME",
  eventName: "Clicked item",
  queryID: getQueryID(),
  objectIDs: ["object1"],
  positions: [42]
});
aa("convertedObjectIDsAfterSearch", {
  index: "INDEX_NAME",
  eventName: "Clicked item",
  queryID: getQueryID(),
  objectIDs: ["object1"]
});