API Reference / API Methods / Insights / Send Events

Nov. 12, 2020

Send Events

Required API Key: any key with the settings 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)

// Use the Insights REST API directly to send batched events
// See https://www.algolia.com/doc/rest-api/insights/#push-events for more information

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.sendEvents(JSONArray events)

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

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

About this method

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

You are currently reading the Ruby API client v2 documentation. Check our 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.

The sendEvents method is useful when you want to send a batch of different types of events, for example when sending historical data.

Examples

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

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.user('user-id').send_events(
  [
    {
        eventType: 'click',
        eventName: 'clickEventName',
        index: 'indexName',
        userToken: 'user-id',
        timestamp: 1529055974,
        objectIDs: ['objectID1', 'objectID2'],
        queryID: 'queryID1',
        positions: [17, 19]
      },
      {
        eventType: 'view',
        eventName: 'viewEventName',
        index: 'indexName',
        userToken: 'user-id',
        timestamp: 1521710906,
        objectIDs: ['objectID1', 'objectID2']
      },
      {
        eventType: 'conversion',
        eventName: 'Product Purchased',
        index: 'indexName',
        userToken: 'user-id',
        timestamp: 1528364634,
        objectIDs: ['objectID1', 'objectID2'],
        queryID: 'queryID1'
      }
  ]
)

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 = client.init_insights_client().user('user-id')

insights.send_events(
  [
    {
        "eventType": "click",
        "eventName": "clickEventName",
        "index": "indexName",
        "userToken": "user-id",
        "timestamp": 1529055974,
        "objectIDs": ["objectID1", "objectID2"],
        "queryID": "queryID1",
        "positions": [17, 19]
      },
      {
        "eventType": "view",
        "eventName":"viewEventName",
        "index": "indexName",
        "userToken": "user-id",
        "timestamp": 1521710906,
        "objectIDs": ["objectID1", "objectID2"]
      },
      {
        "eventType": "conversion",
        "eventName": "Product Purchased",
        "index": "indexName",
        "userToken": "user-id",
        "timestamp": 1528364634,
        "objectIDs": ["objectID1", "objectID2"]
        "queryID": "queryID1"
      }
  ]
)

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

let eventClick: InsightsEvent = .click(name: "Product Clicked",
                                       indexName: "indexName",
                                       userToken: "user-id",
                                       queryID: "queryID1",
                                       objectIDsWithPositions: [
                                        ("objectID1", 17),
                                        ("objectID2", 19)
                                       ])


let eventView: InsightsEvent = .view(name: "viewEventName",
                                     indexName: "indexName",
                                     userToken: "user-id",
                                     objectIDs: [
                                      "objectID1",
                                      "objectID2"
                                     ])

let eventConversion: InsightsEvent = .conversion(name: "Product Purchased",
                                                 indexName: "indexName",
                                                 userToken: "user-id",
                                                 queryID: "queryID1",
                                                 objectIDs: [
                                                  "objectID1",
                                                  "objectID2"
                                                 ])

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

val eventClick = InsightsEvent.Click(
    eventName = EventName("clickEventName"),
    indexName = IndexName("indexName"),
    userToken = UserToken("user-id"),
    timestamp = 1529055974L,
    queryID = QueryID("queryID1"),
    resources = InsightsEvent.Resources.ObjectIDs(listOf(ObjectID("objectID1"), ObjectID("objectID2"))),
    positions = listOf(17, 19)
)

val eventView = InsightsEvent.View(
    eventName = EventName("viewEventName"),
    indexName = IndexName("indexName"),
    userToken = UserToken("user-id"),
    timestamp = 1521710906L,
    resources = InsightsEvent.Resources.ObjectIDs(listOf(ObjectID("objectID1"), ObjectID("objectID2"))),
)

val eventConversion = InsightsEvent.Conversion(
    eventName = EventName("Product Purchased"),
    indexName = IndexName("indexName"),
    userToken = UserToken("user-id"),
    timestamp = 1528364634L,
    queryID = QueryID("queryID1"),
    resources = InsightsEvent.Resources.ObjectIDs(listOf(ObjectID("objectID1"), ObjectID("objectID2"))),
)

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

var events = new List<InsightsEvent>(){
  new InsightsEvent(
    EventType = "click",
    UserToken = "user-id",
    EventName = "clickEventName",
    Index = "indexName",
    ObjectIDs = new List<string>{ "objectID1", "objectID2" },
    Positions = new List<uint> { 17, 19 },
    QueryID = "queryID1",
    Timestamp = 1529055974;
  ),
  new InsightsEvent(
    EventType = "view",
    UserToken = "user-id",
    EventName = "viewEventName",
    Index = "indexName",
    ObjectIDs = new List<string>{ "objectID1", "objectID2" },
    Timestamp = 1521710906;
  ),
  new InsightsEvent(
    EventType = "conversion",
    UserToken = "user-id",
    EventName = "Product Detail Page Viewed",
    Index = "indexName",
    ObjectIDs = new List<string>{ "objectID1", "objectID2" },
    QueryID = "queryID1",
  )
};

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

InsightsEvent eventClick =
    new InsightsEvent()
        .setEventType("click")
        .setUserToken("user-id")
        .setEventName("clickEventName")
        .setIndex("indexName")
        .setObjectIDs(Arrays.asList("objectID1", "objectID2"))
        .setPositions(Arrays.asList(17L,19L))
        .setQueryID("queryID1")
        .setTimestamp(1529055974L);

InsightsEvent eventView =
    new InsightsEvent()
        .setEventType("view")
        .setUserToken("user-id")
        .setEventName("viewEventName")
        .setIndex("indexName")
        .setObjectIDs(Arrays.asList("objectID1", "objectID2"))
        .setTimestamp(1521710906L);

InsightsEvent eventConversion =
    new InsightsEvent()
        .setEventType("conversion")
        .setUserToken("user-id")
        .setEventName("Product Purchased")
        .setIndex("indexName")
        .setObjectIDs(Arrays.asList("objectID1", "objectID2"))
        .setQueryID("queryID1");

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
client := insights.NewClient("YourApplicationID", "YourAPIKey")

events := []insights.Event{
  {
    EventType: "click",
    EventName: "clickEventName",
    Index: "indexName",
    UserToken: "user-id",
    Timestamp: time.Unix(1529055974, 0),
    ObjectIDs: []string{"objectID1", "objectID2"},
    Positions: []int{17, 19},
    QueryID: "queryID1"
  },
  {
    EventType: "view",
    EventName: "viewEventName",
    Index: "indexName",
    UserToken: "user-id",
    Timestamp: time.Unix(1521710906, 0),
    ObjectIDs: []string{"objectID1", "objectID2"}
  },
  {
    EventType: "conversion",
    EventName: "Product Purchased",
    Index: "indexName",
    UserToken: "user-id",
    Timestamp: time.Unix(1528364634, 0),
    ObjectIDs: []string{"objectID1", "objectID2"},
    QueryID: "queryID1"
  },
}

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
34
35
client.execute {
  val eventClick = InsightsEvent(
    eventType = "click",
    eventName = "clickEventName",
    index = "indexName",
    userToken = "user-id",
    objectIDs = Some(Seq("objectID1", "objectID2")),
    positions = Some(Seq(17, 19)),
    queryID = Some("queryID1"),
    timestamp = Some(1529055974L)
  )

  val eventView = InsightsEvent(
    eventType = "view",
    eventName = "viewEventName",
    index = "indexName",
    userToken = "user-id",
    objectIDs = Some(Seq("objectID1", "objectID2")),
    timestamp = Some(1521710906L)
  )

  val eventConversion = InsightsEvent(
    eventType = "click",
    eventName = "Product Clicked",
    index = "indexName",
    userToken = "user-id",
    objectIDs = Some(Seq("objectID1", "objectID2")),
    positions = Some(Seq(17, 19)),
    queryID = Some("queryID1"),
    timestamp = Some(1529055974L)
  )
  
  send events Seq(eventClick, eventView, eventConversion)
}
}

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 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,64}
`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 index `objectID`. Limited to 20 objects. 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. This field is required if a `queryID` is provided. One position must be provided 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. Usually, since `page` starts at 0, you can use the following formula: `$positionOnPage + ($page - 1) * hitsPerPage`. Only include this parameter when sending `click` events.

Response

No response

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

PHP

Ruby

JavaScript

Python

Swift

Kotlin

Android

.NET

Java

Golang

Scala

InstantSearch.js

React InstantSearch

Vue InstantSearch

Angular InstantSearch

InstantSearch iOS

InstantSearch Android

Autocomplete

Crawler Configuration API

Index settings and search parameters

A full reference of API Endpoints

Rails

Symfony

Django

Laravel

Crawler

Magento 2

WordPress

Shopify

Salesforce Commerce Cloud B2C

Netlify

Send Events

About this method

Examples

Parameters

events ➔ event

Response

Did you find this page helpful?

On this page