An event is a specific activity or interaction that a business application can detect at a specific time and that can be associated with a customer identifier. The application publishes the event to Acoustic Exchange through a REST API call that includes descriptive attributes in a JSON payload. Each type of event is registered with Acoustic Exchange so that subscribing applications can readily interpret the event data.
Acoustic Exchange recognizes various common events that occur in different channels. For example, for commercial web sites, Acoustic Exchange recognizes Cart Abandonment as a distinct type of event. For mobile engagements, Acoustic Exchange recognizes when an individual installs a mobile app on a mobile phone. For email communications, an event is generated when the recipient clicks a link in the email message.
When you register an event, you can define one or more attributes that describe the event activity. You must also specify at least one attribute that can be used to identify the individual that initiated the event. For example, for an email link click event, you might define an attribute that provides the email address of the individual who clicked the link.
Events also include a timestamp to indicate when the event was observed.
Each event is assigned an event code. Acoustic Exchange uses the event code to identify the specific event.
The difference between push and pull-type data exchange
The distinction between exchanging data as PUSH or PULL depends on how the data moves between an endpoint and Acoustic Exchange. The way that data flows between endpoints and Acoustic Exchange determines how the Acoustic Exchange APIs are called or implemented by the endpoint.
Acoustic Exchange recognizes the following syndication types. Depending on the types of data exchanges that your product or solution supports, you can select more than one data syndication type.
- Event publisher
- All Exchange endpoints publish event data to Exchange as a PUSH-type event publisher. Publishing events to Exchange also requires an API call to Exchange.
- Event consumer
- An endpoint that receives event data that Exchange sends as soon as it is available is considered a PUSH-type event consumer.
- Event consumer: PULL
- An endpoint that receives event data only when it specifically requests the data from Exchange is considered a PULL-type event consumer.
- Audience producer: PULL
- Exchange calls APIs that are hosted and implemented by the source endpoint. When the source endpoint indicates that data is available, Exchange pulls audience data from the source endpoint.
- Audience producer: PUSH
- The source endpoint calls APIs that are hosted by Exchange. When the source endpoint determines that it can make audience data available, the source endpoint pushes data to Exchange. For example, to avoid potential security concerns, business applications that are physically installed in a local computer network as an on premise application typically connect to Acoustic Exchange as a push-type endpoint.
- Audience consumer: PULL
- The destination endpoint calls APIs that are hosted by Exchange. When the destination endpoint is ready to accept audience data, it pulls data from Exchange. Business applications that are physically installed in a local computer network as an on premise application typically connect to Exchange as a pull-type endpoint.
- Audience consumer: PUSH
- Exchange calls APIs that are hosted and implemented by the destination endpoint. Exchange pushes audience data to the endpoint when the data is shared by an audience source. Often, cloud-based business applications (also called SaaS applications) connect to Exchange as a push-type audience consumer.
API examples
Audience producer: PUSH
| Action | API |
|---|---|
| Add a list to Acoustic Exchange that identifies segments that are ready for export to Acoustic Exchange. | POST /v1/endpoint/{endpointId}/segments |
| Replace a list on Acoustic Exchange that identifies segments that are ready for export to Acoustic Exchange. | PUT /v1/endpoint/{endpointId}/segments |
| Clear the list on Acoustic Exchange that identifies segments that are ready for export to Acoustic Exchange. | DELETE /v1/endpoint/{endpointId}/segments |
| Remove a specific segment from the list on Acoustic Exchange that identifies segments that are ready for export to Acoustic Exchange. | DELETE /v1/endpoint/{endpointId}/segments/{segmentId} |
| Upload audience data and metadata to Acoustic Exchange in CSV format. | POST /v1/jobs/{jobId}/data |
| Get a list of one or more jobs, identified by category, endpoint ID, or status. | GET /v1/jobs/{jobCategory} |
| Get a specific job, identified by job category and job ID. | GET /v1/jobs/{jobCategory}/{jobId} |
Audience consumer: PUSH
| Action by the endpoint | API (Acoustic Exchange calls) |
|---|---|
|
Provide a list of audiences that are already available as a destination audience and that can receive additional audience data or that can be modified by replacing or adding to existing data. |
GET /v1/segments |
| Provide details about a specific destination audience. | GET /v1/segments/{segmentId} |
| Create an audience on the destination endpoint. | POST /v1/segments |
| Add audience data to the specified destination audience, either as a new audience or to existing audience. | POST /v1/segments/{segmentId}/data |
| Replace all existing data in the specified destination audience with new audience data. | PUT /v1/segments/{segmentId}/data |
| Delete specific records in the specified destination audience. | DELETE /v1/segments/{segmentId}/data |
Audience producer: PULL
| Action by the endpoint | API (Acoustic Exchange calls) |
|---|---|
|
Provide a list of audiences (segments) that are available to provide audience data. |
GET /v1/segments |
| Provide details about a specific source audience. | GET /v1/segments/{segmentId} |
| Upload available data to Acoustic Exchange. If no data is available, Acoustic Exchangerequests that you create a data upload job. | GET /v1/segments/{segmentId}/data |
| Create a job to upload audience data when it becomes available. | POST /v1/jobs |
| Provide job status. Acoustic Exchange polls for job status. It continues to poll when data upload begins and until the upload completes. | GET /v1/jobs/{jobCategory} |
| Upload the requested audience data. | POST /v1/jobs/{jobId}/data |
Audience consumer: PULL
| Action | API |
|---|---|
| Add a list to Exchange that identifies segments that are ready for import to Exchange. | POST /v1/endpoint/{endpointId}/segments |
| Replace a list on Exchange that identifies segments that are ready for import to Exchange. | PUT /v1/endpoint/{endpointId}/segments |
| Clear the list on Exchange that identifies segments that are ready for import to Exchange. | DELETE /v1/endpoint/{endpointId}/segments |
| Remove a specific segment from the list on Exchange that identifies segments that are ready for import to Exchange. | DELETE /v1/endpoint/{endpointId}/segments/{segmentId} |
| Pull audience data files from Exchange to a destination endpoint. | GET /v1/jobs/{jobId}/segmentDataFiles/{fileName} |
| Clean up audience data files from Exchange after downloading the data. | DELETE/v1/jobs/{jobId}/segmentDataFiles/{fileName} |
| Mark an audience download job as complete and clean up files. | PUT /v1/jobs/{jobid}/status/complete |