# IBM Universal Behavior Exchange Destination

## Destination Info

* Accepts [Page](/docs/segment/connections/spec/page), [Track](/docs/segment/connections/spec/track) calls.
* In Cloud-mode, refer to it as **IbmUbx**, **IBM UBX** in the [Integrations object.](/docs/segment/guides/filtering-data/#filtering-with-the-integrations-object)

### Components

* Server

## Connection Modes

[Learn more about connection modes.](/docs/segment/connections/destinations/#connection-modes)

### Device-Mode

* web: no
* mobile: no
* server: no

### Cloud-Mode

* web: yes
* mobile: yes
* server: yes

[IBM's Universal Behavior Exchange (UBX)](https://www.ibm.com/support/knowledgecenter/en/SS9JVY/UBX/kc_welcome_UBX.html) 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**. Segment is actively working on this feature. Some functionality may change before it becomes generally available. If you have any feedback to help improve the IBM UBX Destination and its documentation, [contact Segment](https://segment.com/help/contact).

## Getting started

> \[!NOTE]
>
> To enable Segment in UBX, go to "Endpoints" in the UBX dashboard, select "Register new endpoint", then select "Segment".
>
> Once you've added the Segment endpoint, contact [Segment support](https://segment.com/help/contact) with your new endpoint's "endpoint authentication key" for help activating your new endpoint.
>
> Note that the endpoint in UBX cannot 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.

1. From the Segment web app, click **Catalog**.
2. Search for "IBM UBX" in the Catalog, select it, and choose which of your sources to connect the destination to.
3. Enter your UBX API URL and your publisher's endpoint authentication key in the Segment Settings UI. You should receive an email with this URL after setting up your UBX account. If you can't locate your URL, contact UBX support.

> **Note**: The URL is also referred to as a "base URL" in the [IBM UBX documentation](https://developer.ibm.com/customer-engagement/docs/watson-marketing/ibm-universal-behavior-exchange-ubx/ubxapireference/). To locate your endpoint authentication key, navigate to the **Endpoints** tab in UBX, click on the three dots symbol, and select **Endpoint details**.

4. Register and provision a Segment endpoint within your UBX dashboard so you can access the appropriate endpoint authentication key. To do this, go to **Endpoints > Register a new endpoint** and select "Segment". Click **Register** to proceed.

   ![UBX dashboard showing endpoint registration with Segment highlighted.](https://docs-resources.prod.twilio.com/2e386ed9b14f8d8e92cf117c9392b8764539e6903134132abc2479610438dda4.png)
5. Once registered, the new endpoint's status will remain "Pending" in the **Endpoints** tab until it has been activated. To activate an endpoint, include your UBX account's API URL and your endpoint authentication key in an email to Segment using the [tech support form](https://segment.com/help/contact/).

   ![UBX Endpoints tab showing Segment endpoint with Active status and actions menu open.](https://docs-resources.prod.twilio.com/886f1448b5c4726fcc557304294bbe265891c85e7333869dbd906e3b8267fbe9.png)
6. Segment activates your endpoint within 24 hours, at which time its status updates 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.

## General tracking advice

Segment encourages customers to review UBX's dynamic event library 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, Segment still recommends 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 send a 'Page View Event' to UBX (code `ibmpageView`). The following mappings might apply:

| Segment Property | UBX Attribute Name |
| ---------------- | ------------------ |
| `name`           | `siteID`           |

**Note**: As with Track events, all properties sent by the user that aren't mapped are sent as attributes to UBX. To send a UBX-specced property that isn't mapped, set the Segment property name to the UBX property code directly (for example, `pageID`). 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, UBX event destinations 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".

![UBX Events tab showing Segment endpoint connected to IBM Test Drive Destination with endpoint actions menu open.](https://docs-resources.prod.twilio.com/0357e06350c0e6aadcbca5a4e0fd4512d1e55ca6152970b2e81ecf34bee8378c.png)

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, the following Segment-specced events and their properties have been mapped to their UBX equivalents:

### Event mappings

#### Mobile

Events

| Segment Event Name       | UBX Event Code    |
| ------------------------ | ----------------- |
| Application Backgrounded | `appSessionClose` |
| Application Opened       | `appSessionOpen`  |
| Application Installed    | `appInstalled`    |
| Application Uninstalled  | `appUninstalled`  |
| Application Crashed      | `appCrashed`      |

No specific mobile property mappings are defined at this time, given that Segment's spec and UBX's spec do not share closely related mobile properties. You can still pass in any attribute codes as defined in UBX's dynamic event library, and Segment passes these values downstream.

#### Ecommerce

Events

| Segment Event Name | UBX Event Code    |
| ------------------ | ----------------- |
| Product Added      | `cartAdd`         |
| Order Completed    | `ibmcartPurchase` |
| Product Viewed     | `ibmproductView`  |
| Product Removed    | `cartRemove`      |
| Products Searched  | `ibmsearchedSite` |
| Product Reviewed   | `wroteReview`     |

Attributes

| Segment Property Name | UBX Attribute Name |
| --------------------- | ------------------ |
| `order_id`            | `orderID`          |
| `total`               | `orderTotal`       |
| `tax`                 | `orderTax`         |
| `discount`            | `orderDiscount`    |
| `coupon`              | `orderPromo`       |
| `products`            | `productList`      |
| `cart_id`             | `orderID`          |
| `product_id`          | `productID`        |
| `name`                | `productName`      |
| `price`               | `basePrice`        |
| `url`                 | `productURL`       |
| `image_url`           | `imageURL`         |
| `review_body`         | `review`           |

#### Video

Events

| Segment Event Name      | UBX Event Code             |
| ----------------------- | -------------------------- |
| Video Content Completed | `ibmelementVideoCompleted` |
| Video Playback Started  | `ibmelementVideoLaunched`  |
| Video Playback Paused   | `ibmelementVideoPaused`    |
| Video Playback Resumed  | `ibmelementVideoPlayed`    |

Attributes

| Segment Property Name | UBX Attribute Name |
| --------------------- | ------------------ |
| `position`            | `videoTimestamp`   |
| `total_length`        | `videoTotalLength` |

#### Email

Events

| Segment Event Name | UBX Event Code |
| ------------------ | -------------- |
| Email Bounced      | `emailBounce`  |
| Email Link Clicked | `emailClick`   |
| Email Opened       | `emailOpen`    |
| Unsubscribed       | `emailOptOut`  |

Attributes

| Segment Property Name | UBX Attribute Name |
| --------------------- | ------------------ |
| `email_subject`       | `subjectLine`      |
| `list_id`             | `messageGroupId`   |
| `list_name`           | `messageGroupName` |
| `link_url`            | `clickUrl`         |

> \[!NOTE]
>
> To send a UBX event or property that isn't mapped, set the Segment event or property name to the UBX-specced event or property code directly (for example, `opptyQualified`). 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 automatically discards any properties of a type not mentioned here, with the exception of objects, which Segment attempts to stringify. If this isn't possible, you can expect to see `[object Object]` appear as the value in UBX.

| Segment Property                                   | UBX Attribute Name |
| -------------------------------------------------- | ------------------ |
| `context.device.type`                              | `deviceType`       |
| `context.ip`                                       | `ip`               |
| `context.location.latitude`                        | `latitude`         |
| `context.locale`                                   | `locale`           |
| `context.location.city`                            | `locationCity`     |
| `context.location.country`                         | `locationCountry`  |
| `context.location.longitude`                       | `longitude`        |
| `context.device.manufacturer`                      | `manufacturer`     |
| `context.campaign.medium`                          | `marketingSource`  |
| `context.campaign.source`                          | `mediaSource`      |
| `context.device.model`                             | `modelName`        |
| `context.os.name`                                  | `OS`               |
| `context.userAgent`                                | `platform`         |
| `context.os.version`                               | `versionOS`        |
| `(context.screen.width) * (context.screen.height)` | `resolution`       |

### Integration-specific option mapping

Segment maps the following integration-specific options to UBX:

| `integrations['ibm-ubx'].channel`        | `channel`                   |
| ---------------------------------------- | --------------------------- |
| `integrations['ibm-ubx'].subChannel`     | `attributes.subChannel`     |
| `integrations['ibm-ubx'].contactConsent` | `attributes.contactConsent` |

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

```javascript
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 if `analytics-android` or
  `analytics-ios` libraries are detected,`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`.

## FAQ

#### Why isn't the data from Segment appear in UBX?

* Ensure your Segment publisher endpoint is "Active". If not, see the [getting started](#getting-started) steps.
* Ensure you've subscribed your UBX destinations to the appropriate events.

## Troubleshooting

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 using 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 [Braze](/docs/segment/connections/destinations/catalog/braze/) or [Bronto](/docs/segment/connections/destinations/catalog/bronto/), in which you can [set up rules that generate abandonment events](/docs/segment/guides/how-to-guides/automated-multichannel-reengagement#1st-line-of-defense-the-push-notification), 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, you can assume that the user abandoned his cart, therefore, 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`

## Engage

You can send computed traits and audiences generated using [Engage](/docs/segment/engage) to this destination as a **user property**. To learn more about Engage, schedule a [demo](https://segment.com/contact/demo).

For user-property destinations, an [identify](/docs/segment/connections/spec/identify/) call is sent to the destination for each user being added and removed. The property name is the snake\_cased version of the audience name, with a true/false value to indicate membership. For example, when a user first completes an order in the last 30 days, Engage sends an Identify call with the property `order_completed_last_30days: true`. When the user no longer satisfies this condition (for example, it's been more than 30 days since their last order), Engage sets that value to `false`.

When you first create an audience, Engage sends an Identify call for every user in that audience. Later audience syncs only send updates for users whose membership has changed since the last sync.

> \[!NOTE]
>
> Real-time audience syncs to IBM Universal Behavior Exchange  may take six or more hours for the initial sync to complete. Upon completion, a sync frequency of two to three hours is expected.

## Settings

Segment lets you change these destination settings from the Segment app without having to touch any code.

| Field              | Description                                                                                                                                                                                                                                                                                | Required | Type   |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------ |
| API URL            | Enter your UBX account's base URL endpoint here. This can be found in the email you received from UBX after setting up your UBX account. It should have either the format \`https://\<subdomain>.ubx.ibmmarketingcloud.com/\<path>/\` or \`https://\<subdomain>.goacoustic.com/\<path>/\`. | Yes      | string |
| Authentication Key | You can find your endpoint's Authorization Key by looking at your endpoint details in UBX. It should look something like \`eff08b68-0000-0000-9a19-8e43dbeeb201:US\`.                                                                                                                      | Yes      | string |