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 on one or more products and opens their product detail pages.
3. After visiting one or more product detail pages, the user adds the product they like the most to the shopping cart.

To track conversion events related to an Algolia search query, capture and send the search queryID with the event.

To keep track of queryIDs across pages, include them as URL parameters.

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

Events without a query ID are not considered for most Algolia features. For more information about the types of events accepted by each feature, refer to the Events by features table.

If you’re using the Google Tag Manager connector, refer to the relevant sending events guide on how to track query IDs.

Automatic query ID inference for conversion events

Algolia automatically infers the queryID for a conversion event from an earlier click event if the events share the same user token, app, index, and objectID. This happens when Algolia processes events: no additional configuration is required.

This means manual queryID tracking may not be necessary. However, for best accuracy, set the queryID whenever possible.

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 several 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.

If no queryID is provided, Algolia will attempt to infer it based on an earlier click event that shares the same objectID, app, index, and user token. This ensures more accurate tracking of conversions even when explicit queryID tracking is unavailable.