IBM UBX Destination

This destination is currently in beta. If you are interested in joining, let us know!

IBM’s Universal Behavior Exchange (UBX) is an API that allows users to share customer interactions, behaviors, and target audiences among IBM solutions and applications - including the Watson Marketing Portfolio - without the need for custom software integration. In effect, UBX is the “Segment” of IBM’s ecosystem. Once data is routed to IBM, you can send it to any destination in UBX’s portfolio.

NOTE: IBM UBX is currently in beta and this doc was last updated on May 7, 2018. This means that there may still be some bugs for us to iron out and we’re excited to hear your thoughts. If you are interested in joining or have any feedback to help us improve the IBM UBX Destination and its documentation, please let us know!

Getting Started

NOTE: To enable Segment in UBX, navigate to “Endpoints” in the UBX dashboard, select “Register new endpoint”, then select “Segment”. Once you’ve added the Segment endpoint, please reach out to Segment support with your new endpoint’s “endpoint authentication key” for help activating your new endpoint. Note that the endpoint in UBX will not be able to receive Segment data until you have enabled both the destination in the Segment UI and requested activation of the endpoint from Segment’s support team.

The first step is to make sure IBM UBX supports the source type and connection mode you’ve chosen to implement. You can learn more about what dictates the connection modes we support here.

WebMobileServer
📱 Device-based
☁️ Cloud-based
  1. From your Segment UI’s Destinations page click on “Add Destination”.
  2. Search for “IBM UBX” within the Destinations Catalog and confirm the Source you’d like to connect to.
  3. Enter your UBX API URL and your publisher’s endpoint authentication key in the Segment Settings UI. You should have received an email with this URL shortly after setting up your UBX account. If you can’t locate your URL, please contact UBX support (the URL is also referred to as a “base URL” in the IBM UBX documentation). To locate your endpoint authentication key, navigate to the “Endpoints” tab in UBX, then look to the far right where you’ll find three vertical dots. Click on them and select “Endpoint details”.
  4. Register and provision a Segment endpoint within your UBX dashboard so you can access the appropriate endpoint authentication key. Do this by navigating to “Endpoints”, then “Register a new endpoint” and select “Segment”. Then click “Register” to proceed.

  5. Once registered, the new endpoint’s status will remain “Pending” in the “Endpoints” tab until it has been activated. To activate an endpoint, please include your UBX account’s API URL and your endpoint authentication key in an email to Segment via our tech support form.

  6. Segment will activate your endpoint within 24 hours, at which time its status will update to “Active” in the UBX dashboard. Now, you can grab your endpoint authentication key again and paste it into your UBX settings in the Segment UI.

You can read more about defining and activating applications in UBX here in their documentation.

General Tracking Advice

We encourage customers to review UBX’s dynamic event library closely to become familiar with UBX’s specced events and properties. Many UBX consumers only accept specific events; likewise, many consumers function best when specific events include particular properties. Although Segment provides robust out-of-the-box mapping (documented below), we still recommend reviewing the dynamic event library closely to ensure that you are sending events and properties that enable you to get the most out of your UBX consumers.

Page

Page calls will send a ‘Page View Event’ to UBX (code ibmpageView). The below mappings may apply:

Segment PropertyUBX Attribute Name
namesiteID

Note: As with track events, all properties sent by the user that aren’t mapped above will be sent as attributes to UBX. To send a UBX-specced property that isn’t mapped above, simply set the Segment property name to the UBX property code directly (e.g. pageID). Remember, you can find UBX-specific event and property codes in their dynamic event library.

Track

Segment’s integration with UBX supports all public recognized UBX event types. Beware, however - UBX event destinations will only receive events to which they are subscribed. To subscribe a UBX destination to events from the Segment publisher, navigate to the “Events” tab and select “Subscribe to events”.

Make sure that you subscribe your UBX event subscriber endpoints to the events you’d like them to consume from the Segment publisher.

Note that while Segment supports all UBX-specced events, we have mapped the following Segment-specced events and their properties to their UBX equivalents:

Event Mappings

Mobile

Events

Segment Event NameUBX Event Code
Application BackgroundedappSessionClose
Application OpenedappSessionOpen
Application InstalledappInstalled
Application UninstalledappUninstalled
Application CrashedappCrashed

We do not define any specific mobile property mappings at this time given that Segment’s spec and UBX’s spec do not share closely related mobile properties. Note, you can still pass in any attribute codes as defined in UBX’s dynamic event library, and Segment will pass these values downstream.

Ecommerce

Events

Segment Event NameUBX Event Code
Product AddedcartAdd
Order CompletedibmcartPurchase
Product ViewedibmproductView
Product RemovedcartRemove
Products SearchedibmsearchedSite
Product ReviewedwroteReview

Attributes

Segment Property NameUBX Attribute Name
order_idorderID
totalorderTotal
taxorderTax
discountorderDiscount
couponorderPromo
productsproductList
cart_idorderID
product_idproductID
nameproductName
pricebasePrice
urlproductURL
image_urlimageURL
review_bodyreview

Video

Events

Segment Event NameUBX Event Code
Video Content CompletedibmelementVideoCompleted
Video Playback StartedibmelementVideoLaunched
Video Playback PausedibmelementVideoPaused
Video Playback ResumedibmelementVideoPlayed

Attributes

Segment Property NameUBX Attribute Name
positionvideoTimestamp
total_lengthvideoTotalLength

Email

Events

Segment Event NameUBX Event Code
Email BouncedemailBounce
Email Link ClickedemailClick
Email OpenedemailOpen
UnsubscribedemailOptOut

Attributes

Segment Property NameUBX Attribute Name
email_subjectsubjectLine
list_idmessageGroupId
list_namemessageGroupName
link_urlclickUrl

Note: To send a UBX event or property that isn’t mapped above, simply set the Segment event or property name to the UBX-specced event or property code directly (e.g. opptyQualified). Remember, you can find UBX-specific event and property codes in their dynamic event library.

Property Mappings

Segment also maps some properties from the context object to their equivalent UBX attributes. Note that UBX only supports a few data types - string, number, boolean and date. Segment will automatically discard any properties of a type not mentioned here, with the exception of objects, which we will attempt to stringify. If we cannot, expect to see [object Object] appear as the value in UBX.

Segment PropertyUBX Attribute Name
context.device.typedeviceType
context.ipip
context.location.latitudelatitude
context.localelocale
context.location.citylocationCity
context.location.countrylocationCountry
context.location.longitudelongitude
context.device.manufacturermanufacturer
context.campaign.mediummarketingSource
context.campaign.sourcemediaSource
context.device.modelmodelName
context.os.nameOS
context.userAgentplatform
context.os.versionversionOS
(context.screen.width) * (context.screen.height)resolution

Integration-Specific Option Mapping

Segment maps the following integration-specific options to UBX:

integrations['ibm-ubx'].channelchannel
integrations['ibm-ubx'].subChannelattributes.subChannel
integrations['ibm-ubx'].contactConsentattributes.contactConsent

An event containing all three integration-specific options may look something like this:

analytics.track('Order Completed' {
  // properties
}, {
  integrations: {
    'ibm-ubx': {
      channel: 'crm',
      subChannel: 'chat',
      contactConsent: 'email,opt-in'
    }
  }
})

It’s important to note some information about precedent for each of these options:

  • channel: Segment first checks whether this value is defined in integration-specific options; if not and we detect analytics-android or analytics-ios libraries, channel is set to mobile; for all other libraries, channel is set to web.
  • subChannel: This value is not appended to the outgoing payload unless explicity defined by the user.
  • ContactConsent: This value is not appended to the outgoing payload unless explicity defined by the user. The value passed to Segment must be in the format channel,subscriptionOption. At the moment, the only acceptable channels are email and sms, and the only two acceptable subscription options are opt-in and opt-out.

For more information, please refer to IBM UBX’s documentation on subchannel here (Best practice event attributes article) and on channel here. Note that recommended values for these fields is often determined by the downstream tools connected to UBX (e.g. Watson Customer Engagement tools).

Troubleshooting

Not seeing any data from Segment appear in UBX

  • Check to ensure your Segment publisher endpoint is “Active”. If not, see Getting Started above.
  • Ensure you’ve subscribed your UBX destinations to the appropriate events.

FAQ

Segment does not auto-generate events other than an initial page call when using our Analytics.js library and mobile lifecycle events when mobile lifecycle tracking is enabled via Segment’s Android or iOS library.

This means some events supported and in some cases expected by downstream UBX destinations - including abandonment events - must be derived by the customer. One approach would be to integrate with a marketing tool such as AppBoy or Bronto, in which you can set up rules that generate abandonment events, which are then be sent back through Segment and downstream to UBX.

Another approach may be to schedule a cron job in your database that checks for users who have triggered a Product Added event, but who never went on to trigger an Order Completed event. In this case, one can logically deduce that the user abandoned his cart, hence you should trigger a server-side Segment event based on this rule, which Segment will process and pass downstream to UBX.

Segment’s integration with UBX supports the following UBX abandonment events:

  • ibmabandonedConversion
  • ibmbrowseAbandonment
  • ibmbrowseAbandonmentItem
  • ibmcartAbandonment
  • ibmcartAbandonmentItem

You can find more information about these events in UBX’s Event Taxonomy.


If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!