Insights Validator Plugin

Algolia provides a powerful API to track the usage of your search and surface metrics such as click-through rate, conversion, and no results rate. To gather and leverage these metrics, you need to implement Click Analytics and send events to our Insights API.

To visualize and validate your implementation, we provide a Chrome extension that monitors all events sent to our API, and their relationships to one another.

Installation

You can install the validator from the Chrome Web Store. Head over to the extension’s page and click Add to Chrome.

Extension overview

Click Analytics lets you associate searches with events. In complex implementations, debugging and visualizing the relationships between searches and events can be a tedious task. The Insights validator gives you real-time feedback, and links queries and analytics events together. It displays your analytics data clearly, allowing you to be confident about your implementation or to quickly discover what needs to be fixed.

Sending searches

You can try out the plugin right on this website, which implements Click Analytics. Once you have installed the extension, you can trigger a search by typing into the search bar.

You can immediately see the number of queries that went through. If you click on the plugin’s icon, you can see that searches were made, and that the website properly loaded the search-insights library.

As you search and trigger events on the website, the popup will record the number of events and searches you’re sending to Algolia.

Getting more details

While the popup provides general information, you need to open the Chrome DevTools and navigate to the Insights Validator tab to get a more detailed understanding of:

• what data you’re sending to Algolia
• how that search and events are linked together.

If you make searches while on the Insights Validator tab of the DevTools, you’ll see them get logged in real time. You can see more information by clicking on them.

Implementing Click Analytics

Ensuring clickAnalytics is enabled at query time

When implementing Click Analytics, the first step is to enable the clickAnalytics query parameter. From the DevTools, you can get a quick overview of which queries have clickAnalytics enabled.

Clicking on any search event opens a small dropdown which displays extra information. You can see what analyticsTags were applied or what the generated queryID is. This will be important later on, when we’ll need to send events to the Insights API.

Triggering click events

Once you have enabled the clickAnalytics query parameter, you’re ready to implement the search-insights library. This is what lets you send analytics and personalization events.

Once you’ve implemented and defined your click and conversion events, you can open the DevTools and trigger any event by clicking on its associated element.

When a click event goes through, the extension reports it. The Analytics API then uses this data to compute click-through rate, average click position, and a histogram of click positions for the current query.

Triggering conversion events

Conversion events work the same as click events. Triggering a conversion event with your DevTools open will show you how searches and events are linked together.

Triggering Personalization events

Events sent to the Insights API can be used by both Click Analytics and Personalization. Events data can help you configure your personalization strategy. In the dashboard, you can set the importance of each specific event and its impact on search results.

Other information

Check A/B tests

Algolia’s A/B Testing feature is transparent to the end user. As a consequence, you might not be able to properly inspect when you’re querying an index that is being A/B tested.

The extension shows you if an A/B test is running and on which index, so that you can quickly know how the results you’re seeing might be influenced.

Validate that the Insights library is properly loaded

The search-insights library allows you to send events to the Insights API. You may use any version, but the extension shows you a warning when you’re using an older version below 1.0.0.

We recommend that you keep your dependencies up to date and upgrade the search-insights library to the latest major version.

Validate Click Analytics events

When implementing Click Analytics, you need to pass at least three parameters: userToken, queryId, and position. Each parameter must be present and valid. When they’re not and you make a search, the extension shows an error.

Troubleshooting

I’m not seeing any click analytics metrics in my analytics dashboard

If your search isn’t properly configured, or if you’re sending malformed data to the Insights API, you may not see any results in your analytics dashboard. Also, there might be a delay of a few minutes between the moment you send events and the time that it takes for us to compute metrics. Under normal circumstances, this shouldn’t be longer than 15 minutes.

The extension is the perfect solution to help you validate your implementation, and make sure you’re properly sending events. Please note that the Insights Validator only works if you’re using a front-end implementation.

Please make sure that the clickAnalytics parameter is enabled, and that you’re properly triggering click and conversion events. If you’re seeing events being dispatched in the Chrome extension, then click-through rates, conversion rates, and average click position metrics should appear in your analytics dashboard.

I’m not seeing any searches or events in the Chrome DevTools

The extension only works for front-end implementations that use either our JavaScript client or one of our InstantSearch libraries, along with the search-insights library. It does not work with back-end implementations.

Using our libraries allows us to reliably listen for certain network requests and properly report your analytics data. It also minimizes human error. If you can’t use our libraries, please give us feedback so we can understand the current limitations or requirements that they don’t cover. Hopefully we can further adjust and ease your implementation!