How to setup Algolia Analytics in Gatsby
Implement custom Algolia Analytics in 5 minutes.
Step One: Install search-insights package
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
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
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 inquiries@delasign.com with any thoughts or feedback you may have.