Publish events in a batch when you expect high volumes of events. Processing a large number of events in a single API call helps to avoid delay and network congestion that might occur if you process high event volumes with a series of separate API calls.
You might also want to publish events as a batch to more efficiently process events that occur regularly over time, but are not time critical. Processing as a batch avoids consuming network resources with repeated API calls to Acoustic Exchange.
Publish multiple events as a simple batch
To publish multiple events in a simple batch, make a POST call to the v1/event API. Structure the request payload as a list of event descriptions that include properties for the event channel, one or more identifiers, and event attributes.
Next, add the multiple events to the JSON payload as a series of event descriptions. Each event description must define the identifiers that Exchange can use to identify the specific individual associated with the event. For example, an email address or cookieId is a typical identifier.
Each event description must also specify the event code that indicates the type of event, a time stamp, and various attributes that describe the event. The event description can also identify the channel in which you detected the event. You can also define the channel at the batch level if all events in the batch are observed in the same channel.
The diagram illustrates the general structure of the JSON payload for publishing events as a simple batch.
- Call POST <base URL>/v1/event.
See POST /v1/event for call details, including an example of how to build the JSON payload.
Publish multiple events as a compound batch
Publish events as a compound batch of related events when you can expect multiple events to be initiated by the same individual at or about the same time. Publishing such a group of events enables you to maintain any relationships and dependencies between the events.
The most common example of related events is the cart abandonment event. The act of abandoning a cart generates the following events.
- Cart abandonment – aggregate (ibmcartAbandonment)
- Cart abandonment – item (ibmcartAbandonmentItem)
An abandoned cart establishes a parent-child relationship between the aggregate event and the item events. The abandoned cart might include multiple items, each described by various attributes. Publishing the aggregate and item events as a single batch can make it easier to analyze and report on the separate events as different aspects of the same customer interaction.
To publish multiple related events, call POST v1/event API. Structure the request payload as a list of identifiers and the events that are related through the identifier.
Next, build the JSON payload in the POST request as a list of one or more identifiers. Associate the related event descriptions with each identifier. Associating multiple related events with a single identifier clearly associates all of the events with the specific individual who initiated them.
The series of identifiers is contained as an array within the top-level eventbatch property. Placing the identifiers under eventbatch makes it possible to list multiple groups of related events.
With each identifier, the related event descriptions must each define the event code that indicates the type of event, a time stamp, and various attributes that describe the specific event. The event description can also identify the channel in which the event occurred. You can define the channel at the batch level if all of the events in the batch occurred in the same channel.
The diagram illustrates the general structure of the JSON payload that is required to publish events as a compound batch.
- Call POST <base URL>/v1/event.
See POST /v1/event for call details, including an example of how to build the JSON payload.