API Reference / API Methods / Insights / Send Events
Required API Key: any key with the search ACL
Method signature
$insights->sendEvents(array events)

// Send a single event
$insights->sendEvent(array event)

About this method

You’re currently reading the JavaScript API client v4 documentation. Check the migration guide to learn how to upgrade from v3 to v4. You can still access the v3 documentation.

You’re currently reading the Ruby API client v2 documentation. Check the migration guide to learn how to upgrade from v1 to v2. You can still access the v1 documentation.

Send a batch of events.

While you can use sendEvent to send a single event, it’s best to use the dedicated method for each event type:

These methods require the necessary parameters for each event type.

sendEvents is useful when sending a batch of different event types, such as historical data.

Examples

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' => 'clickEventName',
        'index' => 'indexName',
        'userToken' => 'user-id',
        'objectIDs' => array('objectID1', 'objectID2'),
        'timestamp' => 1652976203596,
        'queryID' => 'queryID1'
    ),
    array(
        'eventType' => 'view',
        'eventName' => 'viewEventName',
        'index' => 'indexName',
        'userToken' => 'user-id',
        'objectIDs' => array('objectID1', 'objectID2'),
        'timestamp' => 1652976203596
    ),
   array(
        'eventType' => 'conversion',
        'eventName' => 'Product Purchased',
        'index' => 'indexName',
         'userToken' => 'user-id',
        'objectIDs' => array('objectID1', 'objectID2'),
        'timestamp' => 1652976203596,
        'queryID' => 'queryID1'
    ),
));

Parameters

events
type: list of event
Required

An array of event objects

events ➔ event

eventType
type: string
Required

An eventType can be a click, a conversion, or a view.

eventName
type: string
Required

A user-defined string used to categorize events.

Format: any ASCII character, except control points with a length between 1 and 64.

index
type: string
Required

Name of the targeted index.

Format:: same as the index name used by the search engine.

userToken
type: string
Required

A user identifier.

Depending on if the user is logged-in or not, several strategies can be used from a sessionId to a technical identifier.

You should always send pseudonymous or anonymous userTokens.

Format: [a-zA-Z0-9_-=/+]{1,128}

timestamp
type: int64
default: now()
Optional

Time of the event expressed in milliseconds since the Unix epoch.

queryID
type: string
Optional

Algolia queryID. This is required when an event is tied to a search (see clickAnalytics).

Format: [a-f0-9]{32}.

It can be found in the Search API results response.

objectIDs
type: array
Optional

An array of up to 20 index objectIDs.

An event can’t have both objectIDs and filters at the same time.

filters
type: array
Optional

An array of filters. Limited to 10 filters.

Format: ${attribute}:${value}, like brand:apple.

An event can’t have both objectIDs and filters at the same time.

positions
type: []int
Optional

Position of the click in the list of Algolia search results. Click positions start at 1, not 0.

This field is required if a queryID is provided. You must provide one position for each objectID.

The position value must be absolute, not relative, to the result page. For example, when clicking on the third record of the second results page, assuming 10 results per page, the position should be 13. Since page starts at 0, you can use the following formula: $positionOnPage + $page * hitsPerPage.

Only include this parameter when sending click events.

For InstantSearch implementations, this position is available through the hit.__position attribute.

Response

No response

Did you find this page helpful?