Capturing User Behavior As Events

User behavior such as clicking on a search result, placing an order, viewing a category page, or even finishing a podcast, all hold meaningful information about the quality of your search and your users themselves. Events let you capture user behavior and send it to Algolia.

At the most foundational level, Algolia uses click and conversion events sent after a search to calculate click-through-rate, conversion rate, and other analytics metrics. Events also power more advanced features like A/B testing, Dynamic Re-Ranking, and Personalization.

This guide outlines the different types of events, which features Algolia uses them for, and what information you must include for each type. Considering which user behavior to send events for is the first step to gathering actionable analytics and building foundations for more advanced search.

You can refer to separate guides for how to send events to Algolia using the front-end libraries and API clients. The Insights REST API lies beneath these clients and provides a single endpoint. For this reason, these events are referred to as “Insights events”.

Because different event types require specific information, it’s best to use the API clients and InstantSearch libraries, which provide distinct methods for sending different event types.

Types of events

There are three main ways of classifying events:

• the type of behavior the user took - view, click, or conversion,
• whether the event occurred on a specific item or items or a category of items,
• and whether the event occurred in direct connection to a search.

These three classifications determine what features Algolia uses the event for and what information you must include when sending the event.

Events tied to user behavior

User behavior falls into three categories: view, click, or conversion. If you are using an API client, there are separate methods for each of these categories.

Deciding on what counts as a conversion or whether a particular click is worth tracking is ultimately up to your use case. To give you a better sense of some of these types of events, you can refer to example events into e-commerce examples and media examples.

Example events

E-commerce example events

View

• Product Viewed: a user viewed a product page.
• Landing Page Viewed: a user viewed a landing page.

Click

• Product Clicked: a user clicked on an item on the home page, a category page, or a newsletter email.
• Search Result Clicked: a user clicked on a search result.
• Filter Clicked: a user clicked on a filter.
• Menu Clicked: a user clicked on a menu item.

Conversion

• Product Bookmarked: a user bookmarked a product.
• Product Liked: a user liked a product.
• Product Recommended: a user recommended a product.
• Product Added to Cart: a user added a product to their cart.
• Product Purchased: a user purchased a product.

Media example events

View

• Article Viewed: a user viewed an article page.

Click

• Article Clicked: a user clicked on an article.
• Ad Clicked: a user clicked on an ad.

Conversion

• Article Read: a user reached the bottom of an article page.
• Article Bookmarked: a user bookmarked an article.
• Article Liked: a user liked an article.
• Article Recommended: a user recommended an article.
• Video Watched: a user watched a video.
• Playlist Followed: a user followed a playlist.
• Author Followed: a user followed an author.
• Brand Followed: a user followed a brand.

Naming events

You can send as many different view, click, and conversion events as are meaningful to your use case. For example, if you consider both recommending an article and bookmarking an article as useful conversions, you should send both.

You can differentiate between these conversion events by providing an eventName. Unlike the eventType, which must be either view, click, and conversion, the eventName can be any ASCII string of up to 64 characters. For example, you could send two conversion events, one with Article Recommended as the eventName and one with Article Bookmarked as the eventName. Refer to the naming guidelines to help you ensure consistency.

While you should send as many types of click and conversion events as are meaningful for your use case, Algolia calculates one overall click-through rate and one overall conversion rate.

Events on items and categories

Views, clicks, and conversions occur either on discrete items or on categories of items. Item-based events include bookmarking an item, viewing a product page, putting a product in a wish list or shopping cart, buying a product, reading an article, and any other events that occur on a specific item. Each event type (view, click, conversion) related to an item also accepts a list of items. For example, you can send a “purchase” conversion event containing the list of items that were purchased together.

Alternatively, you can send events related to a group of items identified by a filter. For example, if a user visits a particular category page, you can capture this as a filter event. Filter events don’t have to be linked to the selection of a facet in the UX. For example, suppose you are sending a campaign targeting a specific brand or product type. If a user clicks on the campaign, you could send a filter event with the brand or product type.

An event can be either item-based or event-based—it can’t be both at the same time.

Events related and unrelated to search

Though Algolia uses click and conversion events on search results to calculate click-through-rate and conversion rate, respectively, many behaviors your users take outside of the context of search capture important information about their affinities. Using events, you can send Algolia user behavior such as:

• what brands, genres, and other categories they prefer,
• what specific items they view, click or convert on, even without a search to get them there.

These Insights API client methods are for events directly related to a search:

• clickedObjectIdsAfterSearch
• convertedObjectIdsAfterSearch

These Insights API client methods are for events not directly related to a search:

• viewedObjectIds
• clickedObjectIds
• convertedObjectIds
• viewedFilters
• clickedFilters

The distinguishing factor for search-related events is that they must always include a queryID. This identifier links events back to the search query they follow.

Using search-related events

Algolia uses search-related events for calculating Click and Conversion Analytics. These Click and Conversion Analytics are used during A/B testing to determine which variant performs statistically significantly better than the other. Search-related clicks and conversion analytics are also used for the Dynamic Re-Ranking feature.

Algolia doesn’t differentiate between different types of click and conversion events when calculating click-through-rate and conversion rate, respectively. In other words, 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.

For example, if you send click events when a user clicks an article and when a user clicks an ad, Algolia calculates click-through-rate as the percentage of searches that resulted in any kind of click. Similarly, if you send conversion events when a user bookmarks a product and when a user adds a product to their cart, the conversion rate reflects the number of searches in which either of these happened. Algolia doesn’t provide separate conversion rates for bookmarking products versus adding products to the cart.

For a click or conversion event to count towards click-through-rate and conversion rate, you must include the queryID as part of the event payload. For more information, please see the FAQ on why some click events aren’t used for click analytics.

Using events to capture user affinities

Whether search-related or not, Algolia can leverage all events to build user affinity profiles, which are fundamental for the Personalization feature.

To reiterate, Algolia uses click and conversion events in the context of a search to calculate Click and Conversion Analytics. These analytics are then used in the A/B testing and Dynamic Re-Ranking features. You can use any events, regardless of whether they’re search-related, when defining your Personalization strategy.

Though Algolia treats all types of click and conversion events the same when calculating click-through-rate and conversion rate, you can weight distinct types of click and conversion events differently for Personalization purposes. For example, you may decide that adding a product to the cart is a stronger conversion signal than bookmarking a product. You can make this distinction when defining the importance of events in your Personalization strategy.

Even if you haven’t decided to use Personalization yet, it’s best to thoughtfully and consistently start collecting events, both search-related and not, as soon as possible. You should send events for any user behavior that you consider relevant to understanding of your users’ affinities. Then, when you decided to use Personalization, you will have a robust corpus of well-formatted user data at your disposal.

If you later decide that a particular event isn’t useful for your Personalization strategy, you don’t have to include it. By tracking as many potentially relevant events as possible, you allow yourself to build a nuanced Personalization strategy.

Insights events (view, click, and conversion) don’t take immediate effect. The delay can range from a few minutes to an hour, depending on whether they are sent after a search or not, and how long after a search they are sent. For precise timeframes, see our page on when Insights events take effect.

Information to include in events

Which information you include when sending events depends on the event type. Regardless of type, all events must include the following:

• event type (view, click, or conversion)
• event name
• related Algolia index—this is particularly important for Personalization to work accurately
• user performing the behavior (sent as userToken)

For any event, you can optionally include the timestamp of when an event occurred. It’s best to include timestamp, especially if you are backfilling events in batches. If you don’t include a timestamp, the API uses the time it receives the event as the timestamp of when it occurred. For an event to be counted in Click and Conversion Analytics, its timestamp must be within one hour of the search it’s related to. To keep the effects of Personalization current, the engine don’t consider events that are older than 90 days.

If you are sending item-based events, you must include the objectID of the items. If you are sending category events, you must include the filter or filters the event occurred on.

When sending search-related events, you must include the queryID of the related search. For search-related, item-based click events, you must include the positions of the item or items that were clicked. The engine uses this parameter to calculate the click position metric.

Remembering what information to include when sending an event can be difficult, which is why it’s best to use the search-insights library in conjunction with InstantSearch. If you aren’t using InstantSearch, you can send events with one of the Insights API Clients. In both cases, these libraries and clients simplify sending the right information for the right event.