Keep track of query IDs

Often, conversions start with a search query and finish outside the search results page. For example, consider this sequence of user events on an ecommerce website:

1. User searches for a product or browses a category page.
2. User clicks one or more products and opens their product detail pages.
3. After visiting one or more product detail pages, user adds the product they like the most to the shopping cart.

You can track this as a conversion event related to an Algolia query.

Connect the conversion event to the search query with a queryID parameter, which uniquely identifies an Algolia search query. To keep track of query IDs across pages, it’s best to include them as URL parameters.

To track conversions unrelated to a previous search, you can send a conversion event without a queryID.

Get the queryID for every search

To generate a queryID with every search, set the clickAnalytics parameter to true.

If you’re using an API client, run:

1
2
3
$res = $index->search('query', [
  'clickAnalytics' => true
]);

1
2
3
results = index.search('query', {
  clickAnalytics: true
})

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

1
2
3
4
res = index.search(
    'query',
    {'clickAnalytics': True}
)

1
2
3
4
5
6
7
8
let query = Query("query")
  .set(\.clickAnalytics, to: true)

index.search(query: query) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
index.Search(
  new Query("query") {
    ClickAnalytics = true
  }
);

1
2
3
4
index.search(
  new Query("query")
    .setClickAnalytics(true)
);

1
2
3
4
index.Search(
  "query",
  opt.ClickAnalytics(true),
)

If you’re using InstantSearch or Autocomplete, set the insights option to true:

Use InstantSearch or Autocomplete to track the queryID for conversion events

InstantSearch and Autocomplete keep track of the queryID when users click search results. When sending conversion events, search-insights automatically includes the queryID in the event payload if you pass inferQueryID: true for each call.

Track the queryID as a URL parameter

You can add the queryID as a URL parameter to the URL of the product detail page. For example, on your InstantSearch search results page:

1
2
3
4
5
6
7
8
search.addWidgets([
  instantsearch.widgets.hits({
    templates: {
      item: (item, { html }) => 
        html`<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 v-slot:item="{ item }">
    <a href="/product.html?queryID={{item.__queryID}}">
      ...
    </a>
  </template>
</ais-hits>

To read the queryID from the URL, you can use the URL API:

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

const queryID = searchParams.get('queryID')

Tracking the queryID with URL parameters is the best way to ensure that conversion events match the correct search. For example, users might open several product detail pages from your category page or search results. This pattern is sometimes called page parking.

When you use URL parameters to keep track of the query ID, follow SEO best practices. For more advice, read the article URL parameter handling in the Search Engine Journal.

Track the queryID in cookies or local storage

You could track the queryID in a cookie, localStorage, or sessionStorage.

For example, to store the latest queryID in the browser’s local storage:

1
2
3
4
5
// Write `queryID` to local storage
localStorage.setItem("queryID", queryID);

// Read `queryID` from local storage
let queryID = localStorage.getItem("queryID");

This example only stores one queryID from the last search query that the user performed. If the user has multiple product detail pages open from previous searches, the conversion event won’t have the correct queryID.

Storing the queryID in a cookie or the browser’s local storage may require your users’ consent.

Send the conversion event

To send the conversion event, use the convertedObjectIDsAfterSearch method.