Customize the appearance of your iOS app’s notification alerts with a notification content app extension.
When an iOS device receives a notification containing an alert, the system displays the contents of the alert in two stages. Initially, it displays an abbreviated banner with the title, subtitle, and two to four lines of body text from the notification. If the user presses the abbreviated banner, iOS displays the full notification interface, including any notification-related actions. The system provides the interface for the abbreviated banner, but you can customize the full interface using a notification content app extension.
The notification content app extension manages a view controller that displays your custom notification interface. This view controller can supplement or replace the default system interface for your notifications. You can use your view controller to:
Customize the placement of items, including the alert's title, subtitle, and body text.
Substitute different fonts or styling for interface elements.
Display app-specific data—for example, data stored in app-specific keys of the notification's payload.
Include custom images or branding.
Your app extension must configure its view controller using the data immediately available, such as the contents of the notification and the files present in your app extension's bundle. If you use an app group to share data between your app and your app extension, you may also use any files found in the app group. To ensure your notifications are delivered in a timely manner, configure the views as quickly as possible. Don’t perform any long-running tasks, like trying to retrieve data over the network.
Add the Notification Content App Extension to Your Project
To add a notification content app extension to your iOS app:
Choose File > New > Target in Xcode.
Select Notification Content Extension from iOS Application Extension.
Provide a name for your app extension.
Add Views to Your View Controller
The template provided by Xcode includes a storyboard and a view controller for you to configure. Build your custom notification interface by adding views to your view controller. For example, use labels to display the title, subtitle, and body text of the notification. You can also add image views and views that display noninteractive content. You don't need to provide any initial content for your views.
You can add interactive controls (for example, buttons or switches) in iOS 12 and later. For more information, see Support Interactive Controls.
Configure Your View Controller
did method of your view controller to update its labels and other views. The notification payload contains the data to use when configuring your view controller. You can also use data from the other files of your app extension. Listing 1 shows a version of this method that retrieves the title and body text from the notification payload and assigns the strings to two
UILabel controls, which are stored as outlets on the view controller.
If a second notification arrives when your view controller is already visible, the system calls the
did method again with the new notification payload.
Declare the Supported Notification Types
Specify the types of notifications for which your notification content app extension provides an interface. When it receives a notification, the system matches the notification's category value—its type—with the declared categories of any notification content app extensions in your app. If it finds a match, the system loads the corresponding app extension.
Info file of your notification content app extension, configure the
UNNotification key with the category strings of the notifications that your extension supports. Category strings are identifiers contained in the
UNNotification objects that you register from your iOS app. You use these strings to differentiate the types of notifications that your app can receive. For example, you might include the string
MEETING in any notifications that indicate the arrival of a new meeting invitation. Identifier strings are case sensitive.
Figure 2 shows the
Info file of a notification content app extension that supports two different notification types. Because it supports two types, the value for the
UNNotification key consists of an array with the strings
PLANE. If a notification with either of those types arrives, the system displays the interface from this notification content app extension.
For a local notification, put its category string into the
category property of your
UNMutable object. For a remote notification, put the string into the
category key of your JSON payload. For information about declaring your app’s notification types, see Declaring Your Actionable Notification Types.
For more information about the keys in your
Info file, see
Hide the Default Notification Interface
The system displays some default information with every notification, including those for which you provide a custom interface. The system always displays a header that includes the app name and icon. The system also displays an interface with the title, subtitle, and body text of the notification, but you can hide this portion of the interface if you prefer.
For example, you might hide the default notification interface if your custom interface displays the same information. Figure 3 illustrates the layout of the notification interface with and without the default content.
To remove the default system content, add the
UNNotification key to your extension’s
Info file and set the value of the key to
true. For more information about this key, see
Incorporating Media Into Your Interface
To support the playback of audio or video from your custom notifications interface, implement the following:
In the view controller’s
mediaproperty, return the type of button you want.
Play Pause Button Type
In the view controller’s
mediaproperty, return the button’s frame.
Play Pause Button Frame
mediamethod, start playing your media file.
mediabutton, stop playing your media file.
To programmatically start or stop playback of your media file, call the current
media methods. Use your view controller’s
extension property to access the extension context.
Support Interactive Controls
In iOS 12 and later you can enable user interactions in your custom notifications. This lets you add interactive controls, such as buttons and switches to your custom interface.
To enable user interactions:
Open your Notification Content Extension’s
UNNotificationkey to your extension attributes. Give it a Boolean value, set to
Extension User Interaction Enabled
Figure 4 shows the
info file, with notifications enabled.