iOS Push

iOS Push uses the APNS push system. It is also available on Mac OS X, and uses the same APIs.

The primary identifier for iOS push is the device token. Each installation of iOS has two device tokens; one for production applications, and one for development applications (which uses 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 256 bytes. This includes the alert, badge, sound, and any extra key/value pairs in the notification section of the payload. We also recommend leaving as much extra space as possible if you are using our reporting tools, as a portion will be used to help with response tracking if it is available.

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 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": {"device_token": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660"},
   "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"]
}

Apple, StoreKit and iPhone are trademarks of Apple, Inc. Maponics Neighborhood Boundaries © Maponics 2012. DMA® is a registered service mark of The Nielsen Company. Used under License.