Orchestration

Urban Airship's Orchestration helps to solve the problem of how to reach each user on the optimal channel, depending on the scenario. Several tools and strategies are supported to maximize engagement with users opted in to multiple notification platforms. For example, a user may be opted in for notifications via their web browser, mobile app, and an open channel such as email.

Overview

The Orchestration of your multi-channel messaging relies on a number of our platform features, depending on the message type, its level of urgency, and the particular use case. The following strategies can be employed to further personalize the mode of messaging delivery, each using a different mix of features from the Engage platform.

Fan Out
Reach the user on all channels in order to maximize chances they receive the message. For highly urgent messages.
Last Active
Reach the user on the channel used most recently. For when user recency is the best indicator of preference.
Priority Platform with Fallback
Drive engagement toward one strategic platform, for example, directing users to the mobile channel to save SMS or email cost. For when you want to define a priority for platform for users to engage with, e.g., 1) App, 2) Web, 3) Email.
User Preference
Send communications to the user's preferred channel. For when you want to provide the optimal customer experience.

Getting Started

Getting started with Orchestration is easy, provided that you are using multiple Urban Airship messaging platforms.

Prerequisites

The strategies outlined in this document each require the use of certain platform features, of which only Orchestration features need to be turned on by Support.

Named Users and Tag Groups are available to all customers, but require some implementation and configuration on your end before putting them to use.

Implement Named User

In order to use our Orchestration features, you must be implementing Named Users as the way to map users across Urban Airship channels. Named Users are by definition an essential prerequisite for Orchestration, as they are required to map a user's different channels to your internal identifier.

If you have not yet implemented Named Users, see: How Do I Implement Named Users?.

Contact Support for Configuration

Contact Urban Airship Support or your Account Manager to provision your project for Orchestration. You will be asked to provide the your app key:

From your project dashboard, navigate to Settings » APIs & Integrations, then copy your App Key. Provide the app key for all apps on which to activate Orchestration.

Set Platform Priority

Navigate to Settings » Configuration » Platform Priority and set the priority order of your project's platforms. See the Settings menu documentation for more information.

Target Users

Once your project is configured for Orchestration, you can target users via the API or dashboard as you would target any other audience. See targeting examples in the detail of the orchestration strategies below.

Okay, but how does it work?

From an implementation perspective, Orchestration just works, without any development effort on your part. But for the curious, we leverage two powerful UA platform features to make Orchestration sing:

Event Listeners
Urban Airship listens for activity such as opens, custom events, and uninstalls in order to determine priority platform and last active status.
Tag Groups
When we configure your project for Orchestration, we use Tag Groups and the reserved ua:orchestration namespace for Orchestration features.

Orchestration Strategies

Fan Out

The Fan Out orchestration approach is supported through our core platform. Fan out refers to the ability to reach the user on all known channels at the same time, in order to maximize the chances that they receive the message. This approach is suitable for highly urgent messages, where the user will not be sensitive to feeling over-messaged.

You can deliver a message to a named user across all channels via our API like so:

POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Content-Type: application/json
Accept: application/vnd.urbanairship+json; version=3;

{
   "audience": {
      "named_user": "ozymandias"
   },
   "notification": {
        "alert": "Look upon which works now?"
    },
    "device_types": "all"
}


This approach is also supported through the dashboard. Here is an example of a single named user targeted across all channels:

Last Active

In many cases, user recency is the best indicator of preference. To target users on the channel that they have most recently interacted with, use the "ua:orchestration" tag group. You can target last active through our API, dashboard, or by using Segments. An example of each targeting method is provided below.

Note

A device that is opted-in will have higher priority than an opted-out device even if the opted-out device was active more recently. For example, if the named user has two devices, iOS and Android, and the iOS device is opted-in while the Android device is opted-out, even if the Android device's app is opened more recently than the iOS device's app has been used, the iOS device will remain the "last active" because it is the only one that is still opted-in.

If there is more than one opted-in device for a particular named user, the device that has most recently had activity will receive any push targeted to the last active device. Examples of possible activities are a registration event, opt-in event, open event, or a custom event.

Note

Last Active is not available for use with SMS notifications.


Target last_active using these methods:

  1. Via our Push API, using the ua:last_active tag group.
  2. Via Target Specific Users in the dashboard, selecting last_active.
  3. By creating a Segment using the Segments Builder.

Example 1: API Request

POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Content-Type: application/json
Accept: application/vnd.urbanairship+json; version=3;

{
   "audience": {
      "tag": "last_active",
      "group": "ua:orchestration"
   },
   "notification": {
      "alert": "hi last active!"
   },
   "device_types": "all"
}


Example Response:

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Data-Attribute: push_ids

{
   "ok": true,
   "operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
   "push_ids": [
      "9d78a53b-b16a-c58f-b78d-181d5e242078"
   ]
}

Example 2: Dashboard

Search for and select last_active.

Example #3: Segments Builder UI

First select the Orchestration Tag Group, then search for and select last_active.

Priority Platform with Fallback

Your list of prioritized platforms is cascading; if the highest priority platform is opted-out or uninstalled, then the next highest priority platform will become that named user's priority platform.

If a user has multiple opted-in channels on a given platform, e.g. both an iPad and iPhone on iOS, the message will be sent to both channels.

Target priority_platform using these methods:

  1. Via our Engage API, using the ua:orchestration tag group.
  2. Via Target Specific Users in the dashboard, selecting priority_platform.
  3. By creating a Segment using the Segments Builder.

Example 1: API Request

POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Content-Type: application/json
Accept: application/vnd.urbanairship+json; version=3;

{
   "audience": {
      "tag": "priority_platform",
      "group": "ua:orchestration"
   },
   "notification": {
      "alert": "hi priority platform!"
   },
   "device_types": "all"
}


Example Response:

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Data-Attribute: push_ids

{
   "ok": true,
   "operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
   "push_ids": [
      "9d78a53b-b16a-c58f-b78d-181d5e242078"
   ]
}

Example 2: Dashboard

Search for and select priority_platform.

Example 3: Segments Builder UI

First select the Orchestration Tag Group, then search for and select priority_platform.

Fallback

Our Priority Platform orchestration system actively monitors events from your audience such as app opens and opt-in status changes to maintain as accurate a picture as possible of where your audience is reachable for messaging. This picture is only as accurate as the signals we get back from apps or the service providers we work with, however, and in some cases, due to platform limitations, we do not receive messaging channel state changes in real time.

The iOS and Android platforms suffer from this limitation when a user uninstalls an app in that the push providers, e.g., APNs, do not send out any signals or display any status about an uninstall in real time. Only when we attempt to send a push notification to it does Apple (APNs) or Google (FCM) let us know the app has been uninstalled.

Since this is a key use case for app messaging, we have enhanced our system to automatically redirect the message to the next available platform in the priority list when we detect an uninstall event on iOS or Android, in real time.

This messaging fallback behavior follows the same logic we use when determining where to assign the priority_platform tag, and in fact, we also reassign the priority_platform tag at the same time we detect the uninstall.

User Preference

If you have an explicit communication preference from a user that is opted in on multiple channels, add a "user_preferred" tag to the preferred channel.

This section provides a recipe for using our platform to set tags expressing a user's preferred channel, and then accessing it through our segmentation system in the same manner as the Last Active and Priority Platform orchestration features.

This walkthrough assumes that you have already implemented named users and contacted Urban Airship Support to activate Orchestration features.

The key steps are:

  1. Associate multiple channels with a named user.
  2. Set a "user_preferred" tag in the "ua:orchestration" tag group on one channel per named user, based on user input.
  3. Target the "user_preferred" tag as necessary.

Associate Channels

In order to set a preferred channel on a user, they must be opted in on at least two messaging channels, e.g., iOS, web.

Set User Preference Tags

List all channels for your named user by using the Named User Lookup API.

Once you parse the results to gather the Channel IDs, you maintain the "user_preferred" tag on each channel, using our Tags API:

POST /api/channels/tags HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

{
   "audience": {
      "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
   },
   "add": {
      "ua:orchestration": [
         "user_preferred"
      ]
   }
}

Target Preferred Users

Now that you have identified and tagged each user's preferred channel, target the user_preferred tag as shown in the Last Active and Priority Platform sections.