Guides / Sending events / Implementing events

Sending Events from Your Back End

On this page

You can send events from your back end to the Algolia Insights API, which can be helpful in these cases:

To send events as they occur, consider sending them from your front end.

Provide accurate timestamps for events

If you send historical events or send events in batches, it’s important to associate each event with an accurate timestamp. If you don’t provide a timestamp, all events use the current timestamp.

The timestamp is expressed as miliseconds since the Unix epoch (Unix time). For more information, see the API reference for the timestamp parameter.

Sending historical data

To accelerate the data collection, you can send events from the last four days to Algolia. This allows you to use Algolia features like Click and Conversion Analytics, Personalization, and Recommend sooner. To make fewer API calls, consider sending historical events in batches.

  • You can only send historical events to Algolia Insights from the last four days.
  • For click and conversion events, the timestamp must be within one hour of the corresponding search event.

Sending events in batches

If you don’t want to send user events as they occur, you can send multiple events in batches with the send-events method of the Insights API client, or the REST API directly.

If you want to send events from a JavaScript back end, use the search insights library version 2.2.0 or newer, or the REST API directly.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

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

$response = $insights->sendEvents(array(
    array(
        'eventType' => 'click',
        'eventName' => 'Product Clicked',
        'index' => 'products',
        'userToken' => 'user-123456',
        'objectIDs' => array('9780545139700', '9780439784542'),
        'timestamp' => 1654160209291,
        'queryID' => '43b15df305339e827f0ac0bdc5ebcaa7'
    ),
    array(
        'eventType' => 'view',
        'eventName' => 'Product Detail Page Viewed',
        'index' => 'products',
        'userToken' => 'user-123456',
        'objectIDs' => array('9780545139700', '9780439784542'),
        'timestamp' => 1654160209291
    ),
   array(
        'eventType' => 'conversion',
        'eventName' => 'Product Purchased',
        'index' => 'products',
         'userToken' => 'user-123456',
        'objectIDs' => array('9780545139700', '9780439784542'),
        'timestamp' => 1654160209291,
        'queryID' => '43b15df305339e827f0ac0bdc5ebcaa7'
    ),
));

Sending events with Algolia’s API clients

You need to install an additional package for JavaScript, iOS, and Android. For installation instructions, see these dedicated pages:

Initialize the Insights client

Copy 
1
2
3
4

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

To send events, you need to use an API key with the search acl

Retrieving the queryID

If you want to send events from your back end, you need the queryID for events related to Algolia queries. The queryID allows you to connect the user event with the search query. With the queryID, you can analyze which search queries lead to search results that users often click.

To retrieve the queryID, perform a search with the clickAnalytics parameter set to true.

Copy 
1
2
3

$res = $index->search('query', [
  'clickAnalytics' => true
]);

After setting the clickAnalytics parameter to true, the queryID is returned in the API response. The queryID is unique for every search. In a search-as-you-type implementation, every keystroke sends a search request. Consequently each keystroke has its own queryID. For accurate Click and Conversion Analytics, always use the latest queryID with the API clients.

Not all conversion events originate from a search results page where you can access the required parameters, including the queryID and the indexName. For example, a user could add an item to the shopping cart from a product detail page. In this case, you need to track the parameters manually.

Guide Track the QueryID for Conversion Events

User interactions related to querying Algolia have a queryID parameter. You can send these events when users interact with search results, category pages, or related items from an Algolia index.

Use the appropriate API methods to send events performed after a search:

In the following example, a user searched for an item and clicked on a search result. The API client sends a click event with the name Product Clicked.

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

You need to enter the following parameters:

  • userToken: a unique identifier for the user, for example, user-123456.

  • eventname: the name of the event, for example, Product Clicked.

  • indexname: the Algolia index from where the clicked search results are from, for example, products.

  • objectids: a list with IDs that identify the clicked results, for example, [9780545139700].

  • positions: a list with the clicked results’ positions in the search results, for example, [7].

  • queryid: an identifier for the last search request. For more information, see Retrieving the queryID.

In the following example, a user added two products to their wishlist. The API client sends a conversion event with the name Product Wishlisted.

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

You don’t need to provide the positions parameter for conversion events. Otherwise, provide the same parameters as for click events.

Sending events unrelated to Algolia queries

You can send user events that aren’t directly connected to querying an Algolia index. These events can be used to enable Algolia’s Personalization and Recommend features. For example, if users browse a category page, you can send a Filter Viewed event.

Events that aren’t connected to querying an Algolia index don’t have a queryID parameter. You should send these events to Algolia Insights, even if you don’t plan on using Personalization or Recommend right away.

You can send these events unrelated to Algolia queries:

The events viewedFilters and clickedFilters require a filters parameter instead of the objectIDs parameter.

Send view events

In the following example, a user viewed a category page corresponding to the filter category:best-sellers. A Category Page Viewed event is sent.

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

Send click events unrelated to Algolia queries

In the following example, a user clicked on a product without searching for it, for example, on a product detail page. A Product Clicked event is sent.

Copy 
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 unrelated to Algolia queries

In the following example, a user purchased a product without performing a search first. A conversion event Product Purchased is sent.

Copy 
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?