Guides / Sending events / Implementing events

Sending Events from Your Back End

If you want to send historical data to Algolia, if you want to send events in batches, or if you want to process your user events on your back end before sending them to Algolia Insights, you can use Algolia’s API clients.

Sending historical data

To reduce the time to value for features like Personalization, Click and Conversion Analytics, and Recommend, you can send events from the last 4 days to Algolia with one of Algolia’s API clients.

Make sure to use accurate timestamps for historical data. It’s most efficient to send historical events in batches.

Sending events in batches

If you don’t want to send user events as they occur, you can send them in batches. You can use one of the API clients, or the REST API directly.

The following examples send three events for the same user, one click event, one view event, and one conversion event.

Generate timestamps for events

If you send historical data, or want to send events in batches, it’s important to associate each event with an accurate timestamp. If you don’t generate an accurate timestamp, all your user events will have the same timestamp (the current time), which can lead to unexpected outcomes.

For example, Algolia’s Personalization uses affinity profiles based on user events of the past 90 days. If you don’t include timestamps with your historical events, the personalized results can change drastically, once the initial data becomes 90 days old.

Note, that although Personalization uses data based on events from the previous 90 days, you can only send historical events to Algolia Insights from the last 4 days.

The Algolia Insights API expects timestamps in milliseconds since the Unix Epoch. For more information, see the API reference for the timestamp parameter.

Send events in batches using API clients

Use the sendEvents method to send multiple events at once. If you use a JavaScript back end, use the Insights REST API to send events in batches.

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' => 1529055974,
        'queryID' => '43b15df305339e827f0ac0bdc5ebcaa7'
    ),
    array(
        'eventType' => 'view',
        'eventName' => 'Product Detail Page Viewed',
        'index' => 'products',
        'userToken' => 'user-123456',
        'objectIDs' => array('9780545139700', '9780439784542'),
        'timestamp' => 1521710906
    ),
   array(
        'eventType' => 'conversion',
        'eventName' => 'Product Purchased',
        'index' => 'products',
         'userToken' => 'user-123456',
        'objectIDs' => array('9780545139700', '9780439784542'),
        'timestamp' => 1529055974,
        'queryID' => '43b15df305339e827f0ac0bdc5ebcaa7'
    ),
));

Send events in batches using the REST API

You can also directly send events to the Insights REST API which accepts an array of events.

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
34
35
36
curl -X POST \
https://insights.algolia.io/1/events \
-H 'x-algolia-api-key: ${ADMIN_API_KEY}' \
-H 'x-algolia-application-id: ${APPLICATION_ID}' \
-H "Content-Type: application/json" \
-d '{
    "events": [
        {
          "eventType": "click",
          "eventName": "Product Clicked",
          "index": "products",
          "userToken": "user-123456",
          "timestamp": 1529055974,
          "objectIDs": ["9780545139700", "9780439784542"],
          "queryID": "43b15df305339e827f0ac0bdc5ebcaa7",
          "positions": [7, 6]
        },
        {
          "eventType": "view",
          "eventName":"Product Detail Page Viewed",
          "index": "products",
          "userToken": "user-123456",
          "timestamp": 1521710906,
          "objectIDs": ["9780545139700", "9780439784542"]
        },
        {
          "eventType": "conversion",
          "eventName": "Product Purchased",
          "index": "products",
          "userToken": "user-123456",
          "timestamp": 1528364634,
          "objectIDs": ["9780545139700", "9780439784542"],
          "queryID": "43b15df305339e827f0ac0bdc5ebcaa7"
        }
      ]
    }'

When the query is successful, the HTTP response is a 200 OK.

1
2
3
4
{
  "status": 200,
  "message": "OK"
}

Sending events with Algolia’s API clients

You can send user events using Algolia’s API clients. For JavaScript, iOS, and Android, you need to install an additional package. For installation instructions, see these dedicated pages:

Initialize the Insights client

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 parameter.

Retrieving the queryID

If you want to send events from your back end, you need to obtain the queryID for events related to Algolia queries. The queryID is a unique identifier of the search query that 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 click often.

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

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

After setting the clickAnalytics parameter to true, the queryID is in the API response. The queryID is unique for every search. In a search-as-you-type implementation, every letter corresponds to one search and 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.

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.

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: an identifier for the user, for example, user-123456. You can also set the userToken during initialization instead.
  • 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: t list with IDs that identify the clicked results. Even if you’re sending only one objectID, it must be in a list, for example, [9780545139700].
  • positions: A list with the clicked item’s position in the search results, for example, [7].
  • queryID: the queryID corresponding to the last search request. See Retrieving the queryID for more information.

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

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.

Send events unrelated to Algolia queries

You can send user events that aren’t directly connected to querying an Algolia index 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.

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.

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.

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?