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)

// Supported since search-insights@2.2.0
// See https://github.com/algolia/search-insights.js#batch-events for more information.
aa('sendEvents', [
  {
    eventType,
    eventName,
    userToken,
    ...
  }
]);

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

About this method

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 JavaScript 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 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

Read the Algolia CLI documentation for more information.

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

1
2
3
4
5
6
7
8
9
10
// Supported since search-insights@2.2.0
// See https://github.com/algolia/search-insights.js#batch-events for more information.
aa('sendEvents', [
  {
    eventType,
    eventName,
    userToken,
    ...
  }
]);

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": "clickEventName",
        "index": "indexName",
        "userToken": "user-id",
        "timestamp": 1666627211068,
        "objectIDs": ["objectID1", "objectID2"],
        "queryID": "queryID1",
        "positions": [17, 19]
      },
      {
        "eventType": "view",
        "eventName":"viewEventName",
        "index": "indexName",
        "userToken": "user-id",
        "timestamp": 1666627211068,
        "objectIDs": ["objectID1", "objectID2"]
      },
      {
        "eventType": "conversion",
        "eventName": "Product Purchased",
        "index": "indexName",
        "userToken": "user-id",
        "timestamp": 1666627211068,
        "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
val insights = ClientInsights(
    applicationID = ApplicationID("YourApplicationID"),
    apiKey = APIKey("YourSearchOnlyAPIKey")
)

val eventClick = InsightsEvent.Click(
    eventName = EventName("clickEventName"),
    indexName = IndexName("indexName"),
    userToken = UserToken("user-id"),
    timestamp = 1666627211052L,
    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 = 1666627211052L,
    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 = 1666627211052L,
    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 = 1666627211056;
  ),
  new InsightsEvent(
    EventType = "view",
    UserToken = "user-id",
    EventName = "viewEventName",
    Index = "indexName",
    ObjectIDs = new List<string>{ "objectID1", "objectID2" },
    Timestamp = 1666627211056;
  ),
  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(1666627211061L);

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

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(1666627211058, 0),
    ObjectIDs: []string{"objectID1", "objectID2"},
    Positions: []int{17, 19},
    QueryID: "queryID1"
  },
  {
    EventType: "view",
    EventName: "viewEventName",
    Index: "indexName",
    UserToken: "user-id",
    Timestamp: time.Unix(1666627211058, 0),
    ObjectIDs: []string{"objectID1", "objectID2"}
  },
  {
    EventType: "conversion",
    EventName: "Product Purchased",
    Index: "indexName",
    UserToken: "user-id",
    Timestamp: time.Unix(1666627211058, 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(1666627211073L)
  )

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

  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(1666627211073L)
  )
  
  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 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

This method doesn't return a response.

Did you find this page helpful?