Send Click and Conversion Events with React InstantSearch

Events are actions that users take on your app or website. They unlock powerful features, such as recommendations, personalization, smarter search results, and analytics that help you optimize your user experience. For more information, see Get started with click and conversion events.

To send events from your React InstantSearch app, follow these steps:

1. Add the insights client.
2. Add click events when users click search results.
3. Track conversions that start in your InstantSearch app.

Before you begin

This guide works with:

• search-insights version 1.6.2 or later
• React InstantSearch

Add search-insights to your project

The search-insights JavaScript library lets you send events to the Algolia Insights API. To add it to your project:

1. Install the Insights client
2. Initialize the Insights client

Set the userToken

To identify users across sessions, explicitly set the userToken:

1
aa('setUserToken', 'user-id')

For example, use the account ID after the user signed in on your website. The search-insights library can generate an anonymous user token and store it in the first-party _ALGOLIA cookie.

Don’t use personally identifiable information as a user ID.

Get the queryID from the search response

Search-related events must include a query ID. To retrieve it, set the clickAnalytics parameter to true using the configure widget:

1
2
3
4
5
6
7
8
9
10
import { InstantSearch, Configure } from 'react-instantsearch-dom';

const App = () => (
  <InstantSearch
    indexName="INDEX_NAME"
    searchClient={searchClient}
  >
    <Configure clickAnalytics />
  </InstantSearch>
);

The insights function infers the queryID from the InstantSearch context.

Add the search-insights client

You can connect the search-insights client to any hits component from which you want to send click or conversion events.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { connectHitInsights } from 'react-instantsearch-dom';

const Hit = ({ hit, insights }) => (
  <article>
    <h1>{hit.name}</h1>
    <button> Add to favorite </button>
  </article>
);

// You need to call `window.aa('init', { appId, apiKey })` before.
// Make sure Hit has a `hit` prop.
const HitWithInsights = connectHitInsights(window.aa)(Hit);

<Hits hitComponent={HitWithInsights} />;

Send click events

Call the insights function from within the hits component to send an event:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
const Hit = ({ hit, insights }) => (
  <article>
    <h1>{hit.name}</h1>
    <button
      onClick={() =>
        insights('clickedObjectIDsAfterSearch', {
          eventName: 'Product Clicked'
        })
      }
    >
      See details
    </button>
  </article>
);

Similar to the queryID, the insights function can infer the required event properties from the InstantSearch context. You must provide an eventName.

This example uses the clickedObjectIDsAfterSearch type of event, but you could also use convertedObjectIDsAfterSearch.

Check your click events in the Events Debugger. For more information, see Validate your events.

Send conversion events

You can use the insights function with convertedObjectIDsAfterSearch to send a conversion event.

However, conversions often happen outside your search pages. For example, the Order completed event for a successful purchase happens in the shopping cart. To capture these conversions, keep track of the query ID across your site.

Then, send the conversion event with convertedObjectIDsAfterSearch from the search-insights library.

Check your conversion events in the Events Debugger. For more information, see Validate your events.

The insights function doesn’t support sending events that are unrelated to search. For these events, use the API clients, Insights API, or InstantSearch library.

A complete example

See Insights for React InstantSearch for a complete example.