Tracking

Events represent user interactions on our website. They unlock powerful features, such as recommendations, personalization, smarter search results, and analytics that help you optimize your user experience. They have extra details, like the name, type, and time of the interaction, and user identity.

The basic shape of an event is:

{
  // Event type: click, conversion, or view
  "eventType": "click",
  // Name for the specific event
  "eventName": "Clicked Search Result",
  // Events are related to items from an Algolia index
  "index": "prod_ecommerce_EN",
  // Pseudonymous or anonymous user identifier
  "userToken": "anonymous-xxxxxx-xx-xxx-xxxxxx",
  // Optional: time of the event. By default the current time is used.
  "timestamp": "1673636676",
  // For search and browse events only: a unique identifier for a search query preceding this event.
  // Generated by Algolia and included in the API response if you set `clickAnalytics: true`
  "queryID": "43b15df305339e827f0ac0bdc5ebcaa7",
  // List of objectIDs the user interacted with. Can't be used with `filters`
  "objectIDs": ["item-1"],
  // List of filters the user interacted with. Can't be used with `objectIDs`
  // "filters": "",
  // For search and browse events only: the position of the `objectID` in the search results.
  "positions": [1],
}

As a minimum, we should send click events when a user selects a searc results and a conversion event when they perform a step towards a business goal such as a purchase.

When planning which events to send, we should consider all interaction points our customers have with our site. For us this would be:

• Category pages or PLPs
• Search result pages
• Autocomplete menu (if implemented)
• Emails, newsletters and another other pages such as content with products

Algolias OOTB Analtics

Algolia automatically captures search analytics. Its OOTB analytics helps to break down users behaviour by turning searches into metrics such as most popular searches, the number of searches with no results, filter and facet usage. Below is a breakdown of all the measurements

Measurements

• Overall search counts
• A “No search result” rate
• Top searches
• Top searches with no results
• Top results
• If a filter is provided, top searches associated with that filter
• Top filter attributes and filter values
• Distinct count of IP addresses / Users
• Top countries

Must have events

PLPs

Event	Description	API Method	Properties
PLP: Product Clicked	A user clicked on a search result. Send a click event to capture the search query, which item was clicked, and the position in the search results.	clickedObjectIDsAfterSearch	eventName, indexName, objectIDs, positions, userToken
PLP: Product Added to Cart	A user added an item to the cart from the product-listing page after performing a search. This is a future recommendation should we add to basket from the PLP	convertedObjectIDsAfterSearch	eventName, indexName, objectIDs, userToken

PDPs

Event	Description	API Method	Properties
PDP: Product Added to Cart after Search	A user added an item to the cart on the product-detail page after performing a search.	convertedObjectIDsAfterSearch	eventName, indexName, objectIDs, queryID, userToken
PDP: Product Added to Cart	A user added an item to the cart.	convertedObjectIDs	eventName, indexName, objectIDs, userToken

Autocomplete

Only recommended if we include products in the autocomplete menu of the search interface, then we should send events for the user interactions. These are considered as must haves.

Event	Description	API Method	Properties
Autocomplete: Product Clicked	A user clicked on a search result in the autocomplete menu.	clickedObjectIDsAfterSearch	eventName, indexName, objectIDs, positions, userToken
Autocomplete: Product Added to Cart	A user added an item to the cart from the autocomplete menu.	convertedObjectIDsAfterSearch	eventName, indexName, objectIDs, userToken

Personalisation

Again like Autocomplete we should include the following user interactions to enhance our Personalisation strategy. Some of the following are important to capture for PLP

Event	Description	API Method	Properties
PLP: Filter Clicked	A user selected a facet value. One to track via the PLP stream of work.	clickedFilters	eventName, indexName, filters, userToken
PLP: Filter Viewed	A user viewed a landing page. One to track via the PLP stream of work.	viewedFilters	eventName, indexName, filters, userToken
Product Viewed	A user viewed a product page from an email, newsletter, push notification, or any other page.	viewedObjectIDs	eventName, indexName, objectIDs, userToken

Sending Events

To send events from our Search application (Scariff), follow these steps:

1. Set the insights option to true. This loads the search-insights for you and sends default events when viewing and clicking search results, or when selecting filters.
2. Add additional click events when a user clicks search results. More information can be found here
3. Track conversions that start in the application. More details can be found below.

Insights

<InstantSearch
  searchClient={client}
  indexName={RAPHA.INDEX_NAME}
  insights={true}
>
  {/* ... */}
</InstantSearch>

Enabling insights gives us the following:

• Load the search-insights library
• Set an anonymous user token for events and search analytics
• Retrieve the queryID for click and conversion events
• Send default events from our widgets

Search Insights Library

InstantSearch loads the search-insights library for you from jsDelivr. Some considerations are:

• Do we want to host our own version?
  • Yes - Increase to package size.
  • No - We have to add https://cdn.jsdelivr.net to our CSP to allow the library to load.

userToken

InstantSearch automatically sets an anonymous user token and stores it in memory. To identify users across sessions, explicitly set the userToken.

window.aa('setUserToken', 'user-id');

Persist an anonymous userToken across sessions

The search-insights library can generate an anonymous user token and store it in the first-party _ALGOLIA cookie. To enable this, we can set the useCookie option to true.

<InstantSearch
  searchClient={client}
  indexName={RAPHA.INDEX_NAME}
  insights={{ useCookie: true }}
>
  {/* ... */}
</InstantSearch>

Default Events

With the insights middleware, our InstantSearch widgets send default events. To check the default events we can use the Events Debugger.

Default click events for refinement widgets

The following widgets send click events (“Filter Applied”) when users select a refinement. Custom widgets using the hooks send the same events.

Widget	Hook
<HierarchicalMenu>	useHierarchicalMenu
<Menu>	useMenu
	useNumericMenu
<Range>	useRange
<RefinementList>	useRefinementList
<ToggleRefinement>	useToggleRefinement

Default view events for results widgets

The following widgets send view events (“Hits Viewed”) for the visible items in the search results. Custom widgets using the connectors send the same events.

Widget	Hook
<Hits>	useHits
<InfiniteHits>	useInfiniteHits

Default click events for results widgets

Widget	Hook
<Hits>	useHits
<InfiniteHits>	useInfiniteHits

Track conversions

Conversions in our case currently happen outside of search. For example, an “Order Completed” event for a successful purchase happens in the shopping cart. To capture these conversions, we must keep track of the query ID across the site. If we were to add one-click purchase from the search result page we would also need to track conversions at that point.

Full example

A full example of insights using react-instantsearch-hooks can be found here

---

Collecting click and conversion events using GTM (Google Tag Manager)

As we are using GTM we can use it to send click, conversion and view events to the Algolia Insights API. To do this we must:

1. Add clickAnalytics to Configure component in our Search application.

import { Configure } from 'react-instantsearch-hooks-web';

<Configure
  clickAnalytics={true}
  userToken={'user-1'}
/>

• Set clickAnalytics to true so that the queryID can be retrieved for event tracking
• Pass the userToken to connect search queries and events.

Resources

• clickedObjectIDsAfterSearch
• convertedObjectIDsAfterSearch
• convertedObjectIDs
• clickedFilters
• viewedFilters
• viewedObjectIDs
• Send click events
• react-instantsearch-hooks-insights