Notification Content Extension — esencia, interfaz personalizada y configuración en iOS

Qué es Notification Content Extension

Notification Content Extension es una extensión de aplicación que sobrescribe la visualización de las notificaciones push en iOS. En lugar de un banner estándar con un título, cuerpo del mensaje y botones, se puede mostrar una interfaz completamente diseñada en Interface Builder o mediante programación con UIKit o SwiftUI.

A diferencia de Notification Service Extension, que modifica el contenido antes de mostrarlo, Content Extension es responsable únicamente de la presentación visual. . La extensión recibe la notificación completa después de todas las modificaciones y decide cómo mostrarla. Esta es la diferencia clave entre los dos tipos de extensiones de notificación.

La extensión se activa cuando el usuario realiza un gesto de expansión — desplazarse hacia abajo en la notificación o tocarla (según el modelo del dispositivo). iOS inicia el proceso de la extensión, crea un controlador a partir del nib o storyboard especificado y entrega la notificación a través de UNNotificationContentExtension .

Creación de una interfaz de notificación personalizada

El desarrollo comienza añadiendo un nuevo target en Xcode con la plantilla Notification Content Extension. Xcode crea un archivo MainInterface.storyboard y una clase que hereda de UIViewController que implementa el protocolo UNNotificationContentExtension.

Tamaño y limitaciones de la interfaz

La altura máxima del área personalizada es de 320 puntos en iPhone (para modelos con pantalla grande) y 352 puntos en iPad. El contenido que supere estos límites se recorta. Para adaptarse a diferentes tamaños, se recomienda usar Auto Layout y UIScrollView para contenido desplazable. El ancho siempre coincide con el ancho de la notificación y cambia automáticamente al rotar el dispositivo.

Las Apple Human Interface Guidelines advierten: la interfaz de notificación debe ser concisa y contener solo un elemento principal — una imagen, reproductor, mapa o formulario de entrada rápida. Múltiples elementos interactivos abruman al usuario y complican la interacción.

Comunicación con la aplicación principal

App Group es el único mecanismo para compartir datos entre la extensión y la aplicación principal. A través del directorio compartido de App Group se pueden transferir imágenes en caché, tokens y configuraciones. Las llamadas directas a la API de la aplicación principal o el acceso a su UserDefaults no están disponibles debido al aislamiento de procesos.

class NotificationViewController: UIViewController {

    func didReceive(
        _ notification: UNNotification
    ) {
        guard let attachment = notification
            .request.content.attachments.first()
        else { return }
        if attachment.url.startAccessingSecurityScopedResource() {
            imageView.image = UIImage(contentsOfFile:
                attachment.url.path)
            attachment.url.stopAccessingSecurityScopedResource()
        }
    }
}

Protocolo UNNotificationContentExtension

UNNotificationContentExtension es el protocolo principal que define el ciclo de vida de una notificación personalizada. El protocolo proporciona métodos para recibir contenido, manejar acciones y gestionar la interfaz.

Método didReceive:with:

didReceive(_:with:) se llama cuando se recibe una notificación. La extensión recibe un objeto UNNotification y UNNotificationContentExtensionMediaPlayPauseButtonType para gestionar el reproductor multimedia. En este método, debes configurar la interfaz — cargar una imagen, inicializar el reproductor o mostrar datos. El sistema llama a este método cada vez que la notificación se actualiza en tiempo real.

Es importante tener en cuenta que la extensión tiene tiempo limitado para ejecutarse — aproximadamente 30 segundos para un ciclo completo de visualización. Si la interfaz no se prepara en este tiempo, iOS mostrará la notificación del sistema. Para recursos pesados — carga de imágenes desde la red, decodificación de video — se recomienda usar operaciones asíncronas con precarga a través de App Group.

Control del reproductor multimedia

El protocolo incluye métodos opcionales para botones de reproducción/pausa: mediaPlay, mediaPause, mediaPlayPauseButtonType. Si la notificación contiene contenido de audio o video, la extensión puede mostrar un reproductor integrado con un elemento de control del sistema. iOS añade automáticamente un botón de reproducción en la esquina superior derecha de la extensión cuando se devuelve el tipo de botón apropiado.

Archivos multimedia y su procesamiento

UNNotificationAttachment es un objeto que contiene datos multimedia adjuntos a una notificación. Las imágenes, archivos de audio y video se añaden en la etapa de creación de la notificación en el servidor o en Notification Service Extension a través de UNNotificationAttachment.

Formatos admitidos

Para imágenes: JPEG, PNG, GIF, HEIF. Para audio: MP3, AAC, ALAC, WAV. Para video: MPEG-4, H.264, HEVC. El tamaño máximo de cada archivo adjunto es de 50 MB, hasta 4 archivos por notificación. El sistema descarga automáticamente los archivos adjuntos en segundo plano antes de mostrar la notificación y proporciona a la extensión acceso a las URL locales a través de recursos con ámbito de seguridad.

Según Apple, la extensión no debe descargar medios por sí misma — UNNotificationAttachment ya contiene una URL local después de que el sistema complete la descarga. Sin embargo, si el archivo adjunto no se descargó a tiempo (por ejemplo, debido a una mala conexión), la extensión puede mostrar un marcador de posición o un texto alternativo.

Trabajo con recursos de ámbito de seguridad

Cada UNNotificationAttachment proporciona una URL con ámbito de seguridad a la que la extensión debe acceder mediante startAccessingSecurityScopedResource() y liberar mediante stopAccessingSecurityScopedResource(). Estos métodos deben llamarse en pares — de lo contrario, el recurso no se liberará y causará una fuga de derechos de acceso.

let attachment = notification.request.content.attachments.first()
guard attachment.url.startAccessingSecurityScopedResource()
else { return }
defer { attachment.url.stopAccessingSecurityScopedResource() }
let data = try Data(contentsOf: attachment.url)
imageView.image = UIImage(data: data)

Notificaciones interactivas y acciones

Notification Content Extension admite acciones interactivas personalizadas — botones que se muestran debajo del contenido de la notificación. Las acciones se registran al crear la categoría de notificación a través de UNNotificationCategory y pueden ser destructivas, de texto o de fondo.

Tipos de acciones

UNNotificationAction es una acción simple con un título y un indicador opcional de destructividad. UNTextInputNotificationAction es una acción con un campo de entrada de texto, por ejemplo para respuestas rápidas a mensajes. Ambos tipos admiten la opción UNNotificationActionOptions.authenticationRequired — que requiere desbloquear el dispositivo antes de la ejecución.

La extensión recibe la acción seleccionada a través del método didReceive(_:withCompletionHandler:), que pasa un objeto UNNotificationResponse con el identificador de la acción y texto opcional. La extensión puede procesar la respuesta por sí misma o pasarla a la aplicación principal a través del contenedor compartido de App Group.

let category = UNNotificationCategory(
    identifier: "message",
    actions: [
        UNTextInputNotificationAction(
            identifier: "reply",
            title: "Reply",
            options: .authenticationRequired
        ),
        UNNotificationAction(
            identifier: "mark_read",
            title: "Mark Read",
            options: .foreground
        )
    ],
    intentIdentifiers: []
)