Class

UNNotificationServiceExtension

An object that modifies the content of a remote notification before it is delivered to the user.

Overview

A UNNotificationServiceExtension object provides the entry point for a Notification Service app extension, which lets you customize the content of a remote notification before it is delivered to the user. A Notification Service app extension doesn't present any UI of its own. Instead, it is launched on demand when a notification of the appropriate type is delivered to the user’s device. You use this extension to modify the notification’s content or download content related to the extension. For example, you could use the extension to decrypt an encrypted data block or to download images associated with the notification.

You don't create UNNotificationServiceExtension objects yourself. Instead, the Xcode template for a Notification Service Extension target contains a subclass for you to modify. Use the methods of that subclass to implement your app extension’s behavior. When a remote notification for your app is received, the system loads your extension and calls its didReceive(_:withContentHandler:) method only when both of the following conditions are met:

  • The remote notification is configured to display an alert.

  • The remote notification’s aps dictionary includes the mutable-content key with the value set to 1.

The didReceive(_:withContentHandler:) method performs the main work of your extension. You use that method to make any changes to the notification’s content. That method has a limited amount of time to perform its task and execute the provided completion block. If your method does not finish in time, the system calls the serviceExtensionTimeWillExpire() method to give you one last chance to submit your changes. If you don't update the notification content before time expires, the system displays the original content.

As for any app extension, you deliver a Notification Service app extension class as a bundle inside your app. The template provided by Xcode configures the Info.plist file automatically for this app extension type. Specifically, it sets the value of the NSExtensionPointIdentifier key to com.apple.usernotifications.service and sets the value of the NSExtensionPrincipalClass key to the name of your UNNotificationServiceExtension subclass.

For information about how to set up and send remote notifications, see Setting Up a Remote Notification Server.

Subclassing Notes

The Xcode templates provide a subclass of UNNotificationServiceExtension for you to modify. You must implement the didReceive(_:withContentHandler:) method and use it to process incoming notifications. It is also strongly recommended that you override the serviceExtensionTimeWillExpire() method.

Topics

Processing Notifications

func didReceive(UNNotificationRequest, withContentHandler: (UNNotificationContent) -> Void)

Asks you to make any needed changes to the notification and notify the system when you're done.

func serviceExtensionTimeWillExpire()

Tells you that your extension is about to be terminated.

Relationships

Inherits From

Conforms To

See Also

Notification Service App Extension

Modifying Content in Newly Delivered Notifications

Modify the payload of a remote notification before it's displayed on the user’s iOS device.