On this page
You can collect user behavior in the form of events. You can send events to Algolia’s Insights API (this API enables Click and Conversion Analytics, A/B testing, Dynamic Re-ranking, Personalization, and Recommend).
Different events make use of different properties. For some events, you need to perform additional actions before sending them, for example, obtaining the
queryID. The following guidelines will help make the most out of your user events. You can find details about handling
userToken parameters in separate guides.
All events must have an
eventName property. The name can be up to 64 ASCII characters. To maintain a clean data set and maximize the impact of your user events data, you need to establish a naming convention. If you use multiple analytics services next to Algolia Analytics, it’s essential to name events consistently to facilitate analytics aggregation.
Algolia recommends the following practices:
- Use Segment’s object-action framework to name events according to the object users interact with and the interaction type—for example, “Product added to cart”. If a user action can occur on multiple pages, you can distinguish these events by adding the page type to the event name. For example, to distinguish if the product was added from a product-listing page or a product-detail page, you can add: “PDP;Product added to cart” and “PLP;Product added to cart”
- Choose non-technical event names so that every team member can understand and use them
- Capitalize your event names consistently, for example, using title case
Including the correct
All events need to include the name of the targeted Algolia index. For example, if a user clicks or converts on a search result,
indexName is where the results come from. If a user views a filter, the
indexName is where you’ve declared the filter attribute in the
objectIDs for item-based events
If an event occurs on a specific item or set of items (instead of a category of items), you need to include the items’
objectIDs. You can send up to 20
objectIDs in one call.
positions for click events related to Algolia queries
Click events related to searching and browsing require the
positions parameter. This parameter specifies the clicked items’ positions in the results set.
Click positions start at 1. For example, if a user clicks the second and then the fourth result, the
positions parameter would be
[2, 4]. Algolia uses this parameter to calculate the average click position.
Sending multiple types of events
You should send as many different click and conversion events as required to reflect meaningful user behavior. For example, you could send conversion events when a product is added to a wish list and when the product is bought.
- A user searches for “ps5”, then buys it. This is a converted search.
- Another user searches for “ps5”, adds it to their wish list, then buys it. This is also a converted search. It doesn’t count any differently towards the conversion rate because the user engaged in two conversion behaviors on the same search.
When first sending events, you should validate that Algolia receives the events you expect. The validating events guide outlines the tools and methods you can use.