Protocol

UNNotificationContentExtension

An object that presents a custom interface for a delivered local or remote notification.

Overview

The UNNotificationContentExtension protocol provides the entry point for a Notification Content app extension, which displays a custom interface for your app’s notifications. You adopt this protocol in the custom UIViewController subclass that you use to present your interface. You create this type of extension to improve the way your notifications are presented, possibly by adding custom colors and branding or by incorporating media and other dynamic content into your notification interface.

To define a Notification Content app extension, add a Notification Content extension target to the Xcode project containing your app. The default Xcode template contains a source file and storyboard for your view controller. The Info.plist file of the extension comes mostly configured. Specifically, the NSExtensionPointIdentifier key is set to the value com.apple.usernotifications.content-extension and the NSExtensionMainStoryboard key is set to the name of the project’s storyboard file. However, the NSExtensionAttribute key contains a dictionary of additional keys and values, some of which you must configure manually:

  • UNNotificationExtensionCategory. (Required) The value of this key is a string or an array of strings. Each string contains the identifier of a category declared by the app using the UNNotificationCategory class.

  • UNNotificationExtensionInitialContentSizeRatio. (Required) The value of this key is a floating-point number that represents the initial size of your view controller’s view expressed as a ratio of its height to its width. The system uses this value to set the initial size of the view controller while your extension is loading. For example, a value of 0.5 results in a view controller whose height is half its width. You can change the size of your view controller after your extension loads.

  • UNNotificationExtensionDefaultContentHidden. (Optional) The value of this key is a Boolean. When set to true, the system displays only your custom view controller in the notification interface. When set to false, the system displays the default notification content in addition to your view controller’s content. Custom action buttons and the Dismiss button are always displayed, regardless of this setting. If you do not specify this key, the default value is set to false.

  • UNNotificationExtensionOverridesDefaultTitle. (Optional) The value of this key is a Boolean. When set to true, the system uses the title property of your view controller as the title of the notification. When set to false, the system sets the notification's title to the name of your app. If you do not specify this key, the default value is set to false.

You may include multiple Notification Content extensions in your app’s bundle. When a notification arrives, the system checks the UNNotificationExtensionCategory key of each extension’s Info.plist file and launches the extension that supports the notification’s category. At that time, the system loads your extension, instantiates and configures your view controller, and calls the view controller’s didReceive(_:) method. You must implement that method and use it to configure your notification interface. The method may be called multiple times if new notifications arrive while your view controller is visible.

If the notification category includes custom actions, the system automatically adds action buttons to your notification interface; do not create those buttons yourself. If your view controller implements the optional didReceive(_:completionHandler:) method, the system calls that method to respond to any selected actions. If your view controller does not implement that method, the system delivers the selected action to your app for handling.

The system prevents the delivery of touch events to your view controller while it is onscreen. Do not install gesture recognizers or rely on touch events in your interface.

For information about how to create and schedule local and remote notifications, see Local and Remote Notification Programming Guide.

Incorporating Media Into Your Interface

To support the playback of audio or video from your interface, implement the mediaPlayPauseButtonType property and return the type of button you want. You must also implement the mediaPlayPauseButtonFrame property and provide a frame rectangle for your button. The system draws the button for you and handles all user interactions with it, calling the mediaPlay() and mediaPause() methods of this protocol at appropriate times so that you can start and stop playback.

If you start or stop playback of your media file programmatically, call the mediaPlayingStarted() and mediaPlayingPaused() methods of the current NSExtensionContext object. The extensionContext property of your view controller object contains a reference to the extension context object.

Topics

Processing Notifications

func didReceive(UNNotification)

Called when a notification arrives for your app.

Required.

Handling Custom Actions

Supporting Media Playback

var mediaPlayPauseButtonFrame: CGRect

The frame rectangle to use for displaying a media playback button.

var mediaPlayPauseButtonTintColor: UIColor

The tint color for the media playback button.

func mediaPlay()

Called when the user initiates playback of your media content.

func mediaPause()

Called when the user pauses playback of your media content.

Constants

enum UNNotificationContentExtensionMediaPlayPauseButtonType

Constants indicating the type of media button to display.

enum UNNotificationContentExtensionResponseOption

Constants indicating the preferred response to a notification.

Relationships

Inherits From