Sending Events with an API Client
On this page
If you are using InstantSearch, it’s best to send events directly through InstantSearch. If you aren’t, you can send click, conversion, and other events using one of the API clients. The API clients provide dedicated methods for each type of event.
This guide uses an online marketplace as an example. It includes code snippets for how to send events when a user clicks on search results or engages in other behaviors you’ve decided are worth tracking. The
userToken values in these examples are placeholders. Be sure to adjust these values for your implementation.
Since you can send events with just a few lines of code, it’s tempting to jump right in and do it. Before that, it’s best to read the best practices for sending events.
Initializing the Insights client
1 2 3 4 $insights = Algolia\AlgoliaSearch\InsightsClient::create( 'YourApplicationID', 'YourSearchOnlyAPIKey' );
search-insights library to send events. For installation instructions, please see their respective pages:
You must use the an API key with the
search ACL to send events.
Sending search-related events
Search-related events must occur within one hour of their search. In other words, after a user searches, the analytics engine only counts events related to that search if they have a
timestamp within one hour of the search. Events must be received by the insights API within four days of their occurrence.
Imagine a user arriving at the marketplace and beginning a search for “harry potter”. Any behavior related to this and other searches, whether it be clicking on a result, wishlisting a result, or eventually making a purchase, should be classified as search-related events.
To properly denote that an event is search-related, you must use the appropriate API methods:
1 2 3 $res = $index->search('query', [ 'clickAnalytics' => true ]);
Once you’ve done this, each results set includes the
queryID field. The
queryID is unique for every search made to Algolia. For example, Algolia returns a new
queryID each time a user appends a new character in a search-as-you-type implementation. In this user’s case:
- The first keystroke (for the character “h”) has
- The second key stroke (for the characters “ha”) has
If the user were to perform the same search at a different time, each query would receive a new unique
queryID. For accurate Click and Conversion Analytics, always use the latest
queryID with the API client methods.
Sending search-related click events
After typing just two characters into the search bar, the user sees all the Harry Potter books in their results set. They’re interested in the last book of the series and click on it.
To track search-related clicks, you need to send events using the
ClickedObjectIdsAfterSearch API client method. This method requires the following parameters:
userToken: This is the user’s unique user identifier, in this example
user-123456. Depending on the client, you may provide this during initialization rather than as a parameter.
eventName: This is up to you—it’s best to follow the naming guidelines. This example uses the
indexName: This is the clicked result’s index. In this case, the name of the index is
objectIDs: These are the clicked results’
objectIDs. The user is interested in the last book in the series, the item with
objectID:9780545139700, the ISBN-13 code of the book. Even if you’re sending only one item, you must send it in an array:
positions: These are the clicked results’ positions in the list of Algolia search results. Like
objectIDs, the parameter expects an array. Since the user’s interested in the last book of a seven-part series and the series are the first seven search results, the position is
queryID: This comes from the response of the last search request as previously described.
1 2 3 4 5 6 7 8 9 10 11 12 $insights = Algolia\AlgoliaSearch\InsightsClient::create( 'YourApplicationID', 'YourSearchOnlyAPIKey' ); $insights->user("user-123456")->clickedObjectIDsAfterSearch( 'Product Clicked', 'products', ['9780545139700'], , 'cba8245617aeace44' );
Sending search-related conversion events
When the user sees the Harry Potter books in their search results, they decide to add the last two books of the series to their wishlist. Book six has an objectID of
9780439785969 and book seven has an objectID of
9780545139700. This example considers wishlisting products as a conversion event.
Unlike sending click events, when sending conversion events, you don’t need to send the converted objects’
positions with it. Other than that, you send the same data as with the previous click event. In this case, the
1 2 3 4 5 6 7 8 9 10 11 $insights = Algolia\AlgoliaSearch\InsightsClient::create( 'YourApplicationID', 'YourSearchOnlyAPIKey' ); $insights->user("user-123456")->convertedObjectIDsAfterSearch( 'Product Wishlisted', 'products', ['9780545139700', '9780439785969'], 'cba8245617aeace44' );
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 implemented a “Buy now” or one-click buy, you need to process both the click and conversion events before proceeding with the actual sale.
While you should send as many types of
conversion events as are meaningful for your use case, Algolia calculates one overall click-through rate and one overall conversion rate.
The previous conversion code snippet works well if you send conversion events directly from the search results page. It works because the search page contains the
queryID, and other necessary information, such as the
index name and the
objectID, to send the event. However, not all click and conversion events originate from the search page, even if they’re related to a search.
For example, a user could add a product to their shopping cart from the product detail page. In this case, you need to pass the
queryID and other necessary information from the search page to the detail page.
There are several solutions to this problem. For web applications, you could use localStorage, cookies, a query string, or other methods. See the guide on keeping track of
queryID for more information.
Sending events unrelated to search
You can also send
conversion, and other events that are unrelated to search. While these events won’t be taken into account when calculating Click and Conversion Analytics they’re useful for the Personalization feature. Personalization relies on user behavior—related or unrelated to search—to build user affinity profiles. Algolia can then use these profiles to personalize results for the individual user.
Even if you aren’t planning on implementing Personalization yet, it’s a good idea to collect these events so that you have a corpus of data ready for you when you do.
While you can only send click and conversion events for behaviors related to search, there is a greater variety of user behavior you can capture that is unrelated to search. Specifically, you can send
view events and events that are related to categories rather than specific items.
For example, if a user decides to browse a particular category page, you can send a
view event for the category, rather than having to provide
objectIDs for all the items on the page. For more information and examples of these event types, please see the guide on capturing user behavior as events.
There are dedicated API methods for each of these events:
These methods require the same parameters as their search-related counterparts. The only difference is that they don’t require a
Sending view events
Here is an example of how to send a view event when a user decides to browse a particular category page. In this case, the category is called
1 2 3 4 5 6 7 8 9 10 $insights = Algolia\AlgoliaSearch\InsightsClient::create( 'YourApplicationID', 'YourSearchOnlyAPIKey' ); $insights->user("user-123456")->viewedFilters( 'Category Page Viewed', 'products', ['category:best-sellers'] );
Sending click events not related to search
A user might click on links to product detail pages or filter products without searching for them first. In that case, you can send click events without any
1 2 3 4 5 6 7 8 9 10 $insights = Algolia\AlgoliaSearch\InsightsClient::create( 'YourApplicationID', 'YourSearchOnlyAPIKey' ); $insights->user("user-123456")->clickedObjectIDs( 'Product Clicked', 'products', ['9780545139700'] );
Send conversion events not related to search
Similarly, a user might buy a product or take another action you’ve designated as a conversion event without making a search first. In that case, you can send conversion events without any
1 2 3 4 5 6 7 8 9 10 $insights = Algolia\AlgoliaSearch\InsightsClient::create( 'YourApplicationID', 'YourSearchOnlyAPIKey' ); $insights->user("user-123456")->convertedObjectIDs( 'Product Purchased', 'products', ['9780545139700'] );