Handling Push Notifications on iOS
This section describes the following topics:
Implementing the App Delegate
The main app delegate for your app is responsible for registering the device with APNS. It does this with the UIApplication class's
registerForRemoteNotificationTypes method. You can use this method to specify what types of notifications to allow for this app.
The following example uses synchronous methods to register the device to receive push notifications:
Default behavior of push notifications
iOS defines the default behavior of the app when it receives push notifications. Based on which properties of the notification are set, iOS performs certain actions.
The following table describes what action, if any, iOS performs:
|Push Request Property||Notification Type||iOS Action|
If the value of this property is set:
If the user interacts with the Alert, iOS opens the app and invokes the
If this property points to a sound file in the app's bundle:
If the value of this property is "default", then iOS plays the device's default sound.
If the value of this property is set:
If the value of this property is set to a number, iOS updates the badge to that number. If the value of this property is set to "incremental", iOS adds one to the current badge number.
If this property is set to
This functionality is available on devices that run iOS 7 and later, and only in apps where
If more than one of these properties is set, then the device performs more than one action. If none of these properties is set, then iOS does nothing.
Handling the push notifications
When a push notification is received by an app, the app executes one of the following push handler methods:
didReceiveRemoteNotification– Receives an NSDictionary containing the push notification's payload. This method is called only when the app is in the foreground, and only if
didReceiveRemoteNotification:fetchCompletionHandleris not defined.
didReceiveRemoteNotification:fetchCompletionHandler– Receives an NSDictionary containing the push notification's payload and the fetch completion handler. This method is called whether the app is in the foreground or the background, and is used only if
remote-notificationsbackground mode is enabled for the app. This method is called if it is defined, regardless of whether
iOS attaches a
userInfo object to each of these methods. This object stores the payload of the push notification in the following objects:
aps– Contains the APNS-specified properties of the push notification, including the values of the
custom– Contains additional data that was set on the push notification as the
For a description of these properties, see Properties of a Push Request.
Accessing push notification properties
You can access the properties of the
userInfo object in the
The following example displays a message that contains the value of the
To access the properties of a push notification when the notification type is Alert, and the app was in the background, and the user clicked on the Alert, use the
didFinishLaunchingWithOptions method. In this case, iOS passes the payload of the push notification as the
launchOptions object (as an NSDictionary object).
Triggering a background task with Content Available
A push notification can trigger a background task on devices that meet the following criteria:
- Target device is running iOS 7 or later
content-availableproperty of the push notification is set to
- The app's
remote-notificationbackground mode is enabled
When the app receives a notification in an environment where these criteria are met, the app calls the
didReceiveRemoteNotification:fetchCompletionHandler method. The app has 30 seconds to perform an action.
The action triggered by such a notification must be completed within 30 seconds. If the action begins a download or tries to perform some other action that takes longer than expected, iOS suspends the application. When suspended, an app does not execute code but does stay in memory. An app can resume operation when a new push notification is received.
Updating the badge count
If you make a change to the badge count in the client app, such as when a message is read, you should update the current value of the badge count on the Akula server. By doing this, you can ensure that Akula will send the correct value the next time a push notification includes a change to the badge count.
You update the server with the new badge value with the
updateBadgeCount (synchronous) or
updateBadgeCountWithDelegate (asynchronous) methods.
The following example sets the current badge number to 42 in the Akula Server push service: