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: UNUserNotificationCenter class for iOS 10

  • API for iOS 8/9: UIUserNotificationSettings class 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. The launchOptions parameter of this method holds UIApplicationLaunchOptionsRemoteNotificationKey when 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 the application(_: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 is UIApplicationStateActive. 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 is UIApplicationStateInactive. It means the mobile app indirectly received a push notification.
  • Background: This value indicates that the state of the mobile app is UIApplicationStateBackground. 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. *2
2. 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. *2
2. 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. *2
2. 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. *2
2. 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.