Push for Android API

General

Urban Airship now supports a subset of our push notification API for Android devices. Other features will be added as time goes on, but for now registration, aliases, tags, broadcast, individual push, and batch push are supported.

Like the push notification API, each application has an Application Key and both an Application Secret and an Application Master Secret. Credentials are supplied in HTTP Basic Auth (with the key as the username and the secret as the password), always over our HTTPS connection. The Application Key is to be included in the application to perform registration, while the application secret is used for API Authentication. The master secret should only be used on a remote server and not included in the application.

An APID (Android Push ID) is the Urban Airship ID of a device to which a message can be pushed from the Urban Airship API.

All URLs listed here are based at https://go.urbanairship.com/ (e.g., https://go.urbanairship.com/api/push/).

Registration

Unlike registration for iOS and BlackBerry applications, basic registration tying an APID to your application happens automatically. The registration API can be used to set aliases or tags.

An HTTP PUT to /api/apids/<apid> registers APID options with our server. This returns HTTP 200 OK for any updates. Registering without any body is a no-op. Options are set by setting the Content-Type header to application/json and, in the body of the request, specifying your options:

{
    "alias": "example_alias",
    "tags": ["tag1", "tag2"]
}

Not including the alias field will clear it. To clear the list of tags, set it to the empty list [].

If you are registering an APID to be used with C2DM, you will also need to include a C2DM registration ID in the JSON body:

{
     "alias": "example_alias",
     "tags": ["tag1", "tag2"],
     "c2dm_registration_id": "A C2DM REGISTRATION ID"
}

Here’s an example using curl, a command line URL fetching tool:

curl -X PUT -u "<application key>:<application secret>" \
    -H "Content-Type: application/json" \
    --data '{"alias": "myalias"}' \
    https://go.urbanairship.com/api/apids/<apid>/

You can see an APID’s information with an HTTP GET to /api/apids/<apid>, which returns application/json:

{
    "apid": "some apid",
    "alias": "myalias",
    "created": "2009-11-06 20:41:06",
    "active": true,
    "tags": [
        "tag1",
        "tag2"
    ]
}

An HTTP DELETE to /api/apids/<apid> will mark the APID as inactive; no notifications will be delivered to it until it re-registers through the library. The DELETE returns HTTP 204 No Content, and needs no payload.

Push

An HTTP POST to /api/push/ sends a push message to one or more users. The payload is in JSON with content-type application/json, with a structure like this:

{
    "apids": [
        "some APID",
        "another APID"
    ],
    "aliases": ["my_alias"],
    "tags": ["tag1", "tag2"],
    "android": {
         "alert": "Hello from Urban Airship!",
         "extra": {"a_key":"a_value"}
    }
}

Only one of aliases, tags, or device_pins is required, but they can be mixed and matched as much as you’d like.

The response is an HTTP 200 OK with no content, or an HTTP 400 Bad Request if the structure was invalid.

Important: The maximum message size is 1024 bytes. This is calculated as the UTF-8 lengths of alert and extra fields together.

The android key contains the payload delivered to the application (both alert and extra are delivered to the application). alert is displayed in the Android Status Bar Notification.

If you include an extra, it must be a dictionary in which both the keys and values are strings. To send JSON, the extra value must be escaped.

Note

The dictionary extra format was introduced with the Android library. Applications using AMCP (AirMail Control Panel, the older method of sending push notifications to Android) are only able to receive extras sent as strings.

Batch Push

Our Android system, like iOS, supports a batch API for sending many messages in one HTTP call. An HTTP POST to /api/push/batch/ sends the given notification to all listed device tokens. The payload is in JSON with content-type application/json, with this structure:

[
    {
        "apids": [
            "some APID",
        ],
        "android": {
             "alert": "Hello from Urban Airship!",
             "extra": {"data":"optional extra data"}
        }
    },
    {
        "apids": [
            "yet another APID"
        ],
        "android": {
             "alert": "Goodbye from Urban Airship!"
             "extra": {"data":"optional extra data"}
        }
    }
]

The response is an HTTP 200 OK with no content, or an HTTP 400 Bad Request if the structure was invalid.

This POST is authenticated with the Application Key and Master Secret. Each item in the list can contain 0 or many apids and 0 or many aliases or tags, and the android payload is in the same format as for individual pushes.

Important: The maximum size for each message in the batch API call is 1024 bytes. This is calculated as the UTF-8 lengths of alert and extra fields together for each individual message within the batch.

Broadcast

An HTTP POST to /api/push/broadcast/ sends a push message to all active APIDs for your application. The payload is in JSON with the content-type application/json, with the following structure:

{
    "android": {
        "alert": "Hello from Urban Airship!",
        "extra": {"data":"optional extra data"}
    }
}

A successful response will have an HTTP status code of 200 OK with no content. If the request is invalid, we’ll return an HTTP 400 Bad Request. We’ll generally return a message in the body of the response indicating the issue with your payload.

Important: The maximum message size is 1024 bytes. This is calculated as the UTF-8 lengths of alert and extra fields together.

The android key contains the payload delivered to the application (both alert and extra are delivered to the application). alert is displayed in the Android Status Bar Notification.

Listing APIDs

To receive a paginated list of APIDs, you can perform an HTTP GET on /api/apids/ using your application key and master secret. You can control how many APIDs are returned at a time by using the limit GET argument. The maximum limit is 5000.

Example cURL command:

curl -u "<application key>:application secret>" https://go.urbanairship.com/api/apids/?limit=5

Example response:

{
    "apids": [
        {
            "apid": "example apid",
            "active": true,
            "alias": "",
            "tags": []
        }
    ],
    "next_page": "https://go.urbanairship.com/api/apids/?start=another_example_apid&limit=5"
}