Notification Content Extension — what it is, how to create a custom interface for iOS

What is Notification Content Extension

Notification Content Extension is an app extension in iOS that overrides the standard push notification display template with a custom UIView. Unlike a regular notification where content is limited to a title, subtitle and body, the extension allows displaying any UIKit interface: a map with coordinates, a chart, an image gallery or an input form.

How It Works

When iOS receives a push notification with a specified categoryIdentifier, the system checks whether an extension is registered for this category. If so, the system launches the extension in a separate process and passes the notification content to it. The extension displays its interface instead of the standard one. The user interacts with the custom interface without opening the main application.

Difference from Notification Service Extension

It is important not to confuse Notification Content Extension with Notification Service Extension. The Service Extension processes content before the notification is shown (downloading attachments, decryption). The Content Extension replaces the interface after receiving the prepared content. Both extensions can work in tandem: the Service Extension prepares data, the Content Extension displays it.

Extension Limitations

Notification Content Extension runs in an isolated process with limited resources. The extension does not have access to the main application storage via NSUserDefaults, except through App Group. The extension size is limited to 50 MB uncompressed. The time to display content is also limited — if the extension does not complete the update within a reasonable time, the system collapses it.

Creating Notification Content Extension in Xcode

To create the extension in Xcode, you need to add a new target of type Notification Content Extension. Xcode will automatically create MainInterface.storyboard with a controller that inherits from UIViewController and implements UNNotificationContentExtension.

Adding the Extension Target

In Xcode, select File → New → Target → Notification Content Extension. Specify the extension name, language (Swift or Objective-C) and make sure the project is connected to the same development team. After creating the target, a folder will appear with three files: MainInterface.storyboard, Info.plist and the controller file.

Configuring Info.plist

The extension Info.plist must specify the NSExtensionAttributes array with the UNNotificationExtensionCategory key. This array contains the category identifiers of notifications for which the extension will activate. The optional key UNNotificationExtensionInitialContentSizeRatio sets the initial aspect ratio of the custom interface for correct positioning.

Extension Folder Architecture

It is recommended to maintain a clean architecture in the extension target: a separate folder for controllers, a separate one for custom Views. Since the extension is a separate binary, the main application code is not directly accessible. To share code, create a separate framework or use App Group for data.

Implementing the UNNotificationContentExtension Protocol

UNNotificationContentExtension is a protocol that must be implemented by the controller in Notification Content Extension. The only required method is didReceive(_:with:), called when a notification is received. The controller receives the notification and a ready view controller that needs to be updated with data.

Basic Controller Implementation

The extension controller must inherit from UIViewController and implement UNNotificationContentExtension. A Storyboard or xib is linked to this controller. When a notification is received, the didReceive method passes the content, and the controller updates its views.

import UIKit
import UserNotifications
import UserNotificationsUI

class CustomNotificationViewController: UIViewController {

    @IBOutlet var titleLabel: UILabel!
    @IBOutlet var customImageView: UIImageView!

    func didReceive(
        notification: UNNotification
    ) {
        let content = notification.request.content
        titleLabel.text = content.title
        loadAttachment(content.attachments.first)
    }

    private func loadAttachment(attachment: UNNotificationAttachment?) {
        guard let url = attachment?.URL else { return }
        if let image = UIImage(contentsOfFile: url.path) {
            customImageView.image = image
        }
    }
}

extension CustomNotificationViewController: UNNotificationContentExtension {
    func didReceive(
        notification: UNNotification
    ) {
        didReceive(notification: notification)
    }
}

Interface Size Management

The system determines the size of the custom interface based on the UNNotificationExtensionInitialContentSizeRatio key in Info.plist and the current content. It is recommended to set this key to 0.1 for the minimum initial size, and then change the size via preferredContentSize after loading the content.

UI Customization and Interactivity

Notification Content Extension provides complete freedom in creating the interface. You can use any UIKit components: UITableView, MKMapView, WKWebView, UIStackView. However, it is important to consider the limited notification space and optimize performance.

Adding a Map to the Notification

One popular scenario is displaying a map with a location. To do this, add MKMapView to the extension Storyboard, and the controller passes coordinates from the notification content. It is important not to forget to add MapKit to the extension target. When using a map, consider the extension memory limit — loading complex tiles may exceed available resources.

Animations and Transitions

Notification Content Extension supports UIView animations, including resizing, moving and transparency of elements. When entering the expanded notification mode, you can start a content appearance animation. Animations should be short (up to 0.5 seconds) and not interfere with the user interacting with the notification. Avoid infinite animations — they drain battery and reduce performance.

Handling Taps on the Custom Interface

Since the extension is a full UIViewController, you can add gestures and tap handlers. UIKit gestures (UITapGestureRecognizer, UIButton) work as standard. For actions requiring opening the application, use the extension delegate or userNotificationCenter. Interactive elements should be large enough for comfortable tapping in the limited space — the minimum touch target size is 44x44 points according to Apple recommendations.

Working with Media and Attachments

Media content is a key capability of Notification Content Extension. A notification can contain images, GIFs, audio and video, which are displayed in the custom interface. Attachments are delivered via UNNotificationAttachment, which can be added either by the server through the payload or by the Notification Service Extension after downloading. Supported formats include JPEG, PNG, MPEG-4 and MP3.

Displaying Media in the Extension

To display an image, simply get the UNNotificationAttachment from the notification content and load it from the local URL. It is important to remember that the extension only has access to local files — remote resources must be pre-downloaded by the Service Extension. Maximum attachment size is 50 MB on iOS 15+, with the limit increasing with each subsequent update. To support multiple images, use UNNotificationAttachment with different identifiers and display them via UIPageViewController.

Loading and Displaying Images

To display an image in the custom interface, the extension gets the UNNotificationAttachment from the notification content and loads it from the local URL. The attachment must be pre-downloaded by the Notification Service Extension — the Content Extension does not have network access. Maximum media attachment size is 50 MB on iOS 15+, in earlier versions the limit was 10 MB. The extension must correctly handle missing attachments and display a fallback interface. For pre-loading low-resolution images, use thumbnail versions created by the Service Extension before attaching.

Playing Video in the Notification

iOS supports video playback in Notification Content Extension via AVPlayerLayer. The extension can display a video player with control buttons directly in the notification. This is especially useful for video surveillance, streaming or content preview applications. Autoplay without sound is allowed provided the user expects media content in this notification. When implementing a video player, add controls: play/pause, progress bar and a close button. Make sure the video does not start automatically with sound — this violates Apple recommendations for user experience. For slideshows of multiple images, use animated transitions between them via UIView.transition with page curl transition option.

Extension Performance Optimization

Notification Content Extension runs in a constrained environment with a memory limit of about 50 MB. To optimize performance, use lazy image loading, avoid heavy computations on the main thread and apply Auto Layout with simple constraints. Heavy operations such as image processing or data parsing should be performed on background queues (DispatchQueue.global). If the memory limit is exceeded, the system will terminate the extension and the user will see a standard notification. It is recommended to profile the extension using Instruments (Allocations and Time Profiler) before publishing, and also check memory consumption on real devices with different iOS versions.