Notification Content Extension — o que é e como criar uma interface personalizada para iOS

O que é Notification Content Extension

Notification Content Extension é uma extensão de app no iOS que substitui o modelo padrão de exibição de notificação push por uma UIView personalizada. Ao contrário de uma notificação comum, onde o conteúdo é limitado a título, subtítulo e corpo, a extensão permite exibir qualquer interface UIKit: um mapa com coordenadas, um gráfico, uma galeria de imagens ou um formulário de entrada.

Como funciona

Quando o iOS recebe uma notificação push com um categoryIdentifier especificado, o sistema verifica se há uma extensão registrada para essa categoria. Se sim — o sistema inicia a extensão em um processo separado e enga o conteúdo da notificação para ela. A extensão exibe sua interface em vez da padrão. O usuário interage com a interface personalizada sem abrir o aplicativo principal.

Diferença do Notification Service Extension

É importante não confundir Notification Content Extension com Notification Service Extension. O Service Extension processa o conteúdo antes da exibição da notificação (download de anexos, descriptografia). O Content Extension substitui a interface após receber o conteúdo pronto. Ambas as extensões podem trabalhar em conjunto: o Service Extension prepara os dados, o Content Extension os exibe.

Limitações da extensão

O Notification Content Extension opera em um processo isolado com recursos limitados. A extensão não tem acesso ao armazenamento principal do aplicativo via NSUserDefaults, exceto pelo App Group. O tamanho da extensão é limitado a 50 MB descompactado. O tempo para exibição do conteúdo também é limitado — se a extensão não concluir a atualização em um tempo razoável, o sistema a encerra.

Criando Notification Content Extension no Xcode

Para criar a extensão no Xcode, é necessário adicionar um novo target do tipo Notification Content Extension. O Xcode criará automaticamente o MainInterface.storyboard com um controlador que herda de UIViewController e implementa UNNotificationContentExtension.

Adicionando o target da extensão

No Xcode, selecione File → New → Target → Notification Content Extension. Informe o nome da extensão, a linguagem (Swift ou Objective-C) e certifique-se de que o projeto está conectado à mesma equipe de desenvolvimento. Após criar o target, aparecerá uma pasta com três arquivos: MainInterface.storyboard, Info.plist e o arquivo do controlador.

Configuração do Info.plist

No Info.plist da extensão, é obrigatório especificar o array NSExtensionAttributes com a chave UNNotificationExtensionCategory. Este array contém os identificadores das categorias de notificação para as quais a extensão será ativada. A chave opcional UNNotificationExtensionInitialContentSizeRatio define a proporção inicial da interface personalizada para o posicionamento correto.

Arquitetura de pastas da extensão

Recomenda-se manter uma arquitetura limpa no target da extensão: uma pasta separada para controladores, outra para Views personalizadas. Como a extensão é um binário separado, o código do aplicativo principal não está diretamente acessível. Para compartilhamento de código, crie um framework separado ou use App Group para dados.

Implementando o protocolo UNNotificationContentExtension

UNNotificationContentExtension é o protocolo que o controlador do Notification Content Extension deve implementar. O único método obrigatório é didReceive(_:with:), chamado ao receber uma notificação. O controlador recebe a notificação e o view controller pronto que precisa ser atualizado com os dados.

Implementação básica do controlador

O controlador da extensão deve herdar de UIViewController e implementar UNNotificationContentExtension. O Storyboard ou xib é vinculado a este controlador. Ao receber a notificação, o método didReceive envia o conteúdo, e o controlador atualiza suas 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)
    }
}

Controle do tamanho da interface

O sistema determina o tamanho da interface personalizada com base na chave UNNotificationExtensionInitialContentSizeRatio no Info.plist e no conteúdo atual. Recomenda-se definir esta chave como 0.1 para um tamanho inicial mínimo e, em seguida, alterar o tamanho através de preferredContentSize após o carregamento do conteúdo.

Personalização da interface e interatividade

Notification Content Extension oferece total liberdade na criação da interface. É possível usar qualquer componente UIKit: UITableView, MKMapView, WKWebView, UIStackView. No entanto, é importante considerar o espaço limitado da notificação e otimizar o desempenho.

Adicionando mapa à notificação

Um dos cenários populares é exibir um mapa com localização. Para isso, adiciona-se MKMapView ao Storyboard da extensão, e o controlador passa as coordenadas do conteúdo da notificação. Não se esqueça de adicionar MapKit ao target da extensão. Ao usar o mapa, considere o limite de memória da extensão — o carregamento de tiles complexos pode exceder os recursos disponíveis.

Animações e transições

Notification Content Extension suporta animações UIView, incluindo redimensionamento, movimentação e transparência de elementos. Ao entrar no modo estendido da notificação, é possível iniciar uma animação de aparecimento do conteúdo. As animações devem ser curtas (até 0.5 segundos) e não interferir na interação do usuário com a notificação. Evite animações infinitas — elas consomem bateria e reduzem o desempenho.

Manipulação de toques na interface personalizada

Como a extensão é um UIViewController completo, você pode adicionar gestos e manipuladores de toque. Gestos UIKit (UITapGestureRecognizer, UIButton) funcionam de forma padrão. Para ações que exigem a abertura do aplicativo, use o delegado da extensão ou o userNotificationCenter. Elementos interativos devem ser grandes o suficiente para toque confortável no espaço limitado — o tamanho mínimo do alvo de toque é de 44x44 pontos, conforme recomendações da Apple.

Trabalhando com mídia e anexos

Conteúdo de mídia é o recurso principal do Notification Content Extension. A notificação pode conter imagens, GIFs, áudio e vídeo que são exibidos na interface personalizada. Os anexos são entregues via UNNotificationAttachment, que pode ser adicionado pelo servidor através do payload ou pelo Notification Service Extension após o download. Os formatos suportados são JPEG, PNG, MPEG-4 e MP3.

Exibindo mídia na extensão

Para exibir uma imagem, basta obter o UNNotificationAttachment do conteúdo da notificação e carregá-lo a partir da URL local. É importante lembrar que a extensão tem acesso apenas a arquivos locais — recursos remotos devem ser baixados previamente pelo Service Extension. Tamanho máximo do anexo — 50 MB no iOS 15+, o limite muda com cada atualização subsequente. Para suportar várias imagens, use UNNotificationAttachment com identificadores diferentes e exiba-os através de UIPageViewController.

Carregamento e exibição de imagens

Para exibir uma imagem na interface personalizada, a extensão obtém o UNNotificationAttachment do conteúdo da notificação e o carrega a partir da URL local. O anexo deve ser baixado previamente pelo Notification Service Extension — o Content Extension não tem acesso à rede. Tamanho máximo do anexo de mídia — 50 MB no iOS 15+, em versões anteriores o limite era de 10 MB. A extensão deve tratar corretamente a ausência do anexo e exibir uma interface de fallback. Para pré-carregar imagens de baixa resolução, use versões em miniatura criadas pelo Service Extension antes da anexação.

Reprodução de vídeo na notificação

O iOS suporta reprodução de vídeo no Notification Content Extension via AVPlayerLayer. A extensão pode exibir um player de vídeo com botões de controle diretamente na notificação. Isso é especialmente útil para aplicativos de vigilância, streaming ou pré-visualização de conteúdo. Reprodução automática sem som é permitida desde que o usuário espere conteúdo de mídia nesta notificação. Ao implementar o player de vídeo, adicione elementos de controle: play/pause, barra de progresso e botão de fechar. Certifique-se de que o vídeo não inicie automaticamente com som — isso viola as recomendações da Apple para experiência do usuário. Para apresentações de slides com várias imagens, use transição animada entre elas via UIView.transition com a opção de transição de virada de página.

Otimização de desempenho da extensão

O Notification Content Extension opera em um ambiente limitado com cerca de 50 MB de memória. Para otimizar o desempenho, use carregamento preguiçoso de imagens, evite cálculos pesados na thread principal e aplique Auto Layout com constraints simples. Operações pesadas, como processamento de imagens ou análise de dados, execute em filas de fundo (DispatchQueue.global). Se o limite de memória for excedido, o sistema encerrará a extensão e o usuário verá a notificação padrão. Recomenda-se perfilar a extensão através do Instruments (Allocations e Time Profiler) antes da publicação, bem como verificar o consumo de memória em dispositivos reais com diferentes versões do iOS.