Best Practices for Sending Events

Every time one of your users engages in meaningful behavior like clicking on a search result, you can track it by sending an event to Algolia. The engine uses click and conversion events to calculate Click and Conversion Analytics. Click and Conversion Analytics form the foundation for more advanced features like A/B Testing and Dynamic Re-Ranking. Algolia also uses events for Personalization.

The REST API that you send these events to is called the Insights API. For this reason, Algolia refers to these events as “Insights events.” For Click and Conversion Analytics and the features that depend on them to be accurate, you need to correctly capture every relevant event.

These best practices help to ensure you’re tracking your user behavior as accurately as possible. There are separate guides for how to send events using the InstantSearch libraries and API clients.

Planning which events to track

Before sending events, it’s critical to understand your users’ behaviors and plan which ones you want to track. Without pre-analysis and planning, you could end up with a messy, inconsistent corpus of user data that will make Click and Conversion Analytics and features that rely on them inaccurate.

Though it’s geared towards the Personalization feature, the guide on planning which user behaviors to gather outlines what to consider when planning. Even if you aren’t planning on implementing Personalization right away, it’s helpful to consider sending events as if you were. Doing so lets you implement Personalization with a robust corpus of well-formatted user data if you decide to.

Naming events consistently

Establishing good naming conventions makes it easier for you and your team to:

• understand the associated behavior for each of your events,
• maintain a clean and readable codebase,
• and leverage analytics data for Personalization.

If you use other analytics services and Algolia Analytics, it’s essential to adopt a consistent naming convention. If you don’t, aggregating your analytics data will be difficult.

Algolia recommends the following practices:

• Use the Object Action Framework: name events according to their interacted object and interaction type, for example, “Product Viewed”.
• Keep your event names simple.
• Make your event names readable for non-technical team members.
• Use “Proper Case” for event names (capitalize every word).

These are strong recommendations, not requirements. There are only two requirements for event names: they must be at most 64 characters long and must contain only ASCII characters.

To see what the recommended naming conventions look like in practice, check out the example events in the guide on capturing user behavior as events.

Capturing all necessary information

If you don’t include all necessary information for an event, the API and API clients respond with an error. But, you could include the information incorrectly and not receive an error.

Including userToken

All events need to include a userToken that identifies the user performing the behavior behind the event. Algolia uses this token to perform query aggregation and build user-specific affinity profiles for Personalization. You should always send pseudonymous or anonymous userTokens.

Including the correct indexName

All events need to include the name of the targeted index. For example, if a user clicks or converts on a search result, the indexName is the index’s name where the result comes from. If a user views a filter, the indexName is where you’ve declared the filter attribute in the attributesForFaceting.

Including queryID for search-related events

You can send click and conversion events that are and aren’t search-related. Suppose a user searches for “baby yoda”, then clicks on a product detail page, then buys a “baby yoda” toy. These are search-related click and conversion events. A user could also buy a dozen eggs weekly without searching for them first. This isn’t a search-related conversion.

Algolia uses search-related events for Click and Conversion Analytics and Personalization. Events that aren’t related to searches are used for Personalization only.

If an event occurs after a search request, it needs to include the queryID—the search request’s unique identifier. Given the as-you-type nature of Algolia search, if your user types five characters, this generates five queries and, therefore, five queryIDs. To accurately calculate click-through and conversion rates and user affinity profiles, you should use the queryID from the last search response you receive before the user clicks or converts.

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

Including positions for search-related click events

Search-related click events require the positions parameter. This parameter specifies the clicked items’ positions in the results set. For example, if a user clicks the second and then fourth result, the positions parameter would be [2, 4]. Algolia uses this parameter to calculate the average click position.

Sending multiple types of events

Algolia encourages you to send as many different click and conversion events as reflect meaningful user behavior. For example, you could send conversion events for both wishlisting a product and buying it.

However, Algolia only calculates one overall click-through-rate for all click events following a search and one overall conversion rate for all conversion events following a search. If you’re sending multiple types of clicks or conversions, it’s important to keep this in mind when looking at click-through and conversion rates. These rates represent the percentage of searches that resulted in any clicks or conversion, respectively.

For example, suppose a user searches for “ps5”, then buys it. This counts as a converted search. Suppose another user searches for “ps5”, then adds it to their wishlist, 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.

Validating events

When first sending events, you should validate that Algolia is receiving the events as you expect. The guide on validating events outline the tools and methods you can use.