Keeping Track of the QueryID for Conversion Events

Oftentimes, a conversion event occurs outside of your search implementation. Take an online bookshop as an example: the conversion could occur when a user buys a product. Since this page isn’t normally part of the search results page, you need to make sure it has the necessary information for sending a conversion event. To send a conversion event, you 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 isn’t necessarily coupled to a certain index—you 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, you need to have the queryID of the previous search available in the new context. Whenever the user performs a search, you save, or pass, the latest queryID, which you can then use once to send a conversion event.

This guide discusses 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, you need to make sure you actually receive it with every search that you perform. You can do this by setting clickAnalytics as an extra search parameter.

With the JavaScript client:

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

With InstantSearch:

1
2
3
4
5
search.addWidgets([
  instantsearch.widgets.configure({
    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 you can access it at a later point, even from another page of your app. For web applications, one way to do this is with query parameters. However, any other persistence mechanism can work.

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

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

1
2
3
4
5
6
7
search.addWidgets([
  instantsearch.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 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, you can send a conversion event when a conversion happens. Please read the 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.