How to Push and Handle Background Push Notifications in iOS ​

What are Background Notifications ​

A background notification is a remote notification that doesn’t display an alert, play a sound, or badge your app’s icon. It wakes your app in the background and gives it time to initiate downloads from your server and update its content.

Enable the Remote Notifications Background Modes in Your App ​

To receive background notifications, you must add the remote notificaitons background mode to you app.

Signing and Capability -> Background Modes -> Remote notifications

background-mode-remote-notifications

Configure the Payload and Request for Background Notifications ​

To Send a background notificaiton, create a remote notification with an aps dictionary that includes only the content-available key.

You may include custom keys in the payload, but the aps dictionary must not contain any keys what would trigger user interactions.

the notification’s POST request should contain the apns-push-type header filed with a value of background, and the apns-priority field with a value of 5.

json
{
   "aps" : {
      "content-available" : 1
   },
   "acme1" : "bar",
   "acme2" : 42
}

The System Does Not Guarantee Background Notifications Delivery ​

The system treats background notifications as low priority: you can use them to refresh your app’s content, but the system doesn’t guarantee their delivery.

  1. The system may throttle the delivery of background notifications if the total number becomes excessive. The number of background notifications allowed by the system depends on current conditions, but don’t try to send more than two or three per hour.

  2. When a device receives a background notification, the system may hold and delay the delivery of the notification, which can have the following side effects:

    • When the system receives a new background notification, it discards the older notification and only holds the newest one.
    • If something force quits or kills the app, the system discards the held notification.
    • If the user launches the app, the system immediately delivers the held notification.

  3. The system does not automatically launch your app if the user has force-quit it. In that situation, the user must relaunch your app or restart the device before the system attempts to launch your app automatically again.

How to Handle Background Notifications ​

If the system do decide to delivery a background notification, there will be these three scenarios:

If Your App Is Not Launched ​

The system launches your app (means your app delegate’s application(_:didFinishLaunchingWithOptions:) method will be called)in the background mode, and calls your app delegate’s application(_:didReceiveRemoteNotification:fetchCompletionHandler:) method.

Your app has 30 seconds to perform any tasks and call the provided completion handler.

If Your App Is In the Suspended State ​

The system wakes your app and puts it in the background mode, then calls your app delegate’s application(_:didReceiveRemoteNotification:fetchCompletionHandler:) method.

Your app has 30 seconds to perform any tasks and call the provided completion handler.

If Your App Is In the Foreground Mode ​

The system directly call your app delegate’s application(_:didReceiveRemoteNotification:fetchCompletionHandler:) method.

application(_:didReceiveRemoteNotification:fetchCompletionHandler:) example: ​

swift
func application(_ application: UIApplication, didReceiveRemoteNotificationuserInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler:@escaping (UIBackgroundFetchResult) -> Void) {
    if application.applicationState == .active {
        // do tasks
        completionHandler(.newData)
    } else if application.applicationState == .inactive {
        // do tasks
        completionHandler(.newData)
    } else if application.applicationState == .background {
        // do tasks
        completionHandler(.newData)
    } else {
        // do tasks
        completionHandler(.newData)
    }
}

The Alert Notification With "content-available" Field ​

If you push an alert notification with the content-available field with a value of “1”.

For example, you send the following payload and the POST request contains the apns-push-type header filed with a value of alert.

json
{
   "aps" : {
      "alert":"Hellow World!",
      "content-available" : 1
   },
   "acme1" : "bar",
   "acme2" : 42
}

Then, it is a normal alert notificaiton and will go through normal notificaiton process flow.

On top of that, because you have set content-available key and your app has add Remote notifications background mode, the system will also launch or wake your app if your app is not active and call application(_:didReceiveRemoteNotification:fetchCompletionHandler:) app delegate method like our previous section said.

Have any questions? Feel free to drop me a message on Twitter!

References ​