How to setup Algolia Analytics in Gatsby

Oscar de la Hera Gomez
Algolia Analytics works via API calls

Implement custom Algolia Analytics in 5 minutes.

Step One: Install search-insights package

Search Insights is an NPM package that facilitates Algolia Analytics

Search Insights is an NPM package that facilitates Algolia Analytics

In Terminal, in the current directory of your project, run the following line

yarn add search-insights

Step Two: Create the Algolia Analytics Functionality

A Singleton is a creational design pattern, which ensures that only one object of its kind exists and provides a single point of access to it for any other code.

Please implement the code below into your system, it contains the code Algolia Analytics needs to start up & to send events. Feel free to modify the events to your taste - we have provided supporting documentation to help you inform yourself of what's possible.

Step Three: Implement the solution

Algolia uses API calls to receive analytics events

The final solution is composed of two parts: initializing the component & sending out analytics events.

Call initialize in every component that uses it.

Please call AlgoliaInitialize or use the code below to initialize.

aa("init", { appId: process.env.GATSBY_ALGOLIA_APP_ID as string, apiKey: process.env.GATSBY_ALGOLIA_SEARCH_KEY as string, });

Send events at every touchpoint

Please call AlgoliaReportBlogClick/AlgoliaReportSearchClick or use the code below to send events.

Please replace

  • A_USER_ID with a value that allows you to change results based on user
  • YOUR_SEARCH_INDEX with the name of the index you are analyzing
  • YOUR_SEARCH_EVENT with the event that you want to associate this piece of analytics to
  • YOUR_QUERY_ID with the queryID for the search that was performed - please consult our post on setting up Algolia with Gatsby to learn more.
  • OBJECT_ID_THAT_WAS_CHOSEN with the objectId that was selected for the given analytics
  • OBJECT_POSITION_IN_SEARCH with the position of the object that was chosen in search - this value cannot be 0 and starts at 1.

Please note that:

  • These call can handle multiple objects, incase theres multiple items to report under a query (i.e. user selected two products to check out).
  • ObjectIDs must be limited to 20 objects. If you have more than 20 objectIds in a call, you will get a 422 HTTP error, this can be resolved by making a batch of Analytics API calls each limiting ObjectIds to a maximum of 20 (i.e. 5 calls for 100 Object Ids - breaking up the objectIds into groups of 20, whilst maintaining the QueryId across the calls).
  • A QueryID MUST be included and must be a 32 character hexadecimal string. We recommend using "00000000000000000000000000000000" if there is no query present so theres a streamlined way of identifying blank queries. If you do not include a QueryID, Algolia will return a 422 HTTP error.

aa("clickedObjectIDsAfterSearch", { userToken: A_USER_ID, index: YOUR_SEARCH_INDEX, eventName: YOUR_SEARCH_EVENT, queryID: YOUR_QUERY_ID, objectIDs: [OBJECT_ID_THAT_WAS_CHOSEN], positions: [OBJECT_POSITION_IN_SEARCH], });

Please note that this example uses the "clickedObjectIDsAfterSearch" parameter, as recommended by Algolia. For more information on the parameters above or the possible events you can use please read up the following information:

Need help developing an Algolia application ?

If you are seeking help for developing an Algolia application, please book a free consultation with us.

Frequently Asked Questions (FAQ)

Why am I getting a 422 error ?

In our experience, with reference to the Algolia documentation, you will get a 422 error from events if:

  • There is no QueryId (or it is blank).
  • If you have 20 objects within a single event.

Any Questions?

We are actively looking for feedback on how to improve this resource. Please send us a note to with any thoughts or feedback you may have.

delasign logo

Book a Free Consultation.

An icon of an email.

Click here to email us.

Fill in the details below to book a free consultation or to let us know about something else. Whatever it is, we are here to help.

How can we help you ?

Contact Details