Click and conversion events - Algolia

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

Click and conversion events capture user interactions in your Algolia experience as structured data. Event data improves your analytics and ranking. Accurate click and conversion events help Algolia measure performance and optimize results. Events are also required for NeuralSearch, Recommend, Personalization, Dynamic Re-Ranking, Query Categorization, and revenue analytics. Without click and conversion events, these features can’t function. To see which event methods each feature uses, see Event types.

Focus on events after search or browse requests

The most important events to consider are those that occur after a search or browse request. For example:

Searches and suggestions: requests with a search query.
Category, navigation, and brand pages: requests with an empty search query but with applied filters.

To associate an event with a specific request, events must include a queryID parameter. Without queryID, Algolia can’t link the event to the originating search or browse request. For some conversion events, Algolia can infer the queryID from an earlier click event. For implementation details, see Keep track of query IDs. Events that include a queryID help Algolia determine if results were useful to users.

Basic events flow

User searches or visits a category page (powered by Algolia)
Your frontend sends a request to the Search API
- The request includes these parameters:
  - userToken: to identify users (pseudonymously)
  - clickAnalytics: true: to return queryID
Search API returns results
- The response includes queryID, object IDs of the matching records, and positions.
User clicks an item, adds it to the cart, or converts in another way
Your frontend sends an event to the Insights API
- Include at least these properties in search-related events:
  - userToken
  - queryID
  - objectIDs

For some conversion events, Algolia can infer the queryID automatically. For details, see Keep track of query IDs. Some event types need more properties. For more details, see also the Insights API reference.

Events that don’t follow a search or browse request still matter. Examples include clicks on product recommendations in an email. These signals help Recommend and Personalization.

Use one stable user identity

The userToken identifies a visitor or signed-in user. Keep it stable during a session. If your privacy model allows it, keep it stable across sessions too. A consistent user identity is essential for analytics and Personalization. You must send the same userToken with your search requests and events.

Before you send userToken, decide how Algolia should treat identity across sessions, devices, and login states:

Pre- and post-login behavior: use the same userToken before and after login if those events belong to one user.
Cross-device identity: use the same userToken across devices if the same user signs in on each one. This often uses a persistent ID from your customer data platform (CDP).
Per-session identity: generate a new anonymous userToken for each session if each session should count as a new user.

Before you send events

Understand how to maintain a consistent userToken.
Understand how the queryID flows from a search request to events.
Identify every interface where users interact with Algolia results or recommendations.

Choose an implementation path

Now choose how you want to send events and validate them.