Guides / Solutions / Ecommerce / Analytics

Sending Events Using API Clients

You can send click, conversion, and other events that are related and unrelated to Algolia results. While events unrelated to Algolia won’t be taken into account when calculating Click and Conversion Analytics, Dynamic Re-ranking, A/B Testing, they’re useful for the Personalization feature. Personalization can rely on user behavior on any channels 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.

If you’re looking to send events to Algolia using the InstantSearch or integrations such as Magento, Shopify, Google Tag Manager & Segment, please refer to the guide Getting Started on Sending Events.

Insight events and implementation overview

  Events related to Algolia results Events unrelated to Algolia results
Examples of Ecommerce events Views, Clicks and Conversion on:
• Product Listing Page (Search, Browse, or Landing Page) powered by Algolia.
• Promotional Banners powered by Algolia
Views, Clicks and Conversion on:
• Recommendations in Product page.
• Emails, Push notifications and Newsletter.
• User Preference settings.
• Product Listing Page not powered by Algolia.
Used by features like Dynamic Re-ranking
Click and Conversion analytics
A/B testing
Personalization
Personalization
Send events with InstantSearch or API Clients API Clients only
queryID Require queryID tracking Don’t require queryID
Algolia Insights API Methods clickedObjectIdsAfterSearch
convertedObjectIdsAfterSearch
viewedObjectIds
clickedObjectIds
convertedObjectIds
viewedFilters
clickedFilters
convertedFilters
Implementation Steps using API Clients 1. Initialize Insight Library
2. Set clickAnalytics and userToken query parameters in each query
3. Retrieve and Track queryID
4. Send events with the following parameters:
   • queryID
   • userToken
   • eventName
   • indexName
   • objectIDs
   • positions(click events only)
1. Initialize Insight Library
2. Send events with the following parameters:
   • userToken
   • eventName
   • indexName
   • objectIDs

The implementation process is slightly different for events related and unrelated to Algolia results. Both processes require you to initialize the Insights client first.

Once you initialize the Insights client, please jump to the relevant section to get started.

Initializing the Insights client

1
2
3
4
$insights = Algolia\AlgoliaSearch\InsightsClient::create(
  'YourApplicationID',
  'YourSearchOnlyAPIKey'
);

The JavaScript, iOS, and Android API clients require you to install the search-insights library to send events. For installation instructions, please see their respective pages:

You must use an API key with the search ACL to send events.

There are three steps after instantiating the Insights library.

1. Set clickAnalytics and userToken query parameters in each query

  • Set the clickAnalytics query parameter to true – Once you’ve enabled click analytics, each results set includes the queryID field.

  • Set the userToken query parameter – For query aggregation, Search Analytics, and Personalization to work properly, the analytics engine needs to uniquely identify each of your users. You need to set the userToken parameter to tell Algolia which user is searching.

1
2
3
4
$index->search('query', [
  'clickAnalytics' => true,
  'userToken' => '123456'
])

During client initialization

1
2
3
4
5
6
$config = \Algolia\AlgoliaSearch\Config\SearchConfig::create('YourApplicationID', 'YourSearchOnlyAPIKey');
$config->setDefaultHeaders([
    'X-Algolia-UserToken' => '123456',
]);

$client = \Algolia\AlgoliaSearch\SearchClient::createWithConfig($config);

Set the X-Forwarded-For header

If you perform the query from your back end, set the X-Forwarded-For header to forward Algolia the user’s IP address. Please make sure to replace the IP address in the snippet with the actual IP address of your end user.

1
2
3
4
5
$index = $client->initIndex('your_index_name');

$res = $index->search('query string', [
    'X-Forwarded-For' => '94.228.178.246',
]);

Here are some examples of userToken:

  • User ID associated with an account on your system (Recommended)
  • Cookie associated with an account for the user, for example, Google and Adobe Analytics
  • Algolia cookie (sent by default with events)

If you’re using the JavaScript API Client, refer to the following guides on user identifiers:

If you’re sending events related and unrelated to Algolia results, please make sure that the user token is consistent for both types of events.

2. Retrieve and track the queryID

Once you’ve enabled click analytics, each results set includes the queryID field. The queryID is unique for every query 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 aef12442b87e97ac as queryID.
  • The second key stroke (for the characters “ha”) has cba8245617aeace44 as queryID.

For accurate Click and Conversion Analytics, always use the latest queryID with the API client methods. Please read the following guide about the best practice to keep track of the query ID.

You can send events one by one, as soon as they occur, or in batches. Read the guide on the best practice of sending current or older events in batches. You may also want to send historical data as events, which you can do more efficiently in batches.

Algolia-related events must occur within one hour of their search. In other words, the analytics engine only counts events related to that query if they have a timestamp within one hour of running a query to Algolia. Events must be received by the insights API within four days of their occurrence.

For any results that come from querying Algolia’s API, there are dedicated API methods for each of these events:

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'],
  [7],
  'cba8245617aeace44'
);

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.

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'
);

Send events unrelated to Algolia results

Once you instantiate the Insight Library, you can start sending events. You can send events one by one, as soon as they occur, or in batches. Read the guide on the best practice of sending current or older events in batches. You may also want to send historical data as events, which you can do more efficiently in batches.

There are dedicated API methods for each of these events:

These methods require the same parameters as their counterparts. The only difference is that they don’t require a queryID.

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']
);
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']
);
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']
);

Did you find this page helpful?