Send Click and Conversion Events with an API Client
On this page
If you are not using InstantSearch, you’ll have to send the events using one of our API Clients. All API Clients have methods to make sending events as simple as possible, requiring only one line of code.
We recommend sending click and conversion events using InstantSearch if you have an InstantSearch implementation.
We’re going to take an online bookshop as an example.
We’ll send click and conversion events for our user, which we identify with a
The scenario will be as followed: our user, John, has an account with our online bookshop, with a unique user ID of
John starts to look for the latest Harry Potter book.
When he starts typing, each keystroke executes a query on Algolia’s servers, which returns the relevant search results.
Luckily, John will only need two keystrokes for all Harry Potter books to show up.
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.
Capturing conversion events
If your UI enables the user to go directly to a conversion point, make sure that you are capturing all relevant events that precede the conversion. For example, if you’ve set up one-click buy as a conversion, you need to process both the click and conversion events before proceeding with the actual sale.
Install the Search-Insights Library
Some of our InstantSearch libraries require you to install our
search-insights library in order to make use of the analytics feature.
For installation instructions, please see their respective pages:
Retrieving the queryID
Every set of search results contains a unique
queryID. When sending click and conversion events, we always use the latest
- The first keystroke (for the character ‘H’) has
- The second key stroke (for the characters ‘Ha’) has
You need to set
clickAnalytics=true in your search parameters for the
queryID to be included in the search results.
1 2 3 $res = $index->search('query', [ 'clickAnalytics' => true ]);
userToken in this example are all fake. Don’t copy-paste these examples, but change them according to your needs!
Sending Click Events
In his search, John has received all of the Harry Potter books, in chronological order (book 1 to book 7). Since he wants the last one in the series (number 7), he clicks this item with
9780545139700 (this is the ISBN-13 code of the book) at
position number seven of his results.
At this point, we have to send an event using the ClickedObjectIdsAfterSearch method of our API Client.
We named our click event
The name of an event is used for your convenience to keep events manageable, even when you send a lot of different events. Make it descriptive so you can instantly identify it.
The API key you use to send events must have the
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'], , 'cba8245617aeace44' );
Sending Conversion Events
Within the context of search
When John sees the Harry Potter books in his search results, he decides to add the last two books of the series to his favorites. Book number six has an objectID of
9780439785969 in our system and book seven has an objectID of
9780545139700 (both are the ISBN-13 codes of the books). For our bookshop, adding a product to the favorites is the action we designated as our system’s conversion event.
So we add to the results page a conversion event. When sending a conversion event, we don’t need to send the position of the converted object with it. Other than that, we have to send the exact same data as we sent with the click event we just sent.
In this example, we called our conversion event
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' );
Outside the context of search
The above code works well if you are sending a conversion event directly from the search page. It works because the search page contains the
index name and the
objectID. However, when sending a conversion event, you’re often not on the search page.
For example, if we consider a conversion to be whenever a user adds a product to the cart, this may happen anywhere, such as the detail page of a product. If this is the case, we need to pass the
queryID from the search page to the detail page.
We wrote a guide on using