alg-insights

Insights

Library for detecting front-end search metrics

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 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/alg-insights@0.1.0/dist/alg-insights.js",c.parentNode.insertBefore(i,c)}(window,document,"script",0,"aa");

    // Initialize library
    aa('init', {
      apiKey: 'SEARCH_API_KEY',
      applicationID: 'APPLICATION_ID'
    })
  </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. The queryID can be retrieved from the raw results array inside your 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 2nd argument passed to the click event is the objectdID. It is the ID of the result that has been clicked. It is required.
• The 3rd argument is also required. It is the absolute position of the clicked element inside the DOM.

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

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