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.

POST v1/event
{  
  “channel” : “<string>”,

  “identifiers” :  
  [            
    {
    “name” : “<string>”,
    “value” : “<string>” 
    }
  ],

  “events” : 
  [
    { 
    “code” : “<string>”, 
    “timestamp” : “<time

    “attributes” : 
    [
      {
      “name” : “<string>”,            
      “value” : “<string>”,  
      “type” : “<string>” 
      }        
    ]
    }
  ] 
}

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.