IBM UBX

Export and target audiences aggregated across marketing platforms.

Getting Ready for UBX Integration

UBX integration requires an audience of named users, and a UBX API key — generated from your Airship project.

To use this integration, you will:

  1. Configure an Airship endpoint within the UBX interface.
  2. Map UBX audience identifiers to named_users in Airship.
  3. Schedule the interval over which UBX shares an audience with Airship.

Named Users and UBX Audiences

To use the UBX integration, you must enable named users in Airship. The named_user_id for your named users must be an audience identifier (type) in your UBX environment so that Airship can associate your UBX shared audience — exported from UBX as custom events or static lists — with named users.

If your named_user_id and UBX identifier types do not match, Airship will not be able to associate custom events or static lists with named users, preventing you from effectively issuing automated messages or performing other operations based on your UBX audience.

See Tags and Named Users or the Named Users API for more information about configuring named users.

Understanding UBX Deployment Types

When you set up your endpoint in IBM UBX, you can determine whether you want to export your UBX audience as a series of custom events or as a static list; this is the Deployment Type.

The Custom Events deployment type sends your UBX audience to Airship as custom events attributed to your named users. This deployment type lends itself to automation using the UBX-generated custom event as an event trigger. Learn to use Automation.

The Static Lists deployment type sends your UBX audience to Airship as a static list. You can schedule the deployment of the static list. If you do not rename the list in UBX between scheduled intervals, the contents of the list are overwritten during the scheduled interval. For example, if you have a list called abandoned_cart, and you deploy it every Tuesday, the contents of the list will change every Tuesday; members of the list will only remain the same if they abandoned their carts for two straight weeks. Learn more about static lists and audience selection.

Generate your IBM UBX API Key

An IBM UBX API key is the token that UBX uses to communicate with your project in Airship. You must provide this key when registering an Airship Endpoint in UBX. You can also get your app key when you generate a token; you will need your app key when registering with IBM UBX as well.

  1. Open your project in Airship.
  2. Go to Settings > APIs & Integrations > Partner Integrations.
  3. In the IBM UBX Tokens section, click Create Token.
  4. Enter a name for the token and click Create Token.
  5. Copy your token to a secure location, like a password manager. You cannot retrieve your token after you close the dialog box.

Register an Airship Endpoint with IBM UBX

Registering an endpoint requires an IBM UBX API key from your Airship project.

  1. Log in to the UBX dashboard.
  2. Click Endpoints, and select Register new endpoint.
  3. Find and select Airship, then click Next.
  4. On the Endpoint Registration page, provide your Airship app credentials. You can also provide an optional alias and description to help identify the endpoint in the UBX interface.
    • Select your Deployment:
      • Custom Events — Send audience information to Airship as custom events; you can use these custom events to trigger automated messages to a targetted audience.
      • Custom Lists — Send audience information to Airship as a static list.
    • In the API Key field, enter your IBM UBX token. You can generate the token from your project in Airship, under Settings » APIs & Integrations » Partner Integrations.
    • Enter your Airship App Key. You can get your app key from the Airship dashboard in Settings » API & Integrations.
  5. Click Register.

Your endpoint is now listed in the UBX Pilot dashboard. If the endpoint doesn't appear to be active, refresh the page.

Sync Identifiers for Users

To take advantage of UBX, you have to determine the UBX identifier that you want to associate with named users in your app's audience. Your UBX identifier should be the same type of value as your named_user_id in Airship. For example, if your named users are organized by an account or username for your service, you must select the UBX Identifier Type that corresponds the account or username value.

  1. Click the options menu next to your new endpoint and select Edit Endpoint Details.
  2. Go to the Identifiers tab, and click Edit for the named_user identifier.
     Note

    You can only edit identifiers once.

  3. Set the Identifier Type to the identifier that corresponds to the named_user_id values for your named users.
  4. Click Save. You are now ready to share your UBX audience with your app.

Sharing your Audience with Airship

After you configure your endpoint, you have to determine when and how often to share your UBX audience with your Airship app. Your source audience is unique to your IBM UBX environment and use case.

  1. Go to the Audiences tab in the UBX dashboard and click Share audiences and identifiers.
  2. Select Share an audience and click Next.
  3. Select the UBX Source Audience that you want to share with your Airship app, and then select your Airship endpoint as the Destination Audience.
  4. Enter a name without spaces for this audience in the Create New Audience field and click Next. The audience name becomes the name of your custom event or static list in Airship.
     Note

    If sharing an audience as custom events, the event name must be entirely lowercase. If the name contains uppercase characters, Airship will not receive the event.

  5. Under Map audience identifiers, select the Source identifier for your audience; this is the value mapped to your named users in Airship.
  6. Enter named_user as the Destination identifier, and then click Next.
  7. Determine the frequency with which to Share audiences and identifiers and click Next. By default, UBX shares custom events with Airship as they occur.
  8. Provide destination options.
    • Select Add New Records.
    • You can specify a Minimum number of records to share. If you opt to share immediately, UBX will share an audience as soon as it meets the minimum threshold. If you share the audience on a schedule, and you do not reach the minimum number of records before the scheduled interval, UBX will wait to share audiences and identifiers until the next scheduled interval.
  9. Click Share to initiate audience sharing with Airship.

Using UBX Custom Events as Event Triggers

You can use your UBX audience as an event trigger in the Automation composer. As UBX shares custom events with your app, your app will trigger automated messages to associated named users, providing a powerful, automated way to stay in touch with your audience.

  1. Open your project from the Airship dashboard, click Create and select Automation.
  2. In the Setup step, select the Event trigger, and specify the name of your custom event. The custom event name is the same as the Audience name in the UBX dashboard.
  3. Configure the message that you want to send when Airship receives the corresponding audience of custom events from UBX.

See the Automation composer for more information about sending automated messages based on custom event triggers.

Sending a Message to your UBX Audience List

If you deploy your UBX audience as a static list, you can target that list in the Audience step when sending a message. The name of your list in Airship is the same as the name of your audience set in UBX under Audiences.

  1. Open your project from the Airship dashboard, click Create and select Message.
  2. In the Audience step, select the channels you want to send your message to.
  3. Select Target Specific Users and either:
    • Use the search box to find and select your list.
    • Under the Explore option, select to Lists > Uploaded Lists, and enter the name of your UBX Audience in the search/filter field.
  4. Continue configuring your message; when complete, your message will go to members of your UBX audience list.