AirMail Push API Update: Aliases, tags, and batch push to Android and BlackBerry devices

Today I’d like to announce a few improvements to our AirMail Push API for Android and BlackBerry devices. These APIs have already been in production for iOS apps for some time, and now they’re ready for use on all three platforms. Whether you’re developing an application for a single platform or using all three, aliases, tags, and the batch API might be just what you need.

Aliases

Since we first opened our push notification service, aliases have been used to ease integration requirements. By adding a developer-defined field to the registration payload, you can remove the need to store combinations of devices along side in your own database. Instead you can refer to the recipient by something convenient like the user ID or a hash of the email address. Now that aliases are available on all three platforms, you don’t even need to track what platforms the user is on.

As an example, say your end-user Bob has user id 42 in your database. When his iOS, Android, and BlackBerry apps start up, they add the string ’42′ as an alias in the JSON payload, like so:

PUT https://go.urbanairship.com/api/device_tokens/<iOS device token>
PUT https://go.urbanairship.com/api/device_pins/<BlackBerry PIN>
PUT https://go.urbanairship.com/api/apids/<Android APID>
Content-Type: application/json
body: {"alias": "42"}

To push, then, you can just use the alias as the recipient, and put the appropriate payload for each platform:

POST https://go.urbanairship.com/api/push/
Content-Type: application/json
body:
{
    "aliases": ["42"],

    # iOS
    "aps": {
        "alert": "Hello from Urban Airship!"
        "badge": 1
    },

    # Android
    "android": {
        "alert": "Hello from Urban Airship!"
    },
    "blackberry": {
        "content-type": "text/plain",
        "body": "Hello from Urban Airship!"
    }
}

No matter what the combination of devices registered with the alias “42″, all active recipients will then get the message, in the format appropriate for that device.

Tags

Like aliases, tags can be a great convenience and lessen the cost of tracking large numbers of ever-changing users. One common use case for tags is to track topics that the user is interested. Consider a news application: a user might select that they’re interested in breaking news about politics, entertainment, and technology. Your app code register each of those as a tag:

PUT https://go.urbanairship.com/api/device_tokens/<iOS device token>
PUT https://go.urbanairship.com/api/device_pins/<BlackBerry PIN>
PUT https://go.urbanairship.com/api/apids/<Android APID>
Content-Type: application/json
body: {"tags": ["politics", "entertainment", "technology"]}

If a news story comes along that your system determines is relevant to users that selected “technology” and “science”, then you could make a push request like this:

POST https://go.urbanairship.com/api/push/
Content-Type: application/json
body:
{
    "tags": ["technology", "science"],

    # iOS
    "aps": {
        "alert": "New Tech/Science Story",
    },
    "url": "http://example.com/news.html",

    # Android
    "android": {
        "alert": "New Tech/Science Story",
        "extra": "http://example.com/news.html",
    },
    "blackberry": {
        "content-type": "text/plain",
        "body": "New Tech/Science Story
http://example.com/news.html",
    }
}

Every user tagged with science or technology will get this push, without needing any server-side database changes or keeping track of every user-initiated change.

Batch Push

Last but not least, we’ve expanded the batch API to support BlackBerry and Android. If you have to send a large number of distinct messages to multiple devices, you can group it into a single API call to minimize the number of round-trip HTTPS calls you make. This API now supports everything that the normal push API can do. Here’s an example:

POST https://go.urbanairship.com/api/push/batch/
Content-Type: application/json
body:
[
    {
        "apids": ["<my apid>"],
        "android": {
            "alert": "OMG you have to read this"
        },
    },
    {
        "device_pins": ["<my pin>"],
        "blackberry": {
            "content-type": "text/plain",
            "body": "Hello old chap, here's a note"
        }
    }
]

We hope these new additions help make your integration as painless as possible.