Apple Push Notification Service Programming Guide

Introduction

Push notifications—also known as remote notifications—let users learn when applications on their iPhone and iPod touch devices have data waiting for them on their servers. They use a persistent IP connection. When a device receives a notification for an application and that application isn’t running, it notifies the user through an alert message, a distinctive sound, or a number badging the application (or some combination of these). The user may then launch the application, which then downloads the data from its server, which is also known as its provider. Introduced in iPhone OS 3.0, push notifications serve the same purpose that a background application would on a desktop computer. (As you may know, background applications are not allowed on these handheld devices.)

Note: For usage guidelines for push notifications, see “Enabling Push Notifications” in iPhone Human Interface Guidelines.

This document tells what push notifications are and how to implement the feature for your applications. For the client-side implementation, familiarity with Objective-C and the Cocoa Touch frameworks is assumed. For the provider side of the implementation, knowledge of TLS/SSL and streaming sockets is helpful.

Organization of This Document

This document has the following chapters:

“What Are Push Notifications?” describes what push notifications are, how they are presented to users, and what advantages and requirements they bring to developers.

“Apple Push Notification Service” describes the central push service for transporting and routing notifications from provider to client application.

“Provisioning and Development” explains the steps for obtaining certificates from the iPhone Developer Program portal and setting up the development environment.

“Provider Communication with Apple Push Notification Service” describes the requirements and interfaces for provider communication with Apple Push Notification Service.

“iPhone OS Client Implementation” explains what a client application on an iPhone OS system must do to register and handle push (remote) notifications.

See Also

You might find these additional sources of information useful for understanding and implementing push notifications:

Security Overview describes the security technologies and techniques used for the iPhone OS and Mac OS X platforms.

The reference documentation for UIApplication and UIApplicationDelegate describe the remote-notification API for client applications.

RFC 5246 is the standard for the TLS protocol.

Secure communication between data providers and Apple Push Notification Service requires knowledge of Transport Layer Security (TLS) or its predecessor Secure Sockets Layer (SSL). Refer to one of the many online or printed descriptions of these cryptographic protocols for further information.

What Are Push Notifications?

An application on an iPhone or iPod touch is often only a part of a larger application based on the client-server model. The client side of the application is installed on the device; the server side of the application has the main function of providing data to its many client applications. (Hence it is termed a “provider.”) A client application occasionally connects with its provider and downloads the data that is waiting for it. Email and social-networking applications are examples of this client-server model.

But what if the application is not connected to its provider or even running on the device when the provider has new data for it to download? How does it learn about this waiting data? Push notifications are the solution to this dilemma. A push notification is a short message that a provider has delivered to a device; the device, in turn, informs the user of a client application that there is data to be downloaded. If the user enables this feature and the application is properly registered, the notification is delivered to the device and possibly the application. Apple Push Notification Service, described in “Apple Push Notification Service,” is the primary technology for the remote-notification feature.

Push Notifications from the User’s Perspective

Imagine yourself using an iPhone: making phone calls, surfing the Internet, listening to music. You have a chess application installed on your iPhone, and you decide to start a game with a friend who is playing remotely. You make the first move (which is duly noted by the game’s server application), and then quit the client application to read some email. In the meantime, your friend counters your move. The server for chess applications learns about this move and, seeing that the chess application on your device is no longer connected, sends a push notification to Apple Push Notification Service (APNs).

Your device—or more precisely, the iPhone OS running on the device—receives the notification from APNs. Because your chess application is not currently running, iPhone OS displays an alert similar to Figure 1-1. The message consists of the application name, a short message, and (in this case) two buttons: Close and View.

Figure 1-1 A push notification alert

If you tap the View button, the chess application launches, connects with its provider, downloads the new data, and adjusts the chessboard user interface to show your friend’s move. (Pressing Close simply dismisses the alert.)

Instead of displaying an alert message—or in addition to an alert message—iPhone OS could display a badge number in the upper-right corner of the icon of the target application, such as illustrated in Figure 1-2. The badge number often reflects the number of items that the server has waiting for the application, but could also mean other things. The badge number is specific to an application, and could indicate any number of things, such as the number of data items to download or the number of unread (but already downloaded) email messages.

Figure 1-2 Application icon with a badge number

Along with an alert message or badge number, iPhone OS might also play a short, distinctive sound to alert the user to the incoming notification.

A provider has much control over how users of its client applications are alerted. It decides which combination of alert message, alert sound, and badge number the device should display (although users have some control over this). It can specify a custom alert sound and increment, decrement, or even remove the badge number. If it specifies an alert message, it composes the message text and may even specify one button instead of two. In the latter case, the View button is suppressed, as illustrated in Figure 1-3.

Figure 1-3 Notification alert message with the View button suppressed

A provider may send a push notification to an iPhone application whether the application is running or not. If the application is running when the notification arrives, even if the device screen is locked, the application delegate may handle the notification directly. APNs retains the last notification it receives from a provider for an application on a device; so, if a device comes online and has not received the notification, APNs pushes the stored notification to it. A device receives push notifications over both Wi-Fi and cellular connections.

Important: WiFi is used for push notifications only if there is no cellular connection or if the device is an iPod touch. To receive notifications via Wi-Fi, the device’s display must be on (that is, it cannot be sleeping) or it must be plugged in.

Users of iPhone and iPod touch devices can control whether the device or specific applications installed on the device should receive push notifications. For applications they can also selectively enable or disable notification types (that is, icon badging, alert messages, and sounds). They set these restrictions in the Notifications preference of the Settings application. The UIKit framework provides a programming interface to detect this user preference for a given application.

Push Notifications from the Developer’s Perspective

Push notifications serve much the same purpose as a background application on a desktop system. For an iPhone application that is not currently running, the notification occurs indirectly, as a result of user intervention. The operating system receives a push notification on behalf of the application, and alerts the user through one or more of the methods described in “Push Notifications from the User’s Perspective.” Alerted, users may choose to launch the application, which then downloads the data from its provider. If an iPhone application is running when a notification comes in, it may handle the notification directly if it chooses to.

Note: On a desktop system, a background process is often the means whereby users are informed of downloadable data for an application that currently isn’t running. But on a device such as the iPhone, background applications are, for performance and security reasons, prohibited. Only one application may be executing at a time.

As its name suggests, Apple Push Notification Service (APNs) uses a “push” design to deliver notifications to devices. A push design differs from its opposite, a pull design, in that the intended recipient of the notification—iPhone OS in this case—passively listens for updates rather than actively polling for them. A push design makes possible a wide and timely dissemination of information with few of the scalability problems inherent with pull designs. APNs uses a persistent IP connection for implementing push notifications.

Most of a push notification consists of a payload: a property list containing APNs-defined properties specifying how the user is to be notified. For performance reasons, the payload is deliberately small. Although you may define custom properties for the payload, you should never use the remote-notification mechanism for data transport because delivery of push notifications is not guaranteed. For more on the payload, see “The Notification Payload.”

Adding the remote-notification feature to your application requires that you obtain the proper certificates from the iPhone Developer Program portal and then write the requisite code for the client and provider sides of the application. “Provisioning and Development” explains the provisioning and setup steps, and “Provider Communication with Apple Push Notification Service” and “iPhone OS Client Implementation” describe the details of implementation.

Apple Push Notification Service continually monitors providers for irregular behavior, looking for sudden spikes of activity, rapid connect-disconnect cycles, and similar activity. Apple seeks to notify providers when it detects this behavior, and if the behavior continues, it may put the provider’s certificate on a revocation list and refuse further connections. Any continued irregular or problematic behavior may result in the termination of a provider's access to APNs.

Apple Push Notification Service

Apple Push Notification Service (APNs for short) is the centerpiece of the push notifications feature. It is a robust and highly efficient service for propagating information to devices such as iPhone and iPod touch devices. Each device establishes an accredited and encrypted IP connection with the service and receives notifications over this persistent connection. If a notification for an application arrives when that application is not running, the device alerts the user that the application has data waiting for it.

Software developers (“providers”) originate the notifications in their server software. The provider connects with APNs through a persistent and secure channel while monitoring incoming data intended for their client applications. When new data for an application arrives, the provider prepares and sends a notification through the channel to APNs, which pushes the notification to the target device.

In addition to being a simple but efficient and high-capacity transport service, APNs includes a default quality-of-service component that provides store-and-forward capabilities. See “Quality of Service” for more information.

“Provider Communication with Apple Push Notification Service” and “iPhone OS Client Implementation” discuss the specific implementation requirements for providers and iPhone applications, respectively.

A Push Notification and Its Path

Apple Push Notification Service transports and routes a notification from a given provider to a given device. A notification is a short message consisting of two major pieces of data: the device token and the payload. The device token is analogous to a phone number; it contains information that enables APNs to locate the device on which the client application is installed. APNs also uses it to authenticate the routing of a notification. The payload is a JSON-defined property list that specifies how the user of an application on a device is to be alerted.

Note: For more information about the device token, see “Security Architecture”; for further information about the notification payload, see “The Notification Payload” .

The flow of remote-notification data is one-way. The provider composes a notification package that includes the device token for a client application and the payload. The provider sends the notification to APNs which in turn pushes the notification to the device.

When it authenticates itself to APNs, a provider furnishes the service with its topic, which identifies the application for which it’s providing data. The topic is currently the bundle identifier of the target application on an iPhone OS device.

Figure 2-1 A push notification from a provider to a client application

Figure 2-1 is a greatly simplified depiction of the virtual network APNs makes possible among providers and devices. The device-facing and provider-facing sides of APNs both have multiple points of connection; on the provider-facing side, these are called gateways. There are typically multiple providers, each making one or more persistent and secure connections with APNs through these gateways. And these providers are sending notifications through APNs to many devices on which their client applications are installed. Figure 2-2 is a slightly more realistic depiction.

Figure 2-2 Push notifications from multiple providers to multiple devices

Feedback Service

Sometimes APNs might attempt to deliver notifications for an application on a device, but the device may repeatedly refuse delivery because there is no target application. This often happens when the user has uninstalled the application. In these cases, APNs informs the provider through a feedback service that the provider connects with. The feedback service maintains a list of devices per application for which there were recent, repeated failed attempts to deliver notifications. The provider should obtain this list of devices and stop sending notifications to them. For more on this service, see “The Feedback Service.”

Quality of Service

Apple Push Notification Service includes a default Quality of Service (QoS) component that performs a store-and-forward function. If APNs attempts to deliver a notification but the device is offline, the QoS stores the notification. It retains only one notification per application on a device: the last notification received from a provider for that application. When the offline device later reconnects, the QoS forwards the stored notification to the device. The QoS retains a notification for a limited period before deleting it.

Security Architecture

To enable communication between a provider and a device, Apple Push Notification Service must expose certain entry points to them. But then to ensure security, it must also regulate access to these entry points. For this purpose, APNs requires two different levels of trust for providers, devices, and their communications. These are known as connection trust and token trust.

Connection trust establishes certainty that, on one side, the APNs connection is with an authorized provider with whom Apple has agreed to deliver notifications. At the device side of the connection, APNs must validate that the connection is with a legitimate device.

After APNs has established trust at the entry points, it must then ensure that it conveys notifications to legitimate end points only. To do this, it must validate the routing of messages traveling through the transport; only the device that is the intended target of a notification should receive it.

In APNs, assurance of accurate message routing—or token trust—is made possible through the device token. A device token is an opaque identifier of a device that APNs gives to the device when it first connects with it. The device shares the device token with its provider. Thereafter, this token accompanies each notification from the provider. It is the basis for establishing trust that the routing of a particular notification is legitimate. (In a metaphorical sense, it has the same function as a phone number, identifying the destination of a communication.)

Note: A device token is not the same thing as the device UDID returned by the uniqueIdentifier property of UIDevice.

The following sections discuss the requisite components for connection trust and token trust as well as the four procedures for establishing trust.

Service-to-Device Connection Trust

APNs establishes the identity of a connecting device through TLS peer-to-peer authentication. (Note that iPhone OS takes care of this stage of connection trust; you do not need to implement anything yourself.) In the course of this procedure, a device initiates a TLS connection with APNs, which returns its server certificate. The device validates this certificate and then sends its device certificate to APNs, which validates that certificate.

Provider-to-Service Connection Trust

Connection trust between a provider and APNs is also established through TLS peer-to-peer authentication. The procedure is similar to that described in “Service-to-Device Connection Trust.” The provider initiates a TLS connection, gets the server certificate from APNs, and validates that certificate. Then the provider sends its provider certificate to APNs, which validates it on its end. Once this procedure is complete, a secure TLS connection has been established; APNs is now satisfied that the connection has been made by a legitimate provider.

Note that provider connection is valid for delivery to only one specific application, identified by the topic (bundle ID) specified in the certificate. APNs also maintains a certificate revocation list; if a provider’s certificate is on this list, APNs may revoke provider trust (that is, refuse the connection).

Token Generation and Dispersal

An iPhone application must register to receive push notifications; it typically does this right after it is installed on a device. (This procedure is described in “iPhone OS Client Implementation.”) iPhone OS receives the registration request from an application, connects with APNs, and forwards the request. APNs generates a device token using information contained in the unique device certificate. The device token contains an identifier of the device. It then encrypts the device token with a token key and returns it to the device.

The device returns the device token to the requesting application as an NSData object. The application then must then deliver the device token to its provider in either binary or hexadecimal format. Figure 2-3 also illustrates the token generation and dispersal sequence, but in addition shows the role of the client application in furnishing its provider with the device token.

Figure 2-3 Sharing the device token

The form of this phase of token trust ensures that only APNs generates the token which it will later honor, and it can assure itself that a token handed to it by a device is the same token that it previously provisioned for that particular device—and only for that device.

Token Trust (Notification)

After iPhone OS obtains a device token from APNs, as described in “Token Generation and Dispersal,” it must provide APNs with the token every time it connects with it. APNs decrypts the device token and validates that the token was generated for the connecting device. To validate, APNs ensures that the device identifier contained in the token matches the device identifier in the device certificate.

Every notification that a provider sends to APNs for delivery to a device must be accompanied by the device token it obtained from a application on that device. APNs decrypts the token using the token key, thereby ensuring that the notification is valid. It then uses the device ID contained in the device token to determine the destination device for the notification.

Trust Components

To support the security model for APNs, providers and devices must possess certain certificates, certificate authority (CA) certificates, or tokens.

Provider: Each provider requires a unique provider certificate and private cryptographic key for validating their connection with APNs. This certificate, provisioned by Apple, must identify the particular topic published by the provider; the topic is the bundle ID of the client application. For each notification, the provider must furnish APNs with a device token identifying the target device. The provider may optionally wish to validate the service it is connecting to using the public server certificate provided by the APNs server.

Device: iPhone OS uses the public server certificate passed to it by APNs to authenticate the service that it has connected to. It has a unique private key and certificate that it uses to authenticate itself to the service and establish the TLS connection. It obtains the device certificate and key during device activation and stores them in the keychain. iPhone OS also holds its particular device token, which it receives during the service connection process. Each registered client application is responsible for delivering this token to its content provider.

APNs servers also have the necessary certificates, CA certificates, and cryptographic keys (private and public) for validating connections and the identities of providers and devices.

The Notification Payload

Each push notification carries with it a payload. The payload specifies how users are to be alerted to the data waiting to be downloaded to the client application. The maximum size allowed for a notification payload is 256 bytes; Apple Push Notification Service refuses any notification that exceeds this limit. Remember that delivery of notifications is “best effort” and is not guaranteed.

For each notification, providers must compose a JSON dictionary object that strictly adheres to RFC 4627. This dictionary must contain another dictionary identified by the key aps.

The aps dictionary contains one or more properties that specify the following actions:

An alert message to display to the user

A number to badge the application icon with

A sound to play

Note: Although you can combine an alert message, icon badging, and a sound in a single notification, you should consider the human-interface implications with push notifications.

For example, a user might find frequent alert messages with accompanying sound more annoying than useful, especially when the data to be downloaded is not critical.

If the target application isn’t running when the notification arrives, the alert message, sound, or badge value is played or shown. If the application is running, iPhone OS delivers it to the application delegate as an NSDictionary object. The dictionary contains the corresponding Cocoa property-list objects (plus NSNull).

Providers can specify custom payload values outside the Apple-reserved aps namespace. Custom values must use the JSON structured and primitive types: dictionary (object), array, string, number, and Boolean. You should not include customer information as custom payload data. Instead, use it for such purposes as setting context (for the user interface) or internal metrics. For example, a custom payload value might be a conversation identifier for use by an instant-message client application or a timestamp identifying when the provider sent the notification.

Important: Because delivery is not guaranteed, you should not depend on the remote-notifications facility for delivering critical data to an application via the payload. And never include sensitive data in the payload. You should use it only to notify the user that new data is available.

Table 2-1 lists the keys and expected values of the aps payload.

Table 2-1 Keys and values of the aps dictionary

Key

Value type

Comment