🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
API client / Methods / Insights
Required API Key: any key with the search ACL
Method signature
$insights->sendEvents(array events)

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

We released a new version of the PHP API client in public beta. Read the beta documentation for more information.

We released a new version of the Java API client in public beta. Read the beta documentation for more information.

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.

About this method

Send a list of events in a single request.

Sending multiple events in a batch can be useful when:

You can include up to 1,000 events in a single request.

When you’re sending historical events, make sure to set correct timestamps for all events, or else every event will have the same timestamp.

For sending real-time events, use the dedicated methods instead:

Examples

Read the Algolia CLI documentation for more information.

The following example sends three events for the same user: one click event, one view event, and one conversion event.

For more information about initializing the Insights client aa, see Initialize the Insights client.

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
37
$insights = Algolia\AlgoliaSearch\InsightsClient::create(
    'YourApplicationID',
    'YourSearchOnlyAPIKey'
);

$response = $insights->sendEvents(array(
    // `clickedObjectIDsAfterSearch`
    array(
        'eventType' => 'click',
        'eventName' => 'Example Clicked',
        'index' => 'YourIndexName',
        'userToken' => 'user-123456',
        'objectIDs' => array('objectID-1', 'objectID-2'),
        'timestamp' => 1702044180006,
        'queryID' => 'queryID'
    ),
    // `viewedObjectIDs`
    array(
        'eventType' => 'view',
        'eventName' => 'Example Viewed',
        'index' => 'YourIndexName',
        'userToken' => 'user-123456',
        'objectIDs' => array('objectID-1', 'objectID-2'),
        'timestamp' => 1702044180006
    ),
    // `convertedObjectIDsAfterSearch`
    array(
        'eventType' => 'conversion',
        'eventName' => 'Example Converted',
        'index' => 'YourIndexName',
         'userToken' => 'user-123456',
        'objectIDs' => array('objectID-1', 'objectID-2'),
        'timestamp' => 1702044180006,
        'queryID' => 'queryID'
    ),
  )
);

Parameters

Parameter Description
events
type: array
items: event
Required

An array of event objects

additionalParams
type: { headers?: Record<string, string> }
default: undefined
Optional

This option is available starting from v2.4.0.

Additional parameters to forward to the Insights library. This is useful to pass different credentials per call when using multiple search clients.

1
2
3
4
5
6
7
8
9
10
11
12
aa(
  'sendEvents',
  [
    // …
  ],
  {
    headers: {
      'X-Algolia-Application-Id': 'YourApplicationID',
      'X-Algolia-API-Key': 'YourSearchOnlyAPIKey',
    },
  }
);

events âž” event

Parameter Description
eventType
type: click | conversion | view
Required

Type of the event, either click, conversion, or view.

See also: Event types

eventSubtype
type: addToCart | purchase
Optional

Subtype of the event. For conversion events either addToCart, or purchase. For all other events it should be omitted.

Used to enable Algolia to provide more detailed analytics reports.

eventName
type: string
pattern: [\x20-\x7E]{1,64}
Required

Name of the specific event.

Format: 1-64 ASCII characters, except control characters.

To maximize the impact of your events, use consistent event names and consistent formatting—for example, “Product Added To Cart” (always in title case).

For example, you can adopt Segment’s object-action framework.

index
type: string
Required

Name of the Algolia index.

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

userToken
type: string
pattern: [A-Za-z0-9_=+/-]{1,129}
Required

Anonymous user identifier.

See also: User Token

authenticatedUserToken
type: string
pattern: [A-Za-z0-9_=+/-]{1,129}
Optional

Pseudonymous identifier for authenticated users.

Never include personally identifiable information in user tokens.

See also: User Token

timestamp
type: int64
default: now()
Optional

Time of the event in milliseconds in Unix epoch time. By default, the Insights API uses the time it receives an event as its timestamp.

If you’re not sending events in real time—for example, if you’re doing backend search, it’s important to set correct timestamps. If you’re sending events in batches and you’re not including a timestamp, all events will have the same timestamp.

  • All events: timestamp may be up to 4 days in the past.
  • In addition, for events with queryID: timestamp must be within 1 hour of the corresponding search or browse request.
queryID
type: string
pattern: [a-f0-9]{32}
Optional

Unique identifier for a search query.

A queryID is required for events related to search or browse requests.

If you add clickAnalytics: true as a search request parameter, the queryID is included in the API response.

See also: Keep track of query IDs

objectIDs
type: array
items: string
Optional

List of object identifiers for items of an Algolia index.

You can include up to 20 objectID.

A single event must not include both objectIDs and filters.

objectData
type: array
items: ObjectData
Optional

Extra information about the records involved in the event—for example, to add price and quantities of purchased products.

If provided, must be the same length as objectIDs.

currency
type: string
items:
Optional

If you include pricing information in the objectData parameter, you must also specify the currency as ISO-4217 currency code, such as USD or EUR.

filters
type: array
items: string
pattern: ${attr}:${value}
Optional

List of facet filters.

You can include up to 10 filters.

Format: ${attribute}:${value}—for example, brand:apple. Both the attribute and value in each facet filter must be URL-encoded individually and separated by a :, such as, "discount:10%25".

A single event must not include both objectIDs and filters.

positions
type: array
items: uint
Optional

Positions of the clicked objects in the search results. This property is required for click events with queryID. The first search result has a position of 1 (not 0).

You must provide one position for each objectID.

Algolia uses this parameter to calculate the average click position.

The position is absolute, and not relative, to any results page. For example, if there are 10 results per page, the position of the third record of the second results page is 13. Since page starts at 0, you can use the following formula: $positionOnPage + $page * hitsPerPage.

If you’re using InstantSearch, you can get the position through the hit.__position attribute.

ObjectData

Parameter Description
queryID
type: string
Optional

ID of the query that this specific record is attributable to. Used to track purchase events with multiple items originating from different searches.

See also: Keep track of query IDs

price
type: number | string
Optional

The price of the item. This should be the final price, inclusive of any discounts in effect.

quantity
type: number
Optional

The quantity of the purchased or added-to-cart item. The total value of a purchase is the sum of quantity multiplied with the price for each purchased item.

discount
type: number | string
Optional

Absolute value of the discount in effect for this object, measured in currency.

Response

This method doesn't return a response.

Did you find this page helpful?