eele94 / search-insights.js

Insights

Library for detecting front-end search metrics eam

Concept

Algolia insights library allows developers to report click and conversion metrics related to search queries. It does so by correlating events with queryIDs generated by the search API when a query parameter clickAnalytics=true is set.

Once a search has been initialized and the queryID received, the library currently supports two types of events - click and conversion.

Getting started

Loading and initializing the library

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', {
      applicationID: 'APPLICATION_ID',
      apiKey: 'SEARCH_API_KEY'
    })
  </script>

Enabling queryID response from Algolia engine

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

InstantSearch

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

algoliasearch-helper:

  const helper = algoliasearchHelper(client, 'INDEX_NAME', {
    clickAnalytics: true
  });

Initializing search analytics

After loading the library you will need to call the initSearch function of the library and provide a callback function that will return the queryID sent by the Algolia engine. We recommend you upgrade your InstantSearch or AlgoliaSearch-helper to the latest version as we have improved the way you can access the queryID value returned by the engine.

To retrieve the queryID from the helper instance and pass it to search insights library you can access it directly from the lastResults store.

  // Initialize search analytics - 
  // should be called after the UI has rendered
  // and you have the reference to search state and 
  // inputSelector exists in the DOM
  aa('initSearch', {
    getQueryID: () => search.helper.lastResults.queryID
  })

Older versions of InstantSearch.js or Algoliasearch-helper

To access queryID from the older versions it's required to access the _rawResults property on the helper.

// Initialize search analytics - 
// should be called after the UI has rendered
// and you have the reference to search state and 
// inputSelector exists in the DOM
aa('initSearch', {
  getQueryID: () => search.helper.lastResults && search.helper.lastResults._rawResults[0].queryID
})

Reporting click events

To report a click event, you have to call aa('click',{objectID: clickedObjectID, position: positionOfElement}). The argument passed to click function is an object containing the objectID and the absolute position of the element. An optional parameter that can be passed is also a queryID value. This is useful for when you are doing a multi-index search and want to report different types of queryID parameters, depending on where the user has clicked inside the DOM.

• objectID: It is the ID of the result that has been clicked. *required
• position: absolute position of the clicked element inside the DOM. (The value is 1 based and not 0 based!) *required
• queryID: optional queryID parameter that overrides the getQueryID function *optional

Depending on the library and implementation details, these two can both be done straight from the hit template or in a custom event handler.

Reporting conversion events

Upon a conversion event, the API is a bit different and you will only have to call the conversion event with aa('conversion',{objectID: clickedObjectID}). The 2nd parameter is the same as above, it is the ID of the clicked result. This ID will be used to derive the queryID. Internally, the library keeps a store of associated click and search events. When a conversion event happens, it tries to correlate the conversion to a click event via the queryID. If no event is found, it assumes that the conversion event did not happen as a result of search.

Library implementation examples

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
• Vue-instantsearch example
• React-instantsearch example
• Autocomplete example

Running examples locally

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