Send Personalization Events

Introduction

If you’re not using InstantSearch, you’ll have to send events using one of our API Clients. All API Clients have methods to make sending events as simple as possible, requiring only a few lines of code.

We recommend sending personalization events using InstantSearch if you have an InstantSearch implementation.

Personalization events are not taken into account right away. User profiles will be updated roughly every 10 minutes.

The use-case scenario

We’re going to take an online bookshop as an example. The scenario will be as follows: our user, John, has an account with our online bookshop, with a unique user ID of user-123456.

We want John to take a lot of actions on our website. The more he does, the more accurate his preferences will be. So we’ll send events on many different actions, like clicking, buying, adding to cart, etc. If you track only buy events, you’ll get less data than if you also send click and add-to-cart events.

So, John starts looking for children’s books like Harry Potter books. Tomorrow he looks for books on European history. And for the next weeks and months, he consistently focuses on history and children’s books. We want to capture all af that activity, so that whenever John searches, his results reflect those preferences.

The analytic-to-personalization workflow

Before getting started with personalization, you should already have implemented click and conversion analytics. That’s because you want to start collecting click-analytic data as soon as possible. Analytics data gets you focused on the basics - to improve your users’ search experience by making the best configuration and data formatting choices.

This is the preferred workflow: first, put click analytics in place; only after that do you want to to think about personalizing your users’ results. Additionally, click events create a foundation for A/B testing.

Our insights API, which manages all analytics and personalization events, reflects this workflow in its naming convention and parameters. Some methods are designed to track a user’s activity after a search (these have the suffix “AfterSearch”), and some methods are used only within the personalization context.

Insights events (click, conversion, view) used for analytics and/or personalization do not take immediate effect. The delay can range from 10 to 60 minutes depending on how long after the search they are sent. For precise times, see our page on when Insights events take effect.

We organize our event process to align with this workflow, by separating events into search-related events and non-search-related events.

Some events are meaningful only within the context of a search. These are typically click and conversion events. As you’ll see, the main two methods for sending search-related events are:

Because these events can be traced back to a query, they require a queryID.

Getting the queryID

Every keystroke executes a query on Algolia’s servers and returns a set of results. Every set of results contains a unique queryID.

When sending personalization events, we always use the latest queryID. A query for “Harry Potter” is broken down as follows:

  • The first keystroke (for the character ‘H’) has aef12442b87e97ac as queryID.
  • The second key stroke (for the characters ‘Ha’) has cba8245617aeace44 as queryID.
  • The third … and so on.

You need to set clickAnalytics=true in your query parameters for the queryID to be included in the search results. The queryID, objectID, and userToken in this example are all fake. Don’t copy-paste these examples, change them according to your needs!

Sending Click Events

Whenever John clicks on a result, which is a search-related activity, we have two options:

  1. Send an event using the ClickedObjectIdsAfterSearch method, which tracks the Click Through Rate (CTR) and can be used for personalization purposes.

  2. Send an event using the ClickedObjectIds method, which only contributes towards personalization purposes.

Since this tutorial is on personalization, we can use both. However, we’ll want to choose the first option because it will do both click analytics and personalization in the same call.

In this example, the objectID of the clicked-on book is 9780545139700. We named our click event book_click_on_search_page.

1
2
3
4
5
6
7
8
9
10
11
12
$insights = Algolia\AlgoliaSearch\InsightsClient::create(
  'YourApplicationID',
  'YourSearchOnlyAPIKey'
);

$insights->user("user-123456")->clickedObjectIDsAfterSearch(
  'book_click_on_search_page',
  'my_online_bookshop_index',
  ['9780545139700'],
  [7],
  'cba8245617aeace44'
);

You can also send click events only for personalization by using the same function without the “AfterSearch” suffix. See ClickedObjectIds.

Sending Conversion Events

For conversion events, you have the same choice - either you send a conversion with a query id or not. If there is no query id, then the event serves only to record personalization data; if you send it with the query id, then you get both personalization and analytics.

Let’s say John sees Harry Potter books in his search results and decides to add the last two books to his favorites. For our bookshop, adding a product to the favorites is the action we had designated as a conversion event. Book number six has an objectID of 9780439785969, and book number seven has an objectID of 9780545139700.

We want to send a conversion that feeds both conversion analytics and personalization: ConvertedObjectIdsAfterSearch. In this example, we called our conversion event book_favorite_on_search_page.

1
2
3
4
5
6
7
8
9
10
11
$insights = Algolia\AlgoliaSearch\InsightsClient::create(
  'YourApplicationID',
  'YourSearchOnlyAPIKey'
);

$insights->user("user-123456")->convertedObjectIDsAfterSearch(
  'book_favorite_on_search_page',
  'my_online_bookshop_index',
  ['9780545139700', '9780439785969'],
  'cba8245617aeace44'
);

You can also send conversion events only for personalization by using the same function without the “AfterSearch” suffix. See ConvertedObjectIds.

Therefore, to continue sending conversion events for personalization without impacting your conversion rate, you’ll need to do the following:

1
2
3
4
5
6
7
8
9
10
$insights = Algolia\AlgoliaSearch\InsightsClient::create(
  'YourApplicationID',
  'YourSearchOnlyAPIKey'
);

$insights->user("user-123456")->convertedObjectIDs(
  'book_favorite_on_search_page',
  'my_online_bookshop_index',
  ['9780545139700']
);

When sending a conversion event, you’re not always on the search page (such as a product detail page). Therefore, you need to pass the queryID to the detail page. We wrote a guide to show you how to use query parameters to pass the queryID.

You can’t use search-related events in all cases. To see the difference, ask yourself, “Is this event related to my Algolia search results?” For example, “Is it a click on a search result?” or “Am I converting after searching?”. If not, then you’ll want to use our non-search-related type of events - all methods that do not have an “AfterSearch” suffix:

We’ve already discussed the first two event types in the previous section. Let’s see what you can do with the view event type.

Sending View Events

Finally, we might want to capture every product detail page that John visits. Capturing views is simpler than clicks and conversion because there is only one method: ViewedObjectIds. For example, john views the newest book on World History with the objectID 9780545139700 (this is the ISBN-13 code of the book)

In this example, we named our click event book_view_on_detail_page.

1
2
3
4
5
6
7
8
9
10
$insights = Algolia\AlgoliaSearch\InsightsClient::create(
  'YourApplicationID',
  'YourSearchOnlyAPIKey'
);

$insights->user("user-123456")->viewedObjectIDs(
  'book_view_on_detail_page',
  'my_online_bookshop_index',
  ['9780545139700']
);

Sending Filter Events

If you want to collect facet/filter activity, you have three methods for that.

Clicking on Facets

Here, John clicks on the “history” facet. We’ll use the ClickedFilters method with the event name book_click_on_filter.

1
2
3
4
5
6
7
8
9
10
$insights = Algolia\AlgoliaSearch\InsightsClient::create(
  'YourApplicationID',
  'YourSearchOnlyAPIKey'
);

$insights->user("user-123456")->clickFilters(
  'book_click_on_filter',
  'my_online_bookshop_index',
  ['category:history']
);

Viewing Facets

Here, John goes to a category page that displays history books with photos and descriptions for browsing. We’ll use the ViewedFilters method with the event name book_view_filter_page.

1
2
3
4
5
6
7
8
9
10
$insights = Algolia\AlgoliaSearch\InsightsClient::create(
  'YourApplicationID',
  'YourSearchOnlyAPIKey'
);

$insights->user("user-123456")->viewedFilters(
  'book_view_filter_page',
  'my_online_bookshop_index',
  ['category:history']
);

Converting Facets

Here, John goes to a category page. In some personalization strategies, this is also a conversion. We’ll have to use the ConvertedFilters method with a custom the event name: book_view_conversion_filter_page.

1
2
3
4
5
6
7
8
9
10
$insights = Algolia\AlgoliaSearch\InsightsClient::create(
  'YourApplicationID',
  'YourSearchOnlyAPIKey'
);

$insights->user("user-123456")->convertedFilters(
  'book_view_conversion_filter_page',
  'my_online_bookshop_index',
  ['category:history']
);

Did you find this page helpful?