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 use the queryID, we have to make sure you actually receive it with every search that you perform. This can be done by setting clickAnalytics=true as an extra search parameter.

With the JavaScript client:

1
2
3
4
5
6
7
8
index
  .search({
    query: 'query',
    clickAnalytics: true
  })
  .then(res => {
    // console.log(res);
  });

With InstantSearch:

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

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

const App = () => (
  <InstantSearch /*...*/ >
    <Configure clickAnalytics />
  </InstantSearch>
);

1
<ais-configure [searchParameters]="{ clickAnalytics: true }"></ais-configure>

1
2
3
4
5
<template>
  <ais-instant-search [...]>
    <ais-configure clickAnalytics="true" />
  </ais-instant-search>
</template>

Passing the queryID to your conversion page

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, even from another screen of your app.

For web applications, we recommend using query parameters. However, any other persistence mechanism can work.

1
2
3
4
5
6
7
index.search({
  query: 'query',
  clickAnalytics: true
}).then(res => {
  const queryID = res.queryID
  //
});

If you’re using InstantSearch, you can easily retrieve the queryID from the while using Hits component:

1
2
3
4
5
6
7
search.addWidget(
  search.widgets.hits({
    templates: {
      item: item => `<a href="product.html?queryID=${item.__queryID}"> ... </a>`
    }
  })
);

1
2
3
4
5
6
7
const Hit = ({ hit }) => (
  <article>
    <a href={`/product.html?queryID=${hit.__queryID}`}>
      ...
    </a>
  </article>
);

1
2
3
4
5
6
7
<ais-hits>
  <ng-template let-hits="hits" let-results="results">
    <a *ngFor="let hit of hits" href="/product.html?queryID={{hit.__queryID}}">
      <ais-highlight attribute="name" [hit]="hit"></ais-highlight>
    </a>
  </ng-template>
</ais-hits>

1
2
3
4
5
6
7
<ais-hits>
  <template slot="item" slot-scope="{ item }">
    <a href="/product.html?queryID={{item.__queryID}}">
      ...
    </a>
  </template>
</ais-hits>

The last thing you need to do before sending conversion events, is retrieving the queryID from the query parameters. If you’ve passed it to the page where conversion occurs through the URL parameters, you can simply 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.