Keeping Track of the QueryID For Conversion Events

Introduction

Oftentimes, a conversion event occurs outside of your search implementation. Let’s take an online bookshop as an example: the conversion could occur when a user buys a product. Since this page is not normally part of the search results page, you’ll need to make sure it contains the necessary information for sending a conversion event. To send a conversion event, we need to know the queryID and the objectID.

A best practice is to keep track of the index used to search as well, especially if you have multiple indices used for your search. This is because a queryID is not necessarily coupled to a certain index, you’ll have to make that link yourself when sending the events.

Keeping track of the queryID

To keep track of the queryID for a conversion that happens outside of the search scope, we need to have the queryID of the previous search available in the new context such as the buy page. Whenever our user performs a search, we save, or pass, the latest queryID, which we can then use once to send a conversion event.

This guide will discuss how to keep track of the queryID for web applications. However, these same steps apply to any platform.

Obtaining the queryID from the search response

Before you can save the queryID, we need to make sure that we actually receive it with every search. This can be done by setting clickAnalytics=true as an extra search parameter.

1
2
3
4
5
6
7
8
// Set up InstantSearch
const search = instantsearch({
  searchClient,
  indexName: 'INDEX_NAME',
  searchParameters: {
    clickAnalytics: true,
  },
});

Saving the queryID

As just discussed, in order to save the queryID, you need to make sure you’ve enabled the queryID in the search response. This allows you to link events to a certain search.

Anytime the queryID changes, which is every time the user executes a query, you should save the queryID so that it can be accessed at a later point. For web applications, this could be localStorage, cookies, query parameters, or any other available method.

In our example, we will make use of the query parameters.

In order to save the queryID every time it is updated, we need to hook into our search implementation.

Without InstantSearch

If you don’t have an InstantSearch implementation, you will need to add code to save the queryID just after you execute the search method with your API Client. The response of this method contains the queryID for you to use and save where necessary.

With InstantSearch

If you are using one of our InstantSearch flavors, you can leverage the render function of the searchBox widget to obtain the queryID This function is called every time the query is updated, and on the first load.

Note: We use the InstantSearch helper’s lastResults property to fetch the queryID (see line 12 of the snippet below). This property is undefined on our first render, since no search has been performed yet. Please make sure you set the queryID only if it’s available.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Set up InstantSearch
const search = instantsearch({
  searchClient,
  indexName: 'INDEX_NAME',
  searchParameters: {
    clickAnalytics: true,
  },
});


search.addWidget(
    search.widgets.hits({
         templates: {
             item: item => `<a href="product.html?queryID=${search.helper.lastResults.queryID}&objectID=${item.objectID}&index=INDEX_NAME"> </a>`
         }
   })
);

With the above code integrated into your search, the queryID will now be saved every time it gets updated.

Retrieve the queryID

The last thing you need to do before sending conversion events, is retrieving the queryID from the query parameters. One way to achieve this is to use the URL API implemented in most browsers.

1
2
3
4
const url = new URL(window.location.href);
const searchParams = url.searchParams;

const queryID = searchParams.get('queryID');

Send the conversion event

With the queryID available, it’s easy to send the conversion event if and when a conversion happens. Please read our guides on sending conversion events with InstantSearch or sending conversion events with an API Client for full details on how to do this.

If no queryID is available, consider sending the conversion event without a search.

Did you find this page helpful?