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:

• 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. By default the current time is used.
  "timestamp": "1673636676",
  // 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 search and browse events only: the position of the `objectID` in the search results.
  "positions": [1],
}

Which events should you send?

Since every digital experience is different, the Algolia Insights API accepts different event types.

For a suggested starting point, see Plan your implementation.

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.

Client-side tracking has a drawback: Ad blockers. Up to 40% of your users might use ad blockers, which can prevent client-side tracking tools from working.

Another option is server-side tracking. With this method, events are first sent to your servers, and then forwarded 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.

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 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:

If you want to send events from pages that aren’t search pages, like a shopping cart, use the search-insights library. You can also use this library if you’re not using Algolia’s UI libraries (Autocomplete and InstantSearch).

You can use the Kotlin and Swift API clients to send click and conversion events for native Android or iOS applications.

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.