Channels Primer

What are Channels?

Channels are a new way of addressing your application installations on iOS, Android and Amazon devices. With iOS 7, Apple drastically changed the way device tokens are issued, and to prevent a similar change from affecting our customers in the future, we create a Channel identifier for each installation which will map to an iOS device token if one is available.

Android APIDs have been updated to the latest infrastructure and are now known as Android Channels. All IDs remain the same, so you can start using the Channel term without updating your database.

Conceptually, Channels are a similar solution to our Windows push systems in the sense that the Channel is an abstraction of the underlying device identifier. In the case of Windows, the APID serves a similar purpose.

Channels are also the mechanism used to address Amazon devices with the latest Android 5.0.0 SDK. See Android: Getting Started for more information.

Which platforms use Channels?

iOS, Android and Amazon.

How do Channels work?

When an end user runs your application for the first time after installing it, a Channel is created and returned to Urban Airship. The Channel then becomes the primary identifier used to address notifications and/or messages to the device.

Channels consist of:

  • an ID (a UUID, e.g., c76ff18e-9cb9-4c19-b9af-a39cae684810)

  • a push address, e.g., a device token for iOS, GCM registration ID for Android, or ADM registration ID for Amazon

  • metadata, e.g., tags , named users , aliases , quiet time settings, etc.

When a new user runs your app for the first time, we create a Channel to map to this installation, and map the device token if one is available. If iOS ever changes the device token, then we can update the device token behind the scenes without changing the Channel.

How can I use Channels?

Everywhere you currently use device tokens (for iOS) or APIDs (for Android) you can now use Channels. What you will require in order to update from device tokens or APIDs to Channels depends on the way you currently interact with them.

I use broadcast primarily

In this case, you do not need to do anything to benefit from the Channels architecture except upgrade to at least 4.0.0 SDK for iOS or 5.0.0 SDK for Android and Amazon; everything is handled behind the scenes.

I set tags or aliases from the device

Similar to the broadcast use case- no action is required on your part other than upgrading to at least 4.0.0 Urban Airship SDK for iOS or 5.0.0 Urban Airship SDK for Android and Amazon. Since metadata is coming from the device, the SDK will automatically use the Channel.

iOS

I send direct messages to device tokens

You may continue to use device tokens for the time being, but to get the protections afforded by Channels you can start collecting Channels from inside your application. The Channel is available next to the device token, on the UAPush object.

NSString *channelID = [UAPush shared].channelID;

Once you have collected the appropriate Channel, then you can send the message directly to the channel.

For example, if your v3 Push API 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. Start collecting Channels from inside your application. See the iOS Migration Guide for details.

Then, when you have collected Channels, you can switch your calls to our Tag API to use “ios_channel” instead of “device_token”. See the Tag API docs for more information.

Android

I send direct messages to APIDs

You may continue to send to APIDs through the push API, but there is now the synonym android_channel to use. 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, then you can send the message directly to the channel.

For example, if your v3 Push API 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, then you can send the message directly to the channel.

For example:

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