Channels Primer

Channel Definition

A channel is an individual addressable entity that you can notify via Urban Airship.

Native vs. Open


A native platform is a platform directly supported by Urban Airship via APIs and SDKs: iOS, Android, Amazon, Windows, and Web. Channels used with a native platform can be referred to as native channels — an example is an instance of a mobile app on a user’s device on iOS or Android.

An open platform is a platform supported by Urban Airship by extension via our Channels API. An open channel is any channel on an open platform — examples include an email address, an SMS number, or any unique identifier that represents an address to which you can deliver a notification.

Addressing Channels

Channels are addressable by channel ID. A channel ID is a unique identifier generated by Urban Airship that maps directly to the delivery address of a downstream service, e.g., APNS on iOS. This ensures consistency of channel metadata - information about the channel, such as segmentation information - even if the mapped service changes its own delivery address (device token for iOS or registration token for Android).

Urban Airship generates this identifier to optimize our internal systems (most APIs that support query by channel ID are extremely fast). Customers can also benefit from storing the Urban Airship channel ID in cases where the delivery address is ephemeral, e.g., device token for an iOS app installation. In the case of native channels like this, our SDK handles updating the delivery address seamlessly for the customer, while the channel ID remains consistent.

An open platform example may involve update of a specific customer’s email address. By simply updating the channel ID, you preserve associated metadata like preferences stored as tags.

A message may be sent to a native channel via the Urban Airship dashboard or the API. See: Target Specific Users and API: Channels.

Use the API to send to open channels. See: API: Open Channels. UI support is planned for a future release.

Channels API

Urban Airship’s Channels API provides a set of APIs for the management of channels and their platforms.

You can create, lookup, list and manage channel information, as well as extend Urban Airship by defining new platforms for use with our core platform services, e.g., segmentation, scheduling, automation.

Native Channels

Native channels are typically backed by an Urban Airship SDK. When a new user runs your app for the first time, our SDK creates a channel to map to that installation. For example, on iOS it will map a device token to that channel. The channel then becomes the primary identifier used to address notifications/messages to the device. If iOS ever changes the device token, we can update the device token behind the scenes without changing the channel.

Native channels can be:

  • An ID, such as a UUID, e.g., c76ff18e-9cb9-4c19-b9af-a39cae684810.
  • A push address, e.g., a device token for iOS, FCM registration ID for Android, or ADM registration ID for Amazon.
  • Metadata, e.g., tags , named users , aliases , quiet time settings, etc.

Upgrade To Use Channels

If you are currently using device tokens (for iOS) or APIDs (for Android), we strongly recommend you migrate to using channels. Whether you primarily use broadcast, or you set tags or aliases from the device, no action is required on your part other than upgrading to at least 4.0.0 SDK for iOS or 5.0.0 SDK for Android and Amazon.

If you set tags or aliases from the device, since metadata is coming from the device, the SDK will automatically use the channel.

iOS

If you send messages to device tokens, you may continue to use them for the time being, but to get the protections afforded by channels, start collecting channels from inside your application. The channel is next to the device token on the UAPush object.

NSString *channelID = [UAPush shared].channelID;

Once you have collected the appropriate channel, send the message directly to the channel. For example, if your push payload looked like this:

{
   "audience": {
      "device_token": "C9E454F6105B0F442CABD48CB678E9A230C9A141F83CF4CC03665375EB78AD3A"
   },
   "notification": {
      "alert": "Hello"
   },
   "device_types": ["ios"]
}

then the updated payload would simply replace the device token audience selector with ios_channel:

{
   "audience": {
      "ios_channel" : "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
   },
   "notification": {
      "alert": "Hello"
   },
   "device_types": ["ios"]
}


Channels for all existing device tokens can be fetched via the Channel Listing API.

Like direct push, the tag APIs continue to work from the server, but we now have channel-specific options. After you have collected your channels, switch your calls to our Tag API to use ios_channel instead of device_token. See the Tag API docs for more information.

Android

If you send messages to APIDs, you may continue to use them via the push API, but you can also use the synonym android_channel. Since the identifiers did not change, all APIDs are valid Android channels. Inside your application, the channel is available on the PushManager object.

String channelId = UAirship.shared().getPushManager().getChannelId();


Once you have collected the appropriate channel, you can send the message directly to the channel. For example, if your push payload looked like this:

{
   "audience": {
      "apid": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
   },
   "notification": {
      "alert": "Hello"
   },
   "device_types": ["android"]
}

then the updated payload would simply replace the apid audience selector with android_channel:

{
   "audience": {
      "android_channel" : "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
   },
   "notification": {
      "alert": "Hello"
   },
   "device_types": ["android"]
}

Amazon

An example of getting the channel for Amazon:

String channelId = UAirship.shared().getPushManager().getChannelId();


Once you have collected the appropriate channel, you can send the message directly to the channel:

{
   "audience": {
      "amazon_channel" : "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
   },
   "notification": {
      "alert": "Hello"
   },
   "device_types": ["amazon"]
}

Open Channels

Open channels is currently available to enterprise customers. Contact your account manager or Support for more details.

Open channels support notification payloads to any messaging channel you choose, via the Urban Airship API.

Open channels can be used on any non-native platform, or open platform, where you’d like to reach your users. Leverage the features of Urban Airship Engage while sending notifications to SMS, email, Slack, or any type of app or device capable of receiving a JSON payload.

You can send to natively supported channels and open channels in combination or in isolation, using our familiar device_types selector and platform-specific payloads.

Open channels are designed to be used in conjunction with Named Users. Today, if you want to send to all channels associated with a named user in one API call, you can simply target that named user with all platforms enabled. In the future we will add further orchestration functionality that will apply more sophisticated approaches to sending to a specific channel.

Use Cases

There are no limits to the type of device or services that you can integrate for notifications. Some examples customers are pursuing include:

  • Your ESP or SMS provider of choice
  • Voice-based services
  • IoT devices
  • Chatbots or messaging app services like Slack or Facebook Messenger
  • Digital TVs & set-top box devices
  • Augmented/virtual reality devices
  • Factory floor devices
  • Gaming consoles
  • Home platforms
  • Car platforms
  • Rapid prototyping of new notification services

Development Features

We’ve designed our APIs to be as friendly as possible to developers, including several features that will save development cost and complexity:

  • Delivery Address Storage: Lets you register and store channels using your own unique recipient identifier, e.g., an email address or SMS number, so you don’t have to store a mapping to our Channel IDs. You can interact with our system using this identifier as well. There is even a facility to update this address while preserving associated metadata—see "old_address" below.

  • Identifiers Metadata: Lets you store additional information about each individual channel (message recipient) that gets forwarded along each webhook call. This information could be used to help you route this message appropriately or make formatting decisions. For example, an email address might contain additional information about capabilities, e.g., “accepts HTML” or “low-bandwidth connection”, that you could use in your webhook implementation to format the message appropriately. This could save a developer from having to build out additional databases or perform lookups during processing.

  • Automatic Segmentation: If you provide timezone, locale language, and country information on channel registration, open channels automatically adds these fields into our segmentation system for use in real-time targeting, in addition to making them available upon callback.

Start Using Open Channels

Head on over to Open Channels: Getting Started .

Terminology

Channels API
A set of APIs for the management of channels and platforms. Create, look up, list, and manage channel information, as well as define new platforms for channel management.
Channel
An individual addressable entity that you can notify via Urban Airship, e.g., an instance of a mobile app on a user’s device, an email address, an SMS number.
Channel ID
A unique identifier by which you can address a channel.
Platform
An external system through which notifications are delivered. Examples include iOS, Android, Amazon, and Web. All platform services, e.g., segmentation and automation, support the management of audience and delivery of notifications to them via external platforms.
Native platform
A platform directly supported by Urban Airship via APIs and SDKs: iOS, Android, Amazon, Windows, and Web.
Open platform
A platform supported by Urban Airship by extension via our Channels API.
Open channel
Any channel on an open platform supported by Urban Airship by extension via our Channels API.