To publish an event to Acoustic Exchange, make a POST request to the v1/event API. Acoustic Exchange provides several ways to use v1/event to publish events.
Acoustic Exchange supports two ways to publish events. You can publish events individually in a single POST to v1/event. You can also publish multiple events as a batch in a single API call.
Publishing events as a batch helps to avoid problems with the use and performance of your network resources. By publishing events in a batch, you can better manage high event volumes and more efficiently deliver events to Acoustic Exchange over an extended period.
Acoustic Exchange supports two ways to batch events, depending on the relationship of the events in the batch to each other. The difference between the batching methods determines how you build the JSON payload of the POST request to v1/event. When you publish a batch of events, consider how the events relate to each other, and make the following distinction.
- Simple batch. If the events in the batch are not related to each other in ways that establish dependencies, you can build the JSON payload as a simple set of separate event descriptions, including the identifiers for each event.
- Compound batch. If individual events in the batch are related by a common identifier, build the JSON payload as a list of identifiers and associate the related events under their common identifier. This relationship can occur when a single individual triggers multiple related events during the same interaction with your business solution. Cart events are a common example of such an interaction.
When you publish events in Acoustic Exchange, either individually or in a batch, the JSON payload contains the following properties.
- Channel The channel specifies where the event was observed. For example, specify mobile for events related to your mobile app.
- Identifiers The name and value of one or more identifiers that Acoustic Exchange can use to identify the specific individual who initiated the event. The identifier name must be registered with Acoustic Exchange for your endpoint.
- Timestamp The time when the event occurred, in ISO-8601 format.
- Event code Identifies a specific event that is recognized by Acoustic Exchange. The events that you specify must be registered with Acoustic Exchange for your endpoint. You must specify an event code that is defined by Acoustic Exchange.
- Event attributes Details that describe the event. The attributes must be registered with Acoustic Exchange for your endpoint.
You must specify identifiers that are registered with Exchange. To register an identifier, call POST v1/application or PUT v1/endpoint (for custom endpoints).
To describe an event, you must specify an event code and the event attributes that your business solution supports. You must register the event types and attributes with Acoustic Exchange for your endpoint. To register event types and attributes that you support, call POST v1/eventtype.