Every event that you publish to Exchange must define attributes that describe the event. The number and quality of attributes that you include in the event can improve the value of the event notification to subscribers and users.
When an endpoint publishes an event, the call to v1/event typically includes several event attributes. Each attribute specifies a name, value, and data type. The attributes in the event notification must include required attributes and can include certain recommended attributes and general attributes.
Exchange requires specific event attributes to distinguish between events, facilitate identity enhancement by the Exchange Identity Service, and to properly represent the event in the user interface. Some descriptive attributes of published events, for example, the event code and event name, are defined when an endpoint registers the event with Exchange.
Exchange reserves specific property names for recognized events. When you register and publish a recognized event, use only the reserved property names.
Required event attributes
For all published events, including Exchange recognized events and custom events, the requirements include:
- channel Where the event was observed.
- name Name of the type of identifier that is used to identify the individual or entity that initiated the event. For example, emailAddress.
- value The identifier value for the specific event that is being published by the endpoint.
- code The event code that Acoustic Exchange assigned to the event. Acoustic Exchange assigns a unique event code to recognized and custom events.
- Timestamp The date and time when the event was observed. The time must be submitted in ISO-8601 format.
For example, for social event publishers, unique user identifiers such as User ID, User Name (Facebook and Instagram), Twitter Handle, Twitter ID (Twitter), are required attributes that you define as identifiers during endpoint registration and include when you publish events from the endpoint.
The following example illustrates the structure of the JSON payload in the call to v1/event to publish an event.
The type of device or method that the individual uses to interact with the business or service provider.
For example, mobile if the customer used a cell phone. Email, if the customer made an email request.
|Required for Individual events.||One or more unique name-value pairs that can be associated with a specific individual and only that individual.|
Acoustic Exchangedefines the event code to identify the specific event. You must use the Acoustic Exchange event code. Do not create a different one.
The time stamp indicates when the event was observed by the publishing endpoint, not when the endpoint transmits the event notification. The format must be ISO-8601.
The list of attributes that describe the event. The attributes that are included in the JSON package depend on the event.
The attributes section must contain values for all required attributes for the event. You can add other attributes, depending on the information that the business application can gather and report.
Event attributes example
Acoustic Exchange has identified various event attributes that can be added to most event definitions to enhance the potential insights that Acoustic Exchange users can derive from the event notification.
Best practice attributes are based on the experience of Acoustic Exchange and Acoustic Exchange Business Partners.
The examples that are presented are typical values. They do not represent the only values that are possible or acceptable.
|Attribute Name||Data Type||Example (typical)||Description|
|activityCategory||string||Lead Generation||Category for a commercial activity or tactic.|
|activityCode||string||<application specific>||A tracking code for a commercial activity or tactic. Usually associated with the event for attribution purposes.|
|activityName||string||Email outreach||Name of the activity or tactic.|
|appName||string||<any application name>||Name of the application used during the interaction.|
|appVersion||string||<application specific>||Version of the application used during the interaction.|
|assetId||string||<URL>||URL location for a physical asset.|
|browserName||string||Safari||Browser used on the device used during the interaction.|
|browserVersion||string||<browser specific>||Browser version used on the device used during the interaction.|
|campaignCategory||string||Customer retention||Category for a campaign conducted to generate customer interactions.|
|campaignCode||string||<campaign specific>||Tracking code for a campaign conducted to generate customer interactions.|
|campaignName||string||New Year - New Opportunities!||Name of the campaign conducted to generate customer interactions.|
|carrier||string||Verizon||Carrier vendor of a mobile device.|
|Classify a channel as owned or paid media.|
|connectionSpeed||string||4G||Wireless connection speed.|
Not case sensitive.
Example value: sms,opt-out
Indicates that an individual does not want to receive SMS messages.
Communication consent preference for an individual, as recorded by a messaging endpoint.
Indicates channel and preference.
|depth||string||Device screen depth.|
|deviceType||string||Tablet||Type of device used during a customer event.|
Permissible use of identifier as defined by the publisher of the event or identity.
Note: Null defaults to Join.
|initiator||string||Customer||Person or system that initiated the event. You can set the default during event registration.|
|ip||string||<IP address>||IP address of the device that was used during the event.|
Unique identifier for a visit. Sometimes called a session ID. Can be used to connect related events.
For example, if a cookieId identifies a visitor, the interactionId identifies a visit by that person. One person can generate multiple visits, which are distinguished by multiple interactionIds
A null value is acceptable, but you must generate a unique value when you publish the event.
Classification to the event. For example, distinguish between events that generate revenue and events that do not generate revenue.
You can set the default during event registration.
|latitude||string||Event location latitude.|
|locale||string||Event location locale.|
|locationAddress||string||Event location address.|
|locationCity||string||Event location city.|
|locationCountry||string||Event location country.|
|locationName||string||Event location name.|
|locationRegion||string||Event location region.|
|longitude||string||Event location longitude.|
|model||string||<device specific>||Model of the device.|
|offerCategory||string||new customer||Classification category for an offer.|
|offerCode||string||<offer specific>||Offer code, for attribution.|
|offerName||string||10% off Levi's Jeans for kids||Name of the offer.|
|offerType||string||Discount||Type of offer.|
|OS||string||iOS||Operating system of the device used during an event.|
|platform||string||Gmail||Platform or client used on the device during an event.|
|resolution||string||Device screen resolution.|
|stageName||string||Learn||Stage or phase that describes the customer journey status of the event.|
(Typical examples. Not an inclusive list.)
|A more granular descriptor of the channel where an event occurred.|
Acoustic Exchange privilege key mapping for published identifier. Used to join identities by identity type.
|vendor||string||Apple||Vendor of the device used during an event.|
|versionOS||string||8||Operating system version of the device used during an event.|