Urban Airship

Table of Contents

Integration

A successful Urban Airship integration is one that maps to your Mobile business objectives. Once you have Installed the UA SDK and familiarized yourself with the Urban Airship User Guide, it’s time to think about how your systems can integrate with Urban Airship to help you achieve your goals.

This section introduces concepts in three major areas:

  • Audience
  • API
  • Data & Analytics
  • Platform-Specific Notes

Audience

Proper audience segmentation and targeting is key to any comprehensive messaging strategy.

Device Identifiers

Push Address

In order to send a push notification to an app, you’ll need the identifier that specifies that specific app installation on a particular device. These identifiers, or push addresses, are typically provided by the messaging platform, e.g., APNs, GCM, etc.

There are no industry standards for the format, lifecyle, or attributes associated with an underlying push address. They are also subject to change and cannot reliably be considered permanent.

In order to ensure consistent communication with your audience, Urban Airship provides a unique identifier known as a Channel that serves as an abstraction from the underlying identifier across multiple platforms. Channels are currently used for iOS, Android, and Amazon devices.

Urban Airship Identifiers

Channel

See: Channel

Channels are a platform-agnostic way to identify an installation of an app on a device. Currently Channels are used for iOS, Android, and Amazon devices. This identifier is available regardless of whether or not the installation has a device token (in the case of iOS), and so can always be used.

For an in-depth look at Channels, see our Channels Primer.

APID

See: APID

An APID, or Airship Push Identifier, is our own identifier used for Android, Windows 8, and Windows Phone 8 devices. While the APID format predates Google’s push systems C2DM and GCM, it’s still used because the identifiers for these systems can change without notice. With the APID identifier used as your push mechanism, these can change without needing any updates in your system.

Warning

Android APIDS have been superseded by Android Channels as of the release of the 5.0 Android SDK in October 2014.

Platform-Provided Identifiers

Device Token

See: device token

Device tokens are the underlying push ID for iOS devices and have been superseded by Channels Each device token is 32 bytes (or 64 characters of hexadecimal). These identifiers change rarely, but Apple reserves the right to change them at any time. Device tokens are also only issued if the user opts in for push notifications. They currently are also changed if the device is wiped clean and not restored from backup.

PIN

See: PIN

BlackBerry phones have a longstanding identifier, used for many years. The PIN is assigned to the hardware itself, and is 4 bytes (8 characters of hexadecimal).

Named Users

Named Users are a CRM integration tool, used to associate several devices with a single User ID. If your application uses some form of user authentication, you can start associating users to Named Users on login. The Named User ID should match the User ID in your system. If you use personally identifiable information for User IDs, such as email addresses, then please ensure that you hash the information before using it as a Named User ID.

Once you have Named Users enabled in your application, you can tag them using non-mobile data accumulated by whatever backend CRM systems you maintain. See Tag Groups for more information on integrating your CRM databases with Urban Airship. For more information on Named Users, please visit our topic guide or the Named User API documentation.

Aliases

Warning

Aliases have been superseded by Named Users. While Aliases will continue to function as before, we recommend that all customers makes the switch to Named Users. For information on transitioning your current Alias integration to Named Users, see this guide.

An Alias is used to lessen the amount of integration on your server. In each mobile application, you can set an alias after you identify the user. For example, if your user enters their email and password to log into your system, your application could set the alias as your system’s user ID, or a hash of the email address.

Each device can have one alias, and the aliases need not be unique. If a person owns two devices with your app, you can set the alias to the same value. A push to that alias will then send to both devices. However, an alias should not apply to more than 10 devices, as they are designed to be used to group the devices that physically belong to a particular end user. For other use cases, you should probably use a tag instead.

Warning

You should not use personally identifiable information as an alias. If an email address or name is the ideal alias, simply hash the information with MD5, SHA, or another hash algorithm. That way you can still use it as an identifier, but Urban Airship won’t have a copy of the data.

Since aliases are set by the client, i.e., the mobile device, no special server integration is needed to activate them for push notifications.

Tags

Tags are a very flexible way to group your users. Set tags from either a client or a server, and use them to track categories of interest, preferences, user behaviors and more. Each device can have any number of tags.

Tags can be of any format you wish, but we recommend that they be URL-safe in order to make less work for you. The maximum length of a tag is 127 characters.

Example tags:

  • foobar
  • some-tag
  • a-very-long-but-detailed-tag-hooray
  • bar_baz
  • 97211
  • portland_or

Warning

You should either set the tags from the client, or from the server, not from both. Otherwise you might overwrite changes from one side or the other.

To set tags from a client, see the documentation for the device you’re working with in Platform section.

To set tags from your server, see the Tags API documentation.

Tag Groups

Tags that are set from a server, e.g., your CRM system, will overwrite tags that are set from the device. To prevent device tags from being overwritten, use Tag Groups, a convenient way to group together tags that orginate from the same data source.

Below are examples of some common tag groups and related tags.

  • Device Profile

    • Preferences
    • Location
    • App activity
    • Authentication status
  • CRM Tags

    • Unspent rewards dollars
    • Loyalty
  • Web Tags

    • Friend request

Note

If you set deviceTagsEnabled=no and then add some tags via the API, they then become the default tags.

For more information on Tag Groups, please see the Mobile Data Bridge topic guide. Also, visit our User Guide documentation on setting up and using Tag Groups.

Segments

Segments is a feature that lets you target a notification to a subset of relevant users based on any criteria you choose. Examples of targeting criteria include but are not limited to:

  • time zone
  • stated alert preferences (e.g., entertainment stories or school closure alerts)
  • in-app behaviors (e.g., purchase history or power-user status)

You may also use location as a targeting parameter.

Construct Segments by defining criteria for that Segment, and) when you push to the Segment, only users matching the criteria receive the push notification. As time goes on, the set of users that matches a particular Segment may change. For example, if your Segment is “users in the ZIP code 94123 within the past 7 days,” as users move around the world, they will fall in and out of qualification for a particular Segment’s criteria. While the users making up the Segment may change, the Segment definition itself (“users in the ZIP code 94123 in the past 7 days”) will not change unless you update the Segment criteria.

Segments are the most powerful way of addressing a portion of your audience. Segments are most often managed in the segments management page in the Urban Airship web application. They can also be managed via the Segments API.

Developer and Small Business Edition customers can use Segments with Tags only. The ability to target and push to a device via our Location service in Segments requires an Enterprise account. If you are an Enterprise customer and would like to add Location Targeting to your suite of Urban Airship services, please contact your account manager.

Relevance Through Behavior + Preferences

Segments allows you to use boolean operators (AND, OR, and NOT) to combine locations with device tags. Because the tagging system can be accessed from the mobile SDKs and the API, it can be used to capture use behaviors in the app (e.g., favoriting an artist) and preferences of your users from your servers (e.g., a product category they have made a purchase from before). Combining tags and boolean operators allows you to define Segments that range in complexity, depending on the users you are trying to reach.

Segments are Reusable by Non-technical People In Your Organization

When you create a Segment, you give it name that is meaningful to the people in your organization who are going to be sending pushes out. Be sure to give your Segment a descriptive and accurate name so that other people in your organization don’t have to go digging through the Segment definition to make sure they are doing the right thing. For example “AT&T Park” is not as strong of a name as “Inside AT&T park within the past 2 hours”.

For a detailed description on the APIs, see Segments.

Segments Criteria

The criteria for a Segment is a JSON tree-like structure. Multiple AND, OR, and NOT operations can be nested to form complex Segments. Here’s an example of how to create a simple Segment that combines two tags. In this example breaking-news use case, the recipient will have opted in to breaking news stories in general, and more specifically, breaking political stories. Allowing users to select the specificity of the story types they wish to receive is a good way to optimize the overall relevance of the alerts that you send.

For details on the location features in segments, see Location.

Basic “AND” Usage
{
"criteria": {
  "and": [
      {
          "tag": "breaking_news_alerts"
      },
      {
          "tag": "politics_stories"
      }
  ]
}

Here’s an example of a Segment that combines one location with one tag.

{
"criteria": {
  "and": [
      {
          "location": {
              "date": {
                  "recent": {
                      "days": 7
                  }
              },
              "id": "4oFkxX7RcUdirjtaenEQIV"
          }
      },
      {
          "tag": "sf_giants_fan"
      }
  ]
}

Pushes to this Segment go to any user that has been in San Francisco (location 4oFkxX7RcUdirjtaenEQIV) in the past 7 days, and also has the tag “sf_giants_fan”. Users in San Francisco that do not have the sf_giants_fan tag would not receive the push, because they don’t meet both criteria. Anybody who has location disabled, or who had an unknown location in the past 7 days would not receive the push.

Basic “OR” Usage
{
"criteria": {
  "or": [
      {
          "location": {
              "date": {
                  "days": {
                      "end": "2012-08-10",
                      "start": "2012-08-06"
                  }
              },
              "id": "4oFkxX7RcUdirjtaenEQIV"
          }
      },
      {
          "location": {
              "date": {
                  "days": {
                      "end": "2012-08-10",
                      "start": "2012-08-06"
                  }
              },
              "id": "00xb78Jw3Zz1TyrjqRykN9"
          }
      }
  ]
}

Notice the “and” on the outer layer has changed to an “or”. Pushes to this Segment would go to any user that had been to San Francisco or New York in the time range.

Basic “NOT” Usage
{
"criteria": {
   "and": [
      {
         "not": {
            "location": {
               "date": {
                     "days": {
                        "end": "2012-08-10",
                        "start": "2012-08-06"
                     }
                  },
                  "id": "4oFkxX7RcUdirjtaenEQIV"
               }
            }
         }
      ]
   }
}

Notice that even though there is just one criteria, the “and” wrapper for each condition is still there. If the criteria within the and is met, the push will be sent to that user. Also notice that within the “and” is a “not”. The “not” flips the criteria. Pushes to this Segment will be sent to users that were not in San Francisco between 2012-08-06 and 2012-08-10. We will push to all users that have registered a location during the date range, as long as they weren’t in San Francisco during the time range. We do not push to users with unknown locations (i.e. if we don’t know where they were, we don’t make any guesses about if they were or weren’t in San Francisco).

Nesting and Combining “AND”, “OR”, and “NOT”
{
"criteria": {
  "and": [
      {
          "or": [
              {
                  "location": {
                      "date": {
                          "recent": {
                              "weeks": 1
                          }
                      },
                      "id": "4oFkxX7RcUdirjtaenEQIV"
                  }
              },
              {
                  "location": {
                      "date": {
                          "recent": {
                              "weeks": 1
                          }
                      },
                      "id": "00xb78Jw3Zz1TyrjqRykN9"
                  }
              }
          ]
      },
      {
          "or": [
              {
                  "tag": "technology"
              },
              {
                  "tag": "business"
              }
          ]
      }
  ]
}

This Segment is “(San Francisco OR New York) AND (technology OR business)”. A user in San Francisco that likes technology would be in the Segment. A user in New York that likes business would be in the Segment. A user in Chicago that likes business would not be in the Segment.

You can nest and, or, and not to 10 levels via the API. You can create some highly advanced Segments. If you have any uneasiness, try building a Segment in the Urban Airship user interface, then retrieving the Segment via the API to see how it was constructed.

Location

Our Location service gives you the ability to target specific users for a notification based on a previously known location for the targeted device. When combined with Segments, Location becomes another powerful dimension with which you can build very specific messaging rules and campaigns. Use of the Location API within the Segments feature requires an Enterprise Urban Airship account. If you are an Enterprise customer and would like to add Location Targeting to your suite of Urban Airship services, please contact your account manager.

For a detailed description on the location APIs, see Location and Segments.

Relevance through Location + Time

With Location activated in your Urban Airship account, Segments allows you to push to users based on where they were most recently seen, and it also lets you push to users based on where they have been in the past. For example, you can say define a Segment as “users in California in the past 90 days”. If a user is currently in New York, but has visited California in the past 90 days, the user would match the Segment definition and receive the push. You can limit the time component to a smaller window to push only to users that are currently in California (i.e. “users in California in the past 2 hours”). You can schedule Segments pushes so you can reach the right users in the right place at the right time. For example, if an baseball game is starting at AT&T Park tomorrow at 12:15pm PDT, you could define a Segment as “users inside AT&T Park in the past 2 hours”, and schedule the push to be sent at 19:30 UTC. The “Welcome to the game!” push would go to users that had been inside AT&T Park between 10:15 and 12:15 PDT. Various time granularities are supported (minute, hour, day, week, month, year).

Push to Location Criteria

The criteria for a Segment is a JSON tree-like structure. Multiple AND, OR, and NOT operations can be nested to form complex Segments. Here’s an example of a Segment that combines one location with one tag.

Basic “and” Usage
"criteria": {
  "and": [
      {
          "location": {
              "date": {
                  "recent": {
                      "days": 7
                  }
              },
              "id": "4oFkxX7RcUdirjtaenEQIV"
          }
      },
      {
          "tag": "sf_giants_fan"
      }
  ]
}

Pushes to this Segment go to any user that has been in San Francisco (location 4oFkxX7RcUdirjtaenEQIV) in the past 7 days, and also has the tag “sf_giants_fan”. Users in San Francisco that do not have the sf_giants_fan tag would not receive the push, because they don’t meet both criteria. Anybody who has location disabled, or who had an unknown location in the past 7 days would not receive the push.

Basic “or” Usage
"criteria": {
    "or": [
        {
            "location": {
                "date": {
                    "days": {
                        "end": "2012-08-10",
                        "start": "2012-08-06"
                    }
                },
                "id": "4oFkxX7RcUdirjtaenEQIV"
            }
        },
        {
            "location": {
                "date": {
                    "days": {
                        "end": "2012-08-10",
                        "start": "2012-08-06"
                    }
                },
                "id": "00xb78Jw3Zz1TyrjqRykN9"
            }
        }
    ]
}

Notice the “and” on the outer layer has changed to an “or”. Pushes to this Segment would go to any user that had been to San Francisco or New York in the time range.

Basic “not” Usage
"criteria": {
    "and": [
        {
            "not": {
                "location": {
                    "date": {
                        "days": {
                            "end": "2012-08-10",
                            "start": "2012-08-06"
                        }
                    },
                    "id": "4oFkxX7RcUdirjtaenEQIV"
                }
            }
        }
    ]
}

Notice that even though there is just one criteria, the “and” wrapper for each condition is still there. If the criteria within the and is met, the push will be sent to that user. Also notice that within the “and” is a “not”. The “not” flips the criteria. Pushes to this Segment will be sent to users that were not in San Francisco between 2012-08-06 and 2012-08-10. We will push to all users that have registered a location during the date range, as long as they weren’t in San Francisco during the time range. We do not push to users with unknown locations (i.e. if we don’t know where they were, we don’t make any guesses about if they were or weren’t in San Francisco).

Nesting and Combining “and”, “or”, and “not”
"criteria": {
    "and": [
        {
            "or": [
                {
                    "location": {
                        "date": {
                            "recent": {
                                "weeks": 1
                            }
                        },
                        "id": "4oFkxX7RcUdirjtaenEQIV"
                    }
                },
                {
                    "location": {
                        "date": {
                            "recent": {
                                "weeks": 1
                            }
                        },
                        "id": "00xb78Jw3Zz1TyrjqRykN9"
                    }
                }
            ]
        },
        {
            "or": [
                {
                    "tag": "technology"
                },
                {
                    "tag": "business"
                }
            ]
        }
    ]
}

This Segment is “(San Francisco OR New York) AND (technology OR business)”. A user in San Francisco that likes technology would be in the Segment. A user in New York that likes business would be in the Segment. A user in Chicago that likes business would not be in the Segment.

You can nest and, or, and not to 10 levels via the API. You can create some highly advanced Segments. If you have any uneasiness, try building a Segment in the Urban Airship user interface, then retrieving the Segment via the API to see how it was constructed.

Recent Location vs. Absolute Dates

You will notice from above that the “date” section in location criteria can be “recent”, or it can include hard dates.

{
    "location": {
        "date": {
            "recent": {
                "days": 5
            }
        },
        "id": "4oFkxX7RcUdirjtaenEQIV"
    }
}

This Segment includes anybody in San Francisco in the past 5 days. “Past 5 days” is calculated dynamically at the time a push is sent to our API, so it’s a moving window. If it is currently 11:00 2012-08-14 UTC, “past 5 days” would be include the partial UTC day for the 14th, then the full UTC days for 13th, 12th, 11th, and 10th. If you create a Segment with “past 1 hours” at 11:02am, the partial hour for 11am would be included, and that’s all. To avoid this, say “past 60 minutes” or “past 2 hours”.

You can also post absolute time ranges. For a variety of reasons we don’t store the raw location data, we store buckets of when and where we have seen people, so you still need to provide a granularity measurement.

"location": {
    "date": {
        "days": {
            "end": "2012-08-10",
            "start": "2012-08-06"
    }
    },
    "id": "4oFkxX7RcUdirjtaenEQIV"
}

The granularities and dates you use for either recent or absolute time ranges must fall within the constraints mentioned in GET /api/segments/dates (see below). You create a Segment that includes “anybody in San Francisco in the past 6 months”, but you are not allowed to create a Segment that includes “anybody in San Francisco in the past 259200 minutes”, even though they are technically the same.

For more information on creating and using segments, see Segments.

Location Boundary Types and Aliases

The location criteria in Segments comes pre-loaded with 2.5M ready-to-use location boundaries (a.k.a. geofences). These location boundaries can be dynamically access via our API by using aliases that correspond to real-world references. For example, to look up the id for the US state of California, you can use the from-alias endpoint:

For a full reference, see Location.

GET /api/location/from-alias?us_state=CA

{
    "bounds": [
        32.528832,
        -124.482003,
        42.009517,
        -114.131211
    ],
    "centroid": [
        37.215297,
        -119.663837
    ],
    "id": "5LajTWicgiQKuX1RBBLDRI",
    "properties": {
        "abbr": "CA",
        "aliases": {
            "fips_10-4": "US06",
            "hasc": "US.CA",
            "state": "US06",
            "us_state": "CA"
        },
        "boundary_type": "province",
        "boundary_type_string": "State/Province",
        "name": "California",
        "source": "tiger.census.gov"
    },
    "type": "Feature"
}

To look up the id for the United States of America, you could also use the from-alias endpoint:

GET /api/location/from-alias?iso_3166-1_a2=US

{
    "bounds": [
        18.930138,
        -179.142471,
        71.41218,
        179.78115
    ],
    "centroid": [
        45.68716,
        -112.493107
    ],
    "id": "7dbFezbkl6eY9pmxp8u5ei",
    "properties": {
        "aliases": {
            "iso_3166-1_a2": "US",
            "iso_3166-1_a3": "USA",
            "iso_3166-1_n3": "840"
        },
        "boundary_type": "country",
        "boundary_type_string": "Country",
        "name": "United States",
        "source": "naturalearthdata.com"
    },
    "type": "Feature"
}

Notice that there are other aliases for the “country” dataset, such as iso_3166-1_a2 (ISO 3166-1 alpha-2), iso_3166-1_a3 (ISO 3166-1 alpha-3), and iso_3166-1_n3 (ISO 3166-1 numeric). Because different systems of the world refer to countries in different ways, we provide multiple ways to access a polygon with aliases.

A more common example is US ZIP codes. You may have a field in your database that has a ZIP code for each user. If you wanted automatically create a Segment for each ZIP code, you could look each ZIP code using the from-alias endpoint:

GET /api/location/from-alias?us_zip=94123

{
    "bounds": [
        37.791703,
        -122.452803,
        37.809728,
        -122.423601
    ],
    "centroid": [
        37.800786,
        -122.438602
    ],
    "id": "5CWR1UyVDs312Zy5fJXFyH",
    "properties": {
        "aliases": {
            "us_zip": "94123"
        },
        "boundary_type": "postalcode",
        "boundary_type_string": "Postal/ZIP Code",
        "name": "94123",
        "source": "tiger.census.gov"
    },
    "type": "Feature"
}

API Basics

This section provides an overview of the basic concepts and terminology associated with sending notifications and rich messages via the Urban Airship API. With the introduction of Version 3 of our API, (see: Overview: Urban Airship API Version 3) we have simplified the request format, introduced simple cross-platform selection and overrides, and made audience selection easier than ever.

For platform-specific peculiarities, please be sure to reference Platform-Specific Push Notes for each platform you are sending to.

For a more comprehensive list of examples using our various API endpoints, please visit our Urban Airship API v3 section.

And if you’re looking for details on how to send messages via our web application, visit our User Guide .

Urban Airship Messaging APIs: General Concepts

Sending push notifications or rich messages from your server is straightforward. When writing code to send a message, there are five top-level attributes to consider when formatting your request. Details on each attribute are included below.

  1. Audience
  2. Notification Payload
  3. Device Types
  4. Delivery Options
  5. Rich Message Content (Optional)

Once you have defined the content, audience and options for your message, you are ready to send. Now you only need to decide when to send it.

You can choose to send now (use the /push/ API) or send later (use the /schedule/ API). You may also want to test your message first by validating the format via our /push/validate/ endpoint. For details on sending, scheduling, and validating messages, please see the following sections in our Reference section:

Audience Selection

An audience selector determines the set of devices that a push will be delivered to. A valid audience selector is a JSON expression which can identify a single device, a segment, a tag, an alias, a broadcast to all devices, or a logical combination of any of those atomic selectors. It unifies the means of selecting target devices by device ID, tag & alias with the Segments location criteria and logical operators.

There are a number of ways to define an audience with selectors ranging from individual device IDs to a broadcast notification, which sends the notification immediately to all eligible opted-in devices.

For detailed explanation of the various audience selectors and available combinations thereof, please see Audience Selection.

Notfication Payload

The notification payload is a JSON object assigned to the "notification" attribute on a Push Object, which contains the actual contents to be delivered to devices. At its simplest, the payload consists of a single string-valued attribute, "alert", which sends a push notification consisting of a single piece of text.

 {
     "audience" : "all",
     "device_types" : "all",
     "notification" : {
         "alert" : "Hello from Urban Airship."
     }
 }

Each supported platform has an optional platform override section, which can simply change the value of "alert" for that platform, or provide more detailed platform-specific payload data.

For detailed explanation of the various notification payloads and platform specific overrides, please see Notification Payload.

Device Type Selection

Restricting the push by device type is another form of audience selection. It’s handled separately, effectively as a filter. Generally you will wish to send the message to all supported platforms, which is handled simply by setting the “device_types” attribute to “all”, like so:

 {
     "audience" : "all",
     "device_types" : "all",
     "notification" : {
         "alert" : "Hello from Urban Airship."
     }
 }

The value of the "device_types" attribute may be either an array, containing one or more strings identifying platforms, or the string value "all", indicating the push should be sent to all platforms. Valid platform identifiers are:

  • "ios"
  • "android"
  • "blackberry"
  • "wns"
  • "mpns"

Examples

Sending a push only to Microsoft platforms:

{
   "audience" : "all",
   "notification" : {
      "alert" : "Oh hai Winders!"
   },
   "device_types" : [ "mpns", "wns" ]
}

Sending a push to the “Big Two”:

{
   "audience" : "all",
   "notification" : {
      "alert" : "Oh hai, 800-lb gorillas"
   },
   "device_types" : [ "ios", "android" ]
}

Delivery Options

The “options” attribute is a JSON dictionary for specifying non-payload options related to the delivery of the push, such as expiry. Currently, expiry is the only publicly available push option but we will continue to expose new options for this attribute in future releases.

For more detail on options, please see Push Options in our API v3 Reference page.

Message Center Content

The final top-level attribute that can be included in the notification request is “message”, which provides the content for a Rich message that will appear in the Message Center. For detail on formatting Rich App Page requests, see Rich App Pages.

Scheduling Options

In order to send a notification and/or message at a later time, i.e., at any time later than immediately, please use

POST /api/schedules/

For detail on scheduling notifications as well as managing and updating your list of schedules, please see: Schedules.

Push to Local Time

Push to Local time is an option, when scheduling a push, to have it delivered at the same time of day across all time zones in your app’s audience.

Because app audiences are global, and the fact that many types of messages are relevant only at certain times of day, this is often desirable.

Suggested uses:
  • For time-sensitive offers, such as a lunch coupon
  • To optimize the time of day to deliver messages for better response, e.g. in time for breakfast or after work
  • Ensure that recipients will not receive a message in the middle of the night

Note

  • An app must be using our SDK to take advantage of this feature, since it depends on our client library setting time zone tags for each device.
  • If you have not used our SDK in the past, and have recently rolled out an app update, only users who have updated your app will be addressable through this feature. A push to local time will not reach your full app audience until they do.
  • It is possible, though extremely unlikely, that a user could receive a duplicate push while traveling across time zones, depending on their app interactions and cell phone settings.
  • When building a report, you can group the multiple pushes generated from your single scheduled message using the group_id, which will be set to the scheduled id returned when you schedule your message.

For more detail on scheduling pushes for local time delivery, see Local Time Delivery.

UA Server Libraries

We also provide drop-in server libraries for Python, PHP and Java to facilitate even simpler integrations.

For more information on the libraries, please see this post from our Developer’s Blog and look for the documentation in our reference section: Urban Airship Server Libraries.

Platform-Specific Push Notes

iOS Push

iOS Push uses the APNS push system.

The primary identifier for iOS push is the channel, which is generated the first time the user runs the application with the mobile client library installed. This channel ID is present whether or not a device token is available, and stays the same even if the device token changes.

Note

Channels were introduced in the 4.0 release of the iOS SDK; earlier general release SDKs will only return the device token.

The APNS specific identifier, the device token, can also be used to send notifications. Its use has been superseded by the channel, however, so new applications should use the channel and existing applications should be upgraded to use the channel soon. Device tokens are only valid on the appropriate system; that is, a device token generated by a production application (ad hoc or App Store builds) can only be used on the production push system, and development applications can only be used on the APNS sandbox.

Here is an example request using the command line tool curl to send a push using the Push Notification API:

curl -X POST -u "<application key>:<application master secret>" \
   -H "Content-Type: application/json" \
   -H "Accept: application/vnd.urbanairship+json; version=3;" \
   --data '{"audience": {"alias": "myalias"}, "notification": {"alert": "Hello!"}, "device_types": ["ios"]}' \
   https://go.urbanairship.com/api/push/

iOS has several features not present in other platforms. These can be specified in the ios override in the notification object.

Note

The maximum message size is 2 KB. This includes the alert, badge, sound, and any extra key/value pairs in the notification section of the payload.

Alerts

iOS push alerts can be either a simple string, or a JSON object with button text or localization instructions. For more information, see The Notification Payload in Apple’s Local and Push Notification Programming Guide. All of the options can be used with Urban Airship.

This JSON payload uses the action-loc-key example from Apple’s document:

{
   "audience": {"ios_channel" : "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"},
   "notification": {
      "ios": {
         "alert" : {
            "body" : "Bob wants to play poker",
            "action-loc-key" : "PLAY"
         }
      }
   },
   "device_types": ["ios"]
}

Badge and Autobadge

Another feature of iOS is badging, which sets a number on the application icon, usually representing unread messages or waiting actions inside the application.

The badge is the number within a red circle that appears on an application’s home screen icon. The badge is generally used to denote the number of unread or otherwise unattended-to pieces of content within the app, e.g., unread messages or top news stories.

Apple requires an integer be sent as the badge value in the APNS payload, even if there is an existing badge value on the app and there is no change. If no badge is sent, an existing badge will not change.

When the badge transitions from a non-zero value to a zero value, either from a push or direct application manipulation, the badge will be removed on the application icon and all push messages related to the application will be removed from the notification center. When the badge has no transitions (for example, when a push message contains a badge value of 0 or no badge is sent consecutively), the push messages will remain in the notification center until a transition occurs.

An application is responsible for managing the badge number. If the application does not clear the badge, the push message(s) will remain in the notification center. After an application receives a push notification, it should remove the icon badge by setting the applicationIconBadgeNumber property of the UIApplication object to 0.

Urban Airship can keep track of what badge value the user sees. Because the value can often be relative to another value which may be unknown to you, the app publisher, we provide a handy way to update the integer to represent the proper count, translating it on the fly. This Urban Airship feature is called autobadge.

Urban Airship supports the following three types of autobadges: auto, increment, and decrement:

  • auto: takes the current stored badge value and inserts it
  • +1: takes the badge value from the database, increments by the number after the + sign, and also increments our stored badge by that number.
  • -1: decrements instead of incrementing.

The autobadge value is normally reset to 0 when the device registers. The iOS client library can also set the badge to an explicit number from inside the application.

Autobadge examples

Starting with a device token with a stored autobadge value of 4, the following push is sent.

{
   "audience": {"alias": "foo"},
   "notification": {
      "ios": {
         "badge": "auto",
         "alert": "My badge is still 4!"
      }
   },
   "device_types": ["ios"]
}

After this payload, the “foo” user still has a badge of 4 and the badge value sent on to Apple was also 4.

{
   "audience": {"alias": "foo"},
   "notification": {
      "ios": {
         "badge": "+1",
         "alert": "My badge is now 5!"
      }
   },
   "device_types": ["ios"]
}

After this push, the “foo” user has a badge of 5, and the badge value sent on to Apple was 5.

Starting again with a badge value of 4:

{
   "audience": {"alias": "foo"},
   "notification": {
      "ios": {
         "badge": "-1",
         "alert": "My badge is now 3!"
      }
   },
   "device_types": ["ios"]
}

Sounds

By default, push notifications are silent, seen but not heard. To specify an alert sound to be played when the push notification is received, add a sound key to the ios override section.

{
   "audience": {"alias": "foo"},
   "notification": {
      "ios": {
         "alert": "Hello, I came with an alert sound!",
         "sound": "default"
      }
   },
   "device_types": ["ios"]
}

Unless you ship custom sounds with your app, only the default alert sound is available. Custom alert sounds should be included in your main application bundle; see Custom Alert Sounds for more.

Custom alert sounds cannot be longer than 30 seconds. If a sound exceeds this limit, the default sound will be played instead. Keep this limitation in mind when including rickroll Easter eggs in your app.

The test application is bundled with 4 test sounds. To send a sound notification to the test application you can use any of the following:

  • pig
  • cat
  • cow
  • frog

You can test your own custom sounds simply by adding your sound files to the test application and reinstalling it on your device. Your sound files just have to be in the main application bundle.

Extras

Any extra key/value pairs should go within the "ios" section of the notification.

{
   "audience": "all",
   "notification": {
      "alert": "Extras example",
      "ios": {
        "extra": {
            "url": "http://example.com",
            "story_id": "1234",
            "moar": {"key": "value"}
         }
      }
   },
   "device_types": ["ios"]
}

Newsstand

Apple’s Newsstand service uses push to trigger background downloading of new content. Use the content-available flag to trigger this.

Note

Newsstand pushes can only be used once every 24 hours, and are only available for Newsstand applications.

{
   "audience": "all",
   "notification": {
      "ios": {
         "content-available": true
      }
   },
   "device_types": ["ios"]
}

Quiet Time

Quiet time is an Urban Airship feature to allow your users to opt-out of receiving alerts or sounds during a specified period. If a push is attempted during quiet time, alert and sound will be stripped. If nothing else (like a badge update) is present in the push notification request, it will be dropped.

Push Expiry

You can also send along an expiry time for APNS to cease trying to deliver a push. This is also known as “time to live”. It can be an integer indicating the number of seconds from when we receive your request, or an absolute timestamp in ISO UTC format. For a scheduled push with an integer, the countdown will start at the scheduled delivery time.

An integer value of 0 (zero) will be passed directly to Apple, and indicates that the push should be delivered immediately and not stored by APNS (“now or never” delivery).

If a global expiry value has been provided in the push options object, this will override it.

{
   "audience": "all",
   "notification": {
      "ios": {
         "alert": "This message will self-destruct in 1 minute (if it has not successfully been delivered)",
         "expiry": 60
      }
   },
   "device_types": ["ios"]
}

Title

Notifications to Apple Watch are specified by the title attribute, which will be an iOS Platform Override in the Urban Airship API. The text passed to the title attribute will be the title text that appears in the short look interface.

For more information on the title attribute in the aps dictionary, see Table 3–2 in the APNs documentation under The Notification Payload.

Example Request:

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

{
   "audience": "all",
   "device_types": ["ios"],
   "notification": {
      "ios": {
         "title": "New Sale!",
         "category": "shop-links",
         "alert": "We've added new styles to the seasonal sale. Shop now!"
      }
   }
}
JSON Parameters:
  • title – (String) A short string describing the purpose of the notification.
  • category – (String) Specifies the display style of the watch notification. See The Category Field for more details.

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",
   ]
}

The Category Field

Including a valid category key will trigger a custom display style for your notification. The category key specifies two customization options:

The category key is set to Nil by default, and the default display style will occur unless it is overridden.

Android Push

Android Push uses the Google Cloud Messaging push system.

An Android Channel is the unique Urban Airship identifier required in order to push to an Android device via our API. Channels have superseded APIDs as the identifier as of October 2014 with the release of the 5.0 version of the Urban Airship SDK.

Here is an example request using the command line tool cURL to send a push using the Push Notification API:

curl -X POST -u "<application key>:<application master secret>" \
   -H "Content-Type: application/json" \
   -H "Accept: application/vnd.urbanairship+json; version=3;" \
   --data '{"audience": {"alias": "myalias"}, "notification": {"alert": "Hello!"}, "device_types": ["android"]}' \
   https://go.urbanairship.com/api/push/

Android has several features not present in other platforms. These can be specified in the android override in the notification object.

Note

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

The 4096-byte limit is only valid when sending via Urban Airship API v3 over GCM. Using older versions of the Urban Airship API OR unsupported legacy Google- or Urban Airship-developed transport systems will most likely result in a 1024 maximum message size. Contact Urban Airship Support if you experience issues with message limits.

Alerts

Unlike iOS, Android push alerts are always simple strings.

Extras

Any extra key/value pairs should go within an “android” section of the notification.

{
   "audience": "all",
   "notification": {
      "alert": "Extras example",
      "android": {
        "extra": {
            "url": "http://example.com",
            "story_id": "1234",
            "moar": "{\"key\": \"value\"}"
         }
      }
   },
   "device_types": ["android"]
}

Warning

Never use the word "data" as the key in a key/value pair.

According to the Android Developer docs, "data" is a reserved word for GCM. Using reserved words in the payload can result in intended values being overwritten.

Collapse Key, Time to Live, and Delay While Idle

You can also set a collapse_key, time_to_live, and delay_while_idle for GCM pushes sent via Urban Airship. Please see the GCM Advanced Topics documentation for more information about each of these features related to the lifetime of a message.

If time_to_live is set to 0, this indicates that GCM should send the message now, but not store it in case of non-delivery. An example scenario for this type of “now or never” message is an incoming call notification, or any sort of event reminder which would have no value if the event had already ended.

You can set time_to_live as either an absolute ISO UTC timestamp, or number of seconds with a duration from 0 to 2,419,200 seconds (4 weeks). Messages without an expiry will default to the 4 week maximum period for retries by GCM.

{
   "audience": {"android_channel": "some Android Channel"},
   "notification": {
         "android": {
             "alert": "Hello",
             "collapse_key": "gobbledygook",
             "time_to_live" : 10,
             "delay_while_idle" : true
         }
       },
   "device_types": ["android"]
}

BlackBerry Push

Blackberry push uses the Blackberry Push Service.

A Blackberry PIN is the identifier used in order to reach a Blackberry device.

Here is an example Blackberry push request using the command line tool cURL to send a push using the Push Notification API:

curl -X POST -u "<application key>:<application master secret>" \
   -H "Content-Type: application/json" \
   -H "Accept: application/vnd.urbanairship+json; version=3;" \
   --data '{"audience": {"alias": "myalias"}, "notification": {"alert": "Hello!"}, "device_types": ["blackberry"]}' \
   https://go.urbanairship.com/api/push/

Register a BlackBerry PIN

PUT /api/device_pins/<device_pin>

In order to push to a Blackberry device, you must pre-register the PIN. Simple registration can be done without a body.

Example request:

PUT /api/device_pins/12345678 HTTP/1.1
Authorization: Basic <application authorization string>
Status Codes:
  • 200 – The tag already exists.
  • 201 – The tag was created.
  • 400 – The tag is is invalid.

Use the Application Key and Application Secret to authenticate these requests. For more information, see App Keys & Secrets: Security.

Device PINs should be 8 character strings, without spaces.

If you wish to include additional information about a device PIN in the push, e.g., an alias or tags, include a JSON payload along with this request. Set the Content-Type header of your request to be application/json, and specify your options in the body of the request.

Example request:

PUT /api/device_pins/12345678 HTTP/1.1
Authorization: Basic <application authorization string>
{
    "alias": "example_alias",
    "tags": [
       "tag1",
       "tag2"
    ]
}

Not including one of these keys removes it from the device pin. In other words:

  • A PUT without an alias will remove any associated alias if the device pin already exists.
  • A PUT with an empty tag list will remove any associated tags.

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/device_pins/<pin>/

Fetch Device PIN Information

GET api/device_pins/<device_pin>

Example request:

{
    "device_pin": "some device pin",
    "alias": "your_user_id",
    "last_registration": "2009-11-06 20:41:06",
    "created": "2009-11-06 20:41:06",
    "active": true,
    "tags": [
        "tag1",
        "tag2"
    ]
}

Mark a Device Pin as Inactive

DELETE /api/device_pins/<device_pin>

No notifications will be delivered to it until a PUT is executed again.

Status Codes:
  • 204 – No content, no payload needed

Push

POST /api/push/

Sends a push message to one or more users.

The payload is in JSON with content-type application/json with the following structure.

Example request:

POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Content-Type: application/json
Accept: application/vnd.urbanairship+json; version=3;
{
   "audience" : {
      "device_pin" : "1q2w3e4r"
   },
   "device_types" : ["blackberry"],
   "notification" : {
      "alert" : "Hey what's up"
   },
}

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",
   ]
}

For the audience parameter, only one of alias, tag, segment, or device_pin is required, but they can be mixed and matched as much as you’d like.

Status Codes:
  • 202 Accepted – The push notification has been accepted
  • 400 Bad Request – The request body was invalid, either due to malformed JSON or a data validation error. See the response body for more detail.
  • 401 Unauthorized – The authorization credentials are incorrect
  • 406 Not Acceptable – The request could not be satisfied because the requested API version is not available

The platform override section for Blackberry uses the attribute blackberry:

{
   "audience" : "all",
   "device_types" : [ "ios", "blackberry" ],
   "notification" : {
      "ios" : {
         "alert" : "Hello, iDevices"
      },
      "blackberry" : {
         "alert" : "Hello Blackberry Nation!"
      }
   }
}

The batch push endpoint has been deprecated in API v3. In order to send multiple pushes in one call, simply include the different notifications in an array within the request payload:

[
   {
      "audience" : {
         "OR" : [
            { "device_pin" : "12345678" },
            { "device_pin" : "abcdefgh" }
         ]
      },
      "device_types" : ["blackberry"],
      "notification" : {
         "alert" : "Hello from Urban Airship"
      }
   },
   {
      "audience" : {
         "device_pin" : "1234abcd"
      },
      "device_types" : ["blackberry"],
      "notification" : {
         "alert" : "Goodbye from Urban Airship"
      }
   }
]
Broadcast

Sending a broadcast is indicated by using the string "all" as the audience selector value.

Example request:

{
   "audience" : "all",
   "notification" : {
      "blackberry" : {
         "alert" : "Greetings, Blackberry Nation!"
      }
   },
   "device_types": ["blackberry"]
}
status 200:OK
status 400:Bad Request (if structure was invalid)

Windows Push

The Urban Airship API supports both Windows Push Notification Services (WNS) for Windows Runtime apps and Microsoft Push Notification Service (MPNS) for Windows Phone 8 apps.

WNS and MPNS have several features not present in other platforms. These can be specified in the wns or mpns overrides in the notification object. See Platform Overrides for more details on platform-specific overrides.

Windows Push Identifier

An Airship Push ID (APID) is the unique Urban Airship identifier required in order to push to a Windows 8 or Windows Phone 8 device via our API.

Each new installation of an application generates a new APID. For example, if a user uninstalls and then reinstalls your app, you will get a new APID for the app.

Here is an example request using the command line tool cURL to send a push using the Push Notification API:

$ curl -X POST -u "<application key>:<application master secret>" -H "Content-Type: application/json" -H "Accept: application/vnd.urbanairship+json; version=3;" --data '{"audience": {"alias": "myalias"}, "notification": {"alert": "Hello Windows people!"}, "device_types": ["wns","mpns"]}' https://go.urbanairship.com/api/push/

Audience Selection

To send to a specific Windows device or devices, specify the Windows APID(s) in the wns or mpns key for the audience attribute.

{
   "audience" : {
      "wns" : "3644dada-d807-a2da-19d0-90d902ea7636"
   }
}

Platform overrides

“alert” “toast” “tile” “badge”

Toast Notifications

Toast notifications are unique to Windows devices and can be specified as an attribute within the platform override for WNS or MPNS notifications. In the example below, we specify the text in a toast alert in the mpns object.

For more information about Windows-specific attributes in our API, see Windows 8.

{
   "audience": "all",
   "notification": {
      "mpns": {
         "toast": {
            "text2": "Hello",
            "text1": "Urban Airship!"
         }
      },
      "wns": {
         "toast": {
            "binding": {
               "text": [
                  "Hello Urban Airship!"
            ],
            "template": "ToastText01"
            }
         }
      }
   },
   "device_types": ["mpns", "wns"]
}
Audio

Optionally specify the toast alert sound with the audio key in the notification object.

{
   "audience": "all",
   "notification": {
      "wns": {
         "toast": {
            "audio": {
               "sound": "reminder"
            }
         }
      }
   },
   "device_types": ["wns"]
}
Duration

Optionally specify a display duration for your toast. There are two values: “short” (the default) and “long”. Use “long” only if your notification is part of a scenario such as an incoming call or appointment reminder. For more information

Windows 8 devices have the ability to set the duration of a toast to be displayed on the device.

{
   "audience": "all",
   "notification": {
      "wns": {
         "toast": {
            "duration": "short"
         }
      }
   },
   "device_types": ["wns"]
}
Templates

Windows 8 devices have the ability to specify a templated toast notification from Microsoft’s list of Toast Templates document.

{
   "audience": "all",
   "notification": {
      "wns": {
         "toast": {
            "binding": {
               "text": [
                  "Hello Urban Airship!"
            ],
            "template": "ToastText01"
            }
         }
      }
   },
   "device_types": ["wns"]
}

Badges

Value Update

Windows 8 devices have the ability to to specify a badge value to be used to set a number on the application tile, usually representing unread messages or waiting actions inside the application.

{
   "audience": "all",
   "notification": {
      "wns": {
         "badge": {
            "value": "1"
         }
      }
   },
   "device_types": ["wns"]
}
Glyph Update

In addition to numbers, there is also a fixed set of image glyphs that can be set on the badge.

{
   "audience": "all",
   "notification": {
      "wns": {
         "badge": {
            "glyph": "busy"
         }
      }
   },
   "device_types": ["wns"]
}

Tiles

Windows 8 and Windows Phone 8 have the ability to update live tiles on the home screen. With the use of templates, you can update any tile on the home screen.

{
   "audience": "all",
   "notification": {
      "mpns":{
         "tile": {
            "count": 11,
            "wide_content_1": "Wide Content 1",
            "wide_content_2": "Wide Content 2",
            "wide_content_3": "Wide Content 3",
            "title": "Title",
            "template": "IconicTile",
            "background_color": "#FFAA0000"
         }
      }
   },
   "device_types": ["mpns"]
}
{
   "audience": "all",
   "notification": {
      "wns": {
         "tile": {
            "binding": [
               {
                  "text": [
                     "TileWideImageAndText01"
                  ],
                  "image": [
                        "/Assets/1.jpg"
                  ],
                 "template": "TileWideImageAndText01"
               }
            ]
         }
      }
   },
   "device_types": ["wns"]
}

RSS and Atom Feed Push

One of Urban Airship’s features is a system to send push notifications based on an update in an RSS or Atom feed. Our system will check the feed at least every 15 minutes, looking for new posts. If it finds any it sends out a push based on the configured template.

Should I use feeds?

The feed system works best with existing feeds from off-the-shelf applications with well-tested RSS or Atom feeds, like Wordpress or other popular blog platforms. Feeds are kind of like HTML; browsers try their best to work around errors, but accurate, timely push requires a higher level of correctness than simple display.

If you’re considering creating a new feed for the purpose of push, or implementing a new application to manage it, the push API is a better choice. It allows you to have total control over the timing, content, and recipients of your pushes. Another consideration is how time-sensitive your notification is. For breaking news or other alerts where minutes matter, the polling nature of feed to push may not be ideal; the API or PubSubHubbub (see below) might be better.

What makes a good feed?

A good feed should pass the W3C Feed Validator, and each entry should contain a GUID, a globally unique identifier. This allows the feed reading system to accurately know when an entry is new — without this, edited entries might appear to be new entries.

In addition, if your platform supports it, you might consider turning on PubSubHubbub. PubSubHubbub is a protocol for instant updates for feeds. With this enabled our feed system does not need to check for new updates; instead, your application will alert our server when new data is available. The Wordpress PubSubHubbub Plugin works well and requires no configuration.

Configuring Feeds

Feeds can be configured for each application in the dashboard, in the Messaging section. The feed template is used to construct a usage of the Push API.

If, when a feed item comes in, the resulting payload is too long, we will automatically truncate it to fit.

Note

While doing initial testing, it can be helpful to send to one device and to use a regularly updated feed. The Breaking News or another news site might be a good choice.

If you are configuring many feeds or feeds for multiple applications, the Feeds might be useful for you.

Retrieving Data & Analytics

Device Feedback

APNS has a feedback system to report when a push is delivered to a device, but the application has been uninstalled. Urban Airship tracks these events and deactivates the device token, to ensure that you’re always following Apple’s rules.

You can query our system to get devices deactivated since your last call, using the Feedback API. This call takes a timestamp; simply feed the last time you queried into that timestamp, and you’ll always be up to date.

If you are sending unicast iOS push notifications, we recommend querying the feedback API once a day or so for applications with low traffic, or up to once an hour for very heavy traffic.

Exporting Device Data

If you want to download the entire list of device tokens, use the Device Token List API. This is a paginated query across all device tokens registered to your application.

Reports and Statistics

Our advanced reporting and analytics system is available as detailed graphs in the web application, and it is also available via API for integration in your own internal applications and dashboards. Every report your account has access to is available. See Reports for more information.

There is also a simple push statistics API, available for all applications. The Push Statistics API returns hourly counts of pushes for your application.

Rich App Pages

Requirements

In order to send Rich App Pages messages, you must integrate the Urban Airship SDK. Rich App Pages are supported on iOS, Android, and Amazon devices. See Platform for details.

Sending Messages

Each device receives a Channel ID from the SDK and registers the ID with Urban Airship. Independently, the SDK creates a “user” on the device, which is associated with the Channel ID. The purpose of this user is to allow access for rich message content via the Message Center.

Urban Airship provides the device with a unique, app-specific set of credentials which is then used by the app solely to retrieve Message Center content.

Note

Urban Airship will always create a user (even if no Channel ID is generated) by using whichever push identifier, e.g., device token, is available. Ultimately the rich content user and the Channel will be associated.

Messages are sent using the Rich Push API.

As with a normal push notification, you will:

  1. Select the audience
  2. Define the notification payload, and
  3. Specify device types

Rich App Pages add a single step, setting the content of the notification. Here’s an example of a push with a Rich App Page delivery:

{
    "audience": "all",
    "notification": {
        "alert": "New offer!"
    },
    "device_types": ["ios", "android"],
    "message": {
        "title": "This week's offer",
        "body": "<html><body><h1>blah blah</h1> etc...</html>",
        "content_type": "text/html",
        "extra": {
            "offer_id" : "608f1f6c-8860-c617-a803-b187b491568e"
        }
    }
}

For more information on sending rich push notifications, see Rich App Pages.