Get started with click and conversion events

Events are actions that users take on your app or website. They unlock powerful features, such as recommendations, personalization, smarter search results, and analytics that help you optimize your user experience. With the Insights API, you can capture all important events related to your search and discovery experience.

Events enable these features:

• NeuralSearch

• Algolia Recommend

• Personalization

• Dynamic Re-Ranking

• Query Categorization

• Analytics

• A/B Testing

What are events?

Events represent user interactions with your app or website. They have extra details, like the name, type, and time of the interaction, and user identity.

For more information, see Event properties.

The basic shape of an event is:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  // Event type: click, conversion, or view
  "eventType": "click",
  // Name for the specific event
  "eventName": "Clicked Search Result",
  // Events are related to items from an Algolia index
  "index": "prod_ecommerce_EN",
  // Pseudonymous or anonymous user identifier
  "userToken": "anonymous-xxxxxx-xx-xxx-xxxxxx",
  // Optional: time of the event in milliseconds. By default the current time is used.
  "timestamp": "1673636676000",
  // For search and browse events only: a unique identifier for a search query preceding this event.
  // Generated by Algolia and included in the API response if you set `clickAnalytics: true`.
  "queryID": "43b15df305339e827f0ac0bdc5ebcaa7",
  // List of objectIDs the user interacted with. Can't be used with `filters`.
  "objectIDs": ["item-1"],
  // List of filters the user interacted with. Can't be used with `objectIDs`.
  "filters": "",
  // For click events after search only: the position of the `objectID` in the search results.
  "positions": [1],
}

Start your implementation

The best way to send events to Algolia depends on where you’re sending them from. Algolia provides tools to help you make sure your events have all the necessary details.

Client-side versus server-side events

Usually, it’s best to send events straight from your users’ devices. To do this, see Send events from your frontend on this page.

If you suspect that you’re not collecting enough events—for example, compared to the number of visitors to your website or app, validate your events. If you see a large difference, it might be caused by ad blockers. In this case, consider server-side tracking.

With server-side tracking, your users send events sent to your servers. Then your servers forward the events to the Insights API. To set up server-side tracking, see Send events from your backend on this page.

Upload events from external analytics

You can speed up data collection by uploading events from the last four days. To upload historical events, you can use:

• The sendEvents method with Algolia’s API clients
• The Insights HTTP API

For Algolia Recommend, you can upload a CSV file with events from the last 90 days.

If an event needs a queryID, its timestamp must be within an hour of the related search or browse request. The queryID can’t be from a search event older than four days. For more information, see Event types.

Send click and conversion events from your ecommerce platform

If you’re using any of these ecommerce platforms, you can use the Algolia integrations to send events:

If you’re using a headless ecommerce platform, see Send click and conversion events from your frontend.

Send click and conversion events from your frontend

If you’re using Algolia’s UI libraries, you can use their Insights integrations to send events:

To send events from pages that aren’t search pages, such as a shopping cart, use the search-insights library for web apps, and the Kotlin and Swift API clients API clients for native Android and iOS apps.

If you’re not using Algolia’s UI libraries, use the search-insights library to send click and conversion events.

Collect click and conversion events with customer data platforms or tag managers

These platforms can send events to the Algolia Insights API:

Send click and conversion events from your backend

The Algolia API clients provide methods for sending events to the Insights API. You can also use the API clients to send events in batches or upload events from external analytics.