API client / Methods / Insights

May. 25, 2023

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)

insights.send_events(Array events)

# Send a single event
insights.send_event(Hash event)

aa('sendEvents', Array events, additionalParams);

insights.send_events(list events)

# Send a single event
insights.send_events(dict event)

insightsClient.sendEvents(_ events: [Event],) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

// Send a single event
insightsClient.sendEvent(_ event: Event,) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

suspend fun ClientInsights.sendEvents(
  events: List<Event>,
): HttpResponse

// Send a single event
suspend fun ClientInsights.sendEvent(
  event: Event,
): HttpResponse

insights.SendEventsAsync(IEnumerable<Event> events)

// Send a single event
insights.SendEventsAsync(Event event)

insights.sendEventsAsync( List<Event> events)

// Send a single event
insights.sendEventAsync(Event event)

client.SendEvents(_[]Event__ events)

// Send a single event
client.SendEvent(_Event__ event)

send events Seq(events events)

// Send a single event
send event (event event)

See code examples

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.

If you want to send a list of different events in a single batch, such as importing historical data, or if you’re sending events from your backend, you can use the sendEvents method to send multiple 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, consider using the dedicated methods, which makes sure that every event has the required parameters:

Guides Get started with click and conversion events

Send click and conversion events with InstantSearch

Send click and conversion events with Autocomplete

API Insights API

Examples

Read the Algolia CLI documentation for more information.

To use this method in JavaScript, you need to install the search-insights library.

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

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

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

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::Insights::Client.create('YourApplicationID', 'YourSearchOnlyAPIKey')

insights.send_events(
  [
    {
        eventType: 'click',
        eventName: 'Clicked Example',
        index: 'YourIndexName',
        userToken: 'user-123456',
        timestamp: 1685462629989,
        objectIDs: ['objectID-1', 'objectID-2'],
        queryID: 'queryID',
        positions: [17, 19]
      },
      {
        eventType: 'view',
        eventName: 'Viewed Example',
        index: 'YourIndexName',
        userToken: 'user-123456',
        timestamp: 1685462629989,
        objectIDs: ['objectID-1', 'objectID-2']
      },
      {
        eventType: 'conversion',
        eventName: 'Converted Example',
        index: 'YourIndexName',
        userToken: 'user-123456',
        timestamp: 1685462629989,
        objectIDs: ['objectID-1', 'objectID-2'],
        queryID: 'queryID'
      }
  ]
)

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
// This requires the `search-insights` library version 2.2.0 or later
aa('sendEvents', [
  // `clickedObjectIDsAfterSearch`
  {
    userToken: 'user-123456',
    eventType: 'click',
    eventName: 'Clicked Example',
    index: 'YourIndexName',
    queryID: 'queryID',
    objectIDs: ['objectID-1', 'objectID-2'],
    positions: [17, 19],
  },
  // `viewedObjectIDs`
  {
    userToken: 'user-123456',
    eventType: 'view',
    eventName: 'Viewed Example',
    index: 'YourIndexName',
    objectIDs: ['objectID-1', 'objectID-2'],
  },
  // `convertedObjectIDsAfterSearch`
  {
    userToken: 'user-123456',
    eventType: 'conversion',
    eventName: 'Converted Example',
    index: 'YourIndexName',
    queryID: 'queryID',
    objectIDs: ['objectID-1', 'objectID-2'],
  },
]);

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
insights = InsightsClient.create(
    'YourApplicationID',
    'YourSearchOnlyAPIKey'
)

insights.send_events(
  [
    {
        "eventType": "click",
        "eventName": "Clicked Example",
        "index": "YourIndexName",
        "userToken": "user-123456",
        "timestamp": 1685462629986,
        "objectIDs": ["objectID-1", "objectID-2"],
        "queryID": "queryID",
        "positions": [17, 19]
      },
      {
        "eventType": "view",
        "eventName":"Viewed Example",
        "index": "YourIndexName",
        "userToken": "user-123456",
        "timestamp": 1685462629986,
        "objectIDs": ["objectID-1", "objectID-2"]
      },
      {
        "eventType": "conversion",
        "eventName": "Converted Example",
        "index": "YourIndexName",
        "userToken": "user-123456",
        "timestamp": 1685462629986,
        "objectIDs": ["objectID-1", "objectID-2"]
        "queryID": "queryID"
      }
  ]
)

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
38
39
40
41
let insightsClient = InsightsClient(appID: "YourApplicationID", apiKey: "YourSearchOnlyAPIKey")

// `clickedObjectIDsAfterSearch`
let eventClick: InsightsEvent = .click(
  eventName: "Clicked Example",
  indexName: "YourIndexName",
  userToken: "user-123456",
  queryID: "queryID",
  objectIDsWithPositions: [
    ("objectID-1", 17),
    ("objectID-2", 19),
  ])

// `viewedObjectIDs`
let eventView: InsightsEvent = .view(
  eventName: "Viewed Example",
  indexName: "YourIndexName",
  userToken: "user-123456",
  objectIDs: [
    "objectID-1",
    "objectID-2",
  ])

// `convertedObjectIDsAfterSearch`
let eventConversion: InsightsEvent = .conversion(
  eventName: "Converted Example",
  indexName: "YourIndexName",
  userToken: "user-123456",
  queryID: "queryID",
  objectIDs: [
    "objectID-1",
    "objectID-2",
  ])

let events = [eventClick, eventView, eventConversion]

insightsClient.sendEvents(events) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

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
val insights = ClientInsights(
  applicationID = ApplicationID("YourApplicationID"),
  apiKey = APIKey("YourSearchOnlyAPIKey")
)

// `clickedObjectIDsAfterSearch`
val eventClick = InsightsEvent.Click(
  eventName = EventName("Clicked Example"),
  indexName = IndexName("YourIndexName"),
  userToken = UserToken("user-123456"),
  timestamp = 1685462629971L,
  queryID = QueryID("queryID"),
  resources = InsightsEvent.Resources.ObjectIDs(listOf(ObjectID("objectID-1"), ObjectID("objectID-2"))),
  positions = listOf(17, 19)
)

// `viewedObjectIDs`
val eventView = InsightsEvent.View(
  eventName = EventName("Viewed Example"),
  indexName = IndexName("YourIndexName"),
  userToken = UserToken("user-123456"),
  timestamp = 1685462629971L,
  resources = InsightsEvent.Resources.ObjectIDs(listOf(ObjectID("objectID-1"), ObjectID("objectID-2"))),
)

// `convertedObjectIDsAfterSearch`
val eventConversion = InsightsEvent.Conversion(
  eventName = EventName("Converted Example"),
  indexName = IndexName("YourIndexName"),
  userToken = UserToken("user-123456"),
  timestamp = 1685462629971L,
  queryID = QueryID("queryID"),
  resources = InsightsEvent.Resources.ObjectIDs(listOf(ObjectID("objectID-1"), ObjectID("objectID-2"))),
)

insights.sendEvents(events = listOf(eventClick, eventView, eventConversion))

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
38
var insights = new InsightsClient(
  "YourApplicationID",
  "YourSearchOnlyAPIKey"
);

var events = new List<InsightsEvent>(){
  // `clickedObjectIDsAfterSearch`
  new InsightsEvent(
    EventType = "click",
    UserToken = "user-123456",
    EventName = "Clicked Example",
    Index = "YourIndexName",
    ObjectIDs = new List<string>{ "objectID-1", "objectID-2" },
    Positions = new List<uint> { 17, 19 },
    QueryID = "queryID",
    Timestamp = 1685462629896;
  ),
  // `viewedObjectIDs`
  new InsightsEvent(
    EventType = "view",
    UserToken = "user-123456",
    EventName = "Viewed Example",
    Index = "YourIndexName",
    ObjectIDs = new List<string>{ "objectID-1", "objectID-2" },
    Timestamp = 1685462629896;
  ),
  // `convertedObjectIDsAfterSearch`
  new InsightsEvent(
    EventType = "conversion",
    UserToken = "user-123456",
    EventName = "Converted Example",
    Index = "YourIndexName",
    ObjectIDs = new List<string>{ "objectID-1", "objectID-2" },
    QueryID = "queryID",
  )
};

insights.sendEventsAsync(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
37
38
39
40
InsightsClient insights = DefaultInsightsClient.create(
  "YourApplicationID",
  "YourSearchOnlyAPIKey"
);

// `clickedObjectIDsAfterSearch`
InsightsEvent eventClick =
  new InsightsEvent()
  .setEventType("click")
  .setUserToken("user-123456")
  .setEventName("Clicked Example")
  .setIndex("YourIndexName")
  .setObjectIDs(Arrays.asList("objectID-1", "objectID-2"))
  .setPositions(Arrays.asList(17 L, 19 L))
  .setQueryID("queryID")
  .setTimestamp( < %= DateTime.now.strftime('%Q') % > L);

// `viewedObjectIDs`
InsightsEvent eventView =
  new InsightsEvent()
  .setEventType("view")
  .setUserToken("user-123456")
  .setEventName("Viewed Example")
  .setIndex("YourIndexName")
  .setObjectIDs(Arrays.asList("objectID-1", "objectID-2"))
  .setTimestamp( < %= DateTime.now.strftime('%Q') % > L);

// `convertedObjectIDsAfterSearch`
InsightsEvent eventConversion =
  new InsightsEvent()
  .setEventType("conversion")
  .setUserToken("user-123456")
  .setEventName("Converted Example")
  .setIndex("YourIndexName")
  .setObjectIDs(Arrays.asList("objectID-1", "objectID-2"))
  .setQueryID("queryID");

List < InsightsEvent > events = Arrays.asList(eventClick, eventView, eventConversion);
insights.sendEventsAsync(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
client := insights.NewClient("YourApplicationID", "YourAPIKey")

events := []insights.Event{
  // `clickedObjectIDsAfterSearch`
  {
    EventType: "click",
    EventName: "Clicked Example",
    Index: "YourIndexName",
    UserToken: "user-123456",
    Timestamp: time.Unix(1685462629900, 0),
    ObjectIDs: []string{"objectID-1", "objectID-2"},
    Positions: []int{17, 19},
    QueryID: "queryID"
  },
  // `viewedObjectIDs`
  {
    EventType: "view",
    EventName: "Viewed Example",
    Index: "YourIndexName",
    UserToken: "user-123456",
    Timestamp: time.Unix(1685462629900, 0),
    ObjectIDs: []string{"objectID-1", "objectID-2"}
  },
  // `convertedObjectIDsAfterSearch`
  {
    EventType: "conversion",
    EventName: "Converted Example",
    Index: "YourIndexName",
    UserToken: "user-123456",
    Timestamp: time.Unix(1685462629900, 0),
    ObjectIDs: []string{"objectID-1", "objectID-2"},
    QueryID: "queryID"
  },
}

res, err := client.SendEvents(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
client.execute {
  val eventClick = InsightsEvent(
    eventType = "click",
    eventName = "Clicked Example",
    index = "YourIndexName",
    userToken = "user-123456",
    objectIDs = Some(Seq("objectID-1", "objectID-2")),
    positions = Some(Seq(17, 19)),
    queryID = Some("queryID"),
    timestamp = Some(1685462629994L)
  )

  val eventView = InsightsEvent(
    eventType = "view",
    eventName = "Viewed Example",
    index = "YourIndexName",
    userToken = "user-123456",
    objectIDs = Some(Seq("objectID-1", "objectID-2")),
    timestamp = Some(1685462629994L)
  )

  val eventConversion = InsightsEvent(
    eventType = "conversion",
    eventName = "Converted Example",
    index = "YourIndexName",
    userToken = "user-123456",
    objectIDs = Some(Seq("objectID-1", "objectID-2")),
    queryID = Some("queryID"),
    timestamp = Some(1685462629994L)
  )

  send events Seq(eventClick, eventView, eventConversion)
}

Parameters


            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.

Copy
aa(
  'sendEvents',
  [
    // …
  ],
  {
    headers: {
      'X-Algolia-Application-Id': 'YourApplicationID',
      'X-Algolia-API-Key': 'YourSearchOnlyAPIKey',
    },
  }
);

events ➔ event

`eventType`	type: click \| conversion \| view Required The type of the event, either `click`, `conversion`, or `view`. Related: API client methods
`eventName`	type: string pattern: `[\x20-\x7E]{1,64}` Required The name of the specific event. Format: 1-64 ASCII characters, except control characters. To maximize the impact of your events, you should 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 The 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,128}` Required A pseudonymous or anonymous user identifier. Never include personal identifiable information in user tokens. Related: user token
`timestamp`	type: int64 default: now() Optional The 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. The Algolia Insights API accepts events from up to 4 days in the past. Timestamps for click and conversion events must be within 1 hour of the corresponding search or browse request.
`queryID`	type: string pattern: `[a-f0-9]{32}` Optional A 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. Related: Keep track of query IDs
`objectIDs`	type: array items: string Optional An array 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`.
`filters`	type: array items: string pattern: `${attr}:${value}` Optional An array of facet filters. You can include up to 10 filters. Format: `${attribute}:${value}`—for example, `brand:apple`. Each facet filter string must be URL-encoded, such as, `"discount:10%25"`. A single event must not include both `objectIDs` and `filters`.
`positions`	type: array items: uint Optional The position 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.

Response

This method doesn't return a response.