Combinations of Reception Methods
You can receive push notifications from APNs by preparing necessary methods for the push notification feature. The called methods and execution triggers of the methods vary depending on various elements including the initialization API, the content of the notification payload, the action taken by the end user, and the state of the mobile app.
The sections listed in the following table summarize events that occur when iOS receives a push notification. Those events include calls to handlers and user actions in Notification Center. The sections correspond to combinations of settings of the alert/body key, content-available key, and category key in the push message.
| alert/body | content- available |
category | See |
|---|---|---|---|
| Set | Set | Set | Details |
| Set | Set | Not set | Details |
| Set | Not set | Set | Details |
| Set | Not set | Not set | Details |
| Not set | Set | Set | Details |
| Not set | Set | Not set | Details |
| Not set | Not set | Set | Details |
| Not set | Not set | Not set | Details |
This topic is not based on Apple's documentation but on testing with real apps. The information in this topic might not be applicable for different versions of OS and/or under different conditions.
Terminology
This section describes terminology used in the table in each section.
Initialization API
The initialization API indicates the iOS API used for initializing the push notification feature. The iOS APIs are represented in the tables as follows:
API for iOS 10:
UNUserNotificationCenterclass for iOS 10API for iOS 8/9:
UIUserNotificationSettingsclass for iOS 8 and 9
Handler
The handlers listed in the tables execute the following iOS methods:
Launch handler: This handler involves the
application(_:didFinishLaunchingWithOptions:)method that is called when a mobile app starts. ThelaunchOptionsparameter of this method holdsUIApplicationLaunchOptionsRemoteNotificationKeywhen the method is called.Reception handler: This handler involves the
application(_:didReceiveRemoteNotification:fetchCompletionHandler:)method. For more information, see Reception Handler.Action handler: This handler involves the
userNotificationCenter(_:didReceive:withCompletionHandler:)method for iOS 10 or theapplication(_:handleActionWithIdentifier:forRemoteNotification:withResponseInfo:completionHandler:)method for iOS 8 and 9. Either of them is called depending on the API specified at initialization. For more information, see User Action Handler.
If a mobile app is not implemented with any of these methods, the call to that missing method will be just skipped. However, as described in the second table, an alternative method will be called in some cases.
State of a mobile app
The state of a mobile app is also mentioned alongside the reception handler and the action handler. The state is one of the following and obtained from the application.applicationState property.
Active: This value indicates that the state of the mobile app isUIApplicationStateActive. It means the mobile app received a push notification while it is running in the foreground.Inactive: This value indicates that the state of the mobile app isUIApplicationStateInactive. It means the mobile app indirectly received a push notification.Background: This value indicates that the state of the mobile app isUIApplicationStateBackground. It means the mobile app received a push notification while it is running in the background.
How to use this section
A push notification is processed differently depending on various elements and you might encounter unexpected defects. In order to avoid such defects, take relevant elements into consideration when you design your mobile app. The table in each section of this topic shows events that occur according to the push notification settings and the execution environment.
Addressing multiple calls to a handler
The reception handler can be called multiple times for a single push notification. If it is not acceptable to repeat a process, you need to design your mobile app accordingly.
Suppose you develop a mobile app whose initialization API is the UIUserNotificationSettings class. Now you design a process that receives a push notification that includes all of the alert/body, content-available, and category keys when your mobile app is running in the background. This condition corresponds to the second cell of the "Background" column of the table in the section for a case where alert/body: set, content-available: set, category: set.
In this case, the reception handler is called when a push notification arrives and when the user taps the notification body in Notification Center. The applicable table cell indicates that the state of a mobile app is UIApplicationStateBackground for the first call and UIApplicationStateInactive for the second call. To avoid repeating a process, use this state information to distinguish the calls.
Implementing actionable notifications
When you implement actionable notifications, you need to consider the possibility that the user does not tap an action button but a notification body in the design phase.
Suppose you develop a mobile app whose initialization API is the UNUserNotificationCenter class. Now you design a process that receives a push notification that does not include the content-available key but the alert/body and category keys when your mobile app is running in the background. This condition corresponds to the first cell of the "Background" column of the table in the section for a case where alert/body: set, content-available: not set, category: set.
In this case, the action handler is called when the user taps an action button or a notification body. The applicable table cell indicates that the state of a mobile app is UIApplicationStateBackground when an action button is tapped and UIApplicationStateInactive when a notification body is tapped. To implement an appropriate process for each user action, use this state information to distinguish the calls.
alert/body: set, content-available: set, category: set
| Initialization API | State of a mobile app | ||
|---|---|---|---|
| Foreground *1 | Background | Not running | |
| API for iOS 10 | The reception handler (Active) is immediately called. |
1. The reception handler (Background) is immediately called. *22. Notification Center displays a notification. 3. A tap calls either of the following handlers. - Action button: Action handler ( Background)- Notification body: Action handler ( Inactive) *3 |
1. Notification Center displays a notification. 2. A tap on an action button or a notification body calls the launch handler. 3. Either of the following handlers is called. - Action button: Action handler ( Background)- Notification body: Action handler ( Inactive) *3 |
API for iOS 8/9 | The reception handler (Active) is immediately called. |
1. The reception handler (Background) is immediately called. *22. Notification Center displays a notification. 3. A tap calls either of the following handlers. - Action button: Action handler ( Inactive)- Notification body: Reception handler ( Inactive) |
1. Notification Center displays a notification. 2. A tap on an action button or a notification body calls the launch handler. 3. Either of the following handlers is called. - Action button: Action handler ( Inactive)- Notification body: Reception handler ( Inactive) |
*1 A mobile app behaves differently when the app is in the foreground if you change the way to display notifications with the userNotificationCenter(_:willPresent:withCompletionHandler:) method.
*2 On iOS 8 or later, a mobile app running in the background receives push notifications whose payload contains the content-available key even if the "Background App Refresh" setting is off on the "Settings" screen of iOS.
*3 If the action handler is not implemented, the reception handler (Inactive) will be called instead.
alert/body: set, content-available: set, category: not set
| Initialization API | State of a mobile app | ||
|---|---|---|---|
| Foreground *1 | Background | Not running | |
| API for iOS 10 | The reception handler (Active) is immediately called. |
1. The reception handler (Background) is immediately called. *22. Notification Center displays a notification. 3. A tap on a notification body calls the action handler ( Inactive). *3 |
1. Notification Center displays a notification. 2. A tap on a notification body calls the launch handler. 3. The action handler ( Inactive) is called. *3 |
API for iOS 8/9 | The reception handler (Active) is immediately called. |
1. The reception handler (Background) is immediately called. *22. Notification Center displays a notification. 3. A tap on a notification body calls the reception handler ( Inactive). |
1. Notification Center displays a notification. 2. A tap on a notification body calls the launch handler. 3. The reception handler ( Inactive) is called. |
*1 A mobile app behaves differently when the app is in the foreground if you change the way to display notifications with the userNotificationCenter(_:willPresent:withCompletionHandler:) method.
*2 On iOS 8 or later, a mobile app running in the background receives push notifications whose payload contains the content-available key even if the "Background App Refresh" setting is off on the "Settings" screen of iOS.
*3 If the action handler is not implemented, the reception handler (Inactive) will be called instead.
alert/body: set, content-available: not set, category: set
| Initialization API | State of a mobile app | ||
|---|---|---|---|
| Foreground *1 | Background | Not running | |
| API for iOS 10 | The reception handler (Active) is immediately called. |
1. Notification Center displays a notification. 2. A tap calls either of the following handlers. - Action button: Action handler ( Background)- Notification body: Action handler ( Inactive) *2 |
1. Notification Center displays a notification. 2. A tap on an action button or a notification body calls the launch handler. 3. Either of the following handlers is called. - Action button: Action handler ( Background)- Notification body: Action handler ( Inactive) *2 |
API for iOS 8/9 | The reception handler (Active) is immediately called. |
1. Notification Center displays a notification. 2. A tap calls either of the following handlers. - Action button: Action handler ( Inactive)- Notification body: Reception handler ( Inactive) |
1. Notification Center displays a notification. 2. A tap on an action button or a notification body calls the launch handler. 3. Either of the following handlers is called. - Action button: Action handler ( Inactive)- Notification body: Reception handler ( Inactive) |
*1 A mobile app behaves differently when the app is in the foreground if you change the way to display notifications with the userNotificationCenter(_:willPresent:withCompletionHandler:) method.
*2 If the action handler is not implemented, the reception handler (Inactive) will be called instead.
alert/body: set, content-available: not set, category: not set
| Initialization API | State of a mobile app | ||
|---|---|---|---|
| Foreground *1 | Background | Not running | |
| API for iOS 10 | The reception handler (Active) is immediately called. |
1. Notification Center displays a notification. 2. A tap on a notification body calls the action handler ( Inactive). *2 |
1. Notification Center displays a notification. 2. A tap on a notification body calls the launch handler. 3. The action handler ( Inactive) is called. *2 |
API for iOS 8/9 | The reception handler (Active) is immediately called. |
1. Notification Center displays a notification. 2. A tap on a notification body calls the reception handler ( Inactive). |
1. Notification Center displays a notification. 2. A tap on a notification body calls the launch handler. 3. The reception handler ( Inactive) is called. |
*1 A mobile app behaves differently when the app is in the foreground if you change the way to display notifications with the userNotificationCenter(_:willPresent:withCompletionHandler:) method.
*2 If the action handler is not implemented, the reception handler (Inactive) will be called instead.
alert/body: not set, content-available: set, category: set
| Initialization API | State of a mobile app | ||
|---|---|---|---|
| Foreground *1 | Background | Not running | |
| API for iOS 10 | The reception handler (Active) is immediately called. |
The reception handler (Background) is immediately called. *2 |
The notification is ignored. | API for iOS 8/9 | The reception handler (Active) is immediately called. |
The reception handler (Background) is immediately called. *2 |
The notification is ignored. |
*1 A mobile app behaves differently when the app is in the foreground if you change the way to display notifications with the userNotificationCenter(_:willPresent:withCompletionHandler:) method.
*2 On iOS 8 or later, a mobile app running in the background receives push notifications whose payload contains the content-available key even if the "Background App Refresh" setting is off on the "Settings" screen of iOS.
alert/body: not set, content-available: set, category: not set
| Initialization API | State of a mobile app | ||
|---|---|---|---|
| Foreground *1 | Background | Not running | |
| API for iOS 10 | The reception handler (Active) is immediately called. |
The reception handler (Background) is immediately called. *2 |
The notification is ignored. | API for iOS 8/9 | The reception handler (Active) is immediately called. |
The reception handler (Background) is immediately called. *2 |
The notification is ignored. |
*1 A mobile app behaves differently when the app is in the foreground if you change the way to display notifications with the userNotificationCenter(_:willPresent:withCompletionHandler:) method.
*2 On iOS 8 or later, a mobile app running in the background receives push notifications whose payload contains the content-available key even if the "Background App Refresh" setting is off on the "Settings" screen of iOS.
alert/body: not set, content-available: not set, category: set
| Initialization API | State of a mobile app | ||
|---|---|---|---|
| Foreground *1 | Background | Not running | |
| API for iOS 10 | The reception handler (Active) is immediately called. *2 |
The notification is ignored. | The notification is ignored. | API for iOS 8/9 | The reception handler (Active) is immediately called. *2 |
The notification is ignored. | The notification is ignored. |
*1 A mobile app behaves differently when the app is in the foreground if you change the way to display notifications with the userNotificationCenter(_:willPresent:withCompletionHandler:) method.
*2 In order to call the reception handler, the sound key or the badge key must be set.
alert/body: not set, content-available: not set, category: not set
| Initialization API | State of a mobile app | ||
|---|---|---|---|
| Foreground *1 | Background | Not running | |
| API for iOS 10 | The reception handler (Active) is immediately called. *2 |
The notification is ignored. | The notification is ignored. | API for iOS 8/9 | The reception handler (Active) is immediately called. *2 |
The notification is ignored. | The notification is ignored. |
*1 A mobile app behaves differently when the app is in the foreground if you change the way to display notifications with the userNotificationCenter(_:willPresent:withCompletionHandler:) method.
*2 In order to call the reception handler, the sound key or the badge key must be set.