To offer guidance for publishing and subscribing to event data, UBX provides a list of events that IBM recognizes as typical activities in common business situations. IBM refers to these events as recognized events.

Different business applications view and track customer and entity interactions in different ways. Each application can observe different interactions and record data for different attributes for each interaction. Because UBX provides a way to view customer actions across multiple applications, it establishes a standard framework for describing typical business interactions. This framework is described in the UBX event catalog.

The event catalog lists various identifier and descriptive attributes that event publishers can use to describe an event. As an event publisher, you can provide values for all of the standard event attributes, or for only few of them. However, some attributes are required of all events.

Event publishers might not provide values for every possible attribute in an event. Endpoints that subscribe to events must design their systems to ignore missing values in the JSON payload that UBX provides when it delivers the event data to the subscribing endpoint.

Event types

IBM defines several types of recognized events and organizes them into classes that are
based loosely on the channel in which the events are observed.

IBM defines the following event types.

  • Web Events
  • Email Events
  • Mobile Events
  • Social Events
  • SMS Events
  • Contact Center Events
  • Aggregate Events

IBM also recognizes custom events that are defined by IBM Business Partners, but only after
consultation and agreement on the event name, event code, and support for event attributes. Such
consultation helps ensure that UBX can correctly recognize and process the data that the custom
event promises to deliver.

Custom events

If IBM recognized events do not adequately describe the event data that an endpoint can
provide, the endpoint can define a custom event.

Endpoints that define custom events typically define custom event attributes. However, the
endpoint must use caution when it defines an event code for a custom event. Event publishers cannot
use an event code that is already used by an IBM recognized event. To avoid potential confusion and
errors, consult with IBM before defining a custom event.

Endpoints that subscribe to custom events must consult with the event publisher to determine the
event attributes that they can expect.

Event publishers cannot add custom event attributes to an IBM recognized event.

Event attributes

Every event that you publish to UBX 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 event subscribers and UBX 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. The event notification might also include certain
recommended attributes that are considered best practice attributes. The publishing endpoint might
also include other attributes that IBM considers general attributes.

IBM requires specific event attributes to distinguish between events, facilitate identity
enhancement by the UBX Identity Service, and to properly represent the event in the UBX user
interface. Some descriptive attributes of published events, specifically, the event code and event
name, are defined when an endpoint registers the event with UBX.

IBM reserves specific property names for recognized events. When you register and publish a
recognized event, use only the reserved property names.

Required event attributes

IBM requires that you define specific attributes for all published events. IBM applies
Depending on the type of event, or on the specific event, IBM might impose more attribute
requirements.

IBM requires that you define the following attributes for all published events, including IBM
recognized events and custom events.

  • 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 IBM assigned to the event. IBM 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.

JSON Required Description
POST v1/event
{  
  “channel” : “<string>”,
YES

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.

  “identifiers” :  
  [            
    {
    “name” : “<string>”,
    “value” : “<string>” 
    }
  ],
Required for Individual events. One or more unique name-value pairs that can be associated with a specific individual and
only that individual.
  “events” : 
  [
    { 
    “code” : “<string>”, 
    “timestamp” : “<time
YES

IBM defines the event code to identify the specific event. You must use the IBM 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.

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

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.

Best practices for event attributes

IBM has identified various event attributes that can be added to most event definitions
to enhance the potential insights that UBX users can derive from the event notification.

Best practice attributes are based on the experience of IBM and IBM 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.
channelType string

Owned

Paid

Classify a channel as owned or paid media.
connectionSpeed string 4G Wireless connection speed.
contactConsent string

email|mobile|sms, opt-in|opt-out

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.
idPrivacy string

Analytics

Personalization

Engagement

Join

Any

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.
interactionId string  

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.

interactionType string

Revenue

Non-Revenue

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.
subChannel string

SMS

Web

Live Chat

Facebook

(Typical examples. Not an inclusive list.)

A more granular descriptor of the channel where an event occurred.
type string

email

cookieid

UBX 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.

Join The Discussion

Your email address will not be published. Required fields are marked *