Notification Content Extension — essência, UI personalizada e configuração no iOS

O que é Notification Content Extension

Notification Content Extension é uma extensão de aplicativo que substitui a exibição de notificações push no iOS. Em vez de um banner padrão com título, corpo da mensagem e botões, você pode mostrar uma interface totalmente projetada no Interface Builder ou programaticamente via UIKit ou SwiftUI.

Ao contrário da Notification Service Extension, que modifica o conteúdo antes da exibição, a Content Extension é responsável apenas pela apresentação visual. . A extensão recebe a notificação completa após todas as modificações e decide como exibi-la. Esta é a principal diferença entre os dois tipos de extensões de notificação.

A extensão é ativada quando o usuário realiza um gesto de expansão — rolar para baixo na notificação ou tocá-la (dependendo do modelo do dispositivo). O iOS inicia o processo da extensão, cria um controlador a partir do nib ou storyboard especificado e entrega a notificação através de UNNotificationContentExtension .

Criação de uma interface de notificação personalizada

O desenvolvimento começa adicionando um novo target no Xcode com o template Notification Content Extension. O Xcode cria um arquivo MainInterface.storyboard e uma classe herdando de UIViewController que implementa o protocolo UNNotificationContentExtension.

Tamanho e limitações da interface

A altura máxima da área personalizada é de 320 pontos no iPhone (para modelos com tela grande) e 352 pontos no iPad. O conteúdo que excede esses limites é cortado. Para se adaptar a diferentes tamanhos, recomenda-se usar Auto Layout e UIScrollView para conteúdo rolável. A largura sempre corresponde à largura da notificação e muda automaticamente ao girar o dispositivo.

As Diretrizes de Interface Humana da Apple alertam: a interface da notificação deve ser concisa e conter apenas um elemento principal — uma imagem, player, mapa ou formulário de entrada rápida. Múltiplos elementos interativos sobrecarregam o usuário e complicam a interação.

Comunicação com o aplicativo principal

App Group é o único mecanismo para compartilhar dados entre a extensão e o aplicativo principal. Através do diretório compartilhado do App Group, imagens em cache, tokens e configurações podem ser transferidos. Chamadas diretas à API do aplicativo principal ou acesso ao seu UserDefaults não estão disponíveis devido ao isolamento de processos.

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 é o protocolo principal que define o ciclo de vida de uma notificação personalizada. O protocolo fornece métodos para receber conteúdo, lidar com ações e gerenciar a interface.

Método didReceive:with:

didReceive(_:with:) é chamado quando uma notificação é recebida. A extensão recebe um objeto UNNotification e UNNotificationContentExtensionMediaPlayPauseButtonType para gerenciar o player de mídia. Neste método, você precisa configurar a interface — carregar uma imagem, inicializar o player ou exibir dados. O sistema chama este método toda vez que a notificação é atualizada em tempo real.

É importante notar que a extensão tem tempo limitado para executar — cerca de 30 segundos para um ciclo completo de exibição. Se a interface não for preparada dentro deste tempo, o iOS mostrará a notificação do sistema. Para recursos pesados — carregamento de imagens da rede, decodificação de vídeo — recomenda-se usar operações assíncronas com pré-cache via App Group.

Controle do player de mídia

O protocolo inclui métodos opcionais para botões de play/pause: mediaPlay, mediaPause, mediaPlayPauseButtonType. Se a notificação contiver conteúdo de áudio ou vídeo, a extensão pode exibir um player integrado com um elemento de controle do sistema. O iOS adiciona automaticamente um botão de reprodução no canto superior direito da extensão quando o tipo de botão apropriado é retornado.

Anexos de mídia e seu processamento

UNNotificationAttachment é um objeto que contém dados de mídia anexados a uma notificação. Imagens, arquivos de áudio e vídeo são adicionados no estágio de criação da notificação no servidor ou na Notification Service Extension através de UNNotificationAttachment.

Formatos suportados

Para imagens: JPEG, PNG, GIF, HEIF. Para áudio: MP3, AAC, ALAC, WAV. Para vídeo: MPEG-4, H.264, HEVC. Tamanho máximo de cada anexo é 50 MB, até 4 anexos por notificação. O sistema baixa automaticamente os anexos em segundo plano antes de exibir a notificação e fornece à extensão acesso às URLs locais através de recursos com escopo de segurança.

Segundo a Apple, a extensão não deve baixar mídia por si só — UNNotificationAttachment já contém uma URL local após o sistema concluir o download. No entanto, se o anexo não foi baixado a tempo (por exemplo, devido a uma conexão ruim), a extensão pode exibir um placeholder ou texto alternativo.

Trabalhando com recursos de escopo de segurança

Cada UNNotificationAttachment fornece uma URL com escopo de segurança que a extensão deve acessar via startAccessingSecurityScopedResource() e liberar via stopAccessingSecurityScopedResource(). Esses métodos devem ser chamados em pares — caso contrário, o recurso não será liberado e causará um vazamento de direitos de acesso.

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)

Notificações interativas e ações

Notification Content Extension suporta ações interativas personalizadas — botões exibidos abaixo do conteúdo da notificação. As ações são registradas ao criar a categoria de notificação via UNNotificationCategory e podem ser destrutivas, baseadas em texto ou em segundo plano.

Tipos de ação

UNNotificationAction é uma ação simples com um título e um sinalizador opcional de destrutividade. UNTextInputNotificationAction é uma ação com um campo de entrada de texto, por exemplo para respostas rápidas a mensagens. Ambos os tipos suportam a opção UNNotificationActionOptions.authenticationRequired — exigindo desbloqueio do dispositivo antes da execução.

A extensão recebe a ação selecionada através do método didReceive(_:withCompletionHandler:), que passa um objeto UNNotificationResponse com o identificador da ação e texto opcional. A extensão pode processar a resposta por si só ou passá-la ao aplicativo principal através do contêiner compartilhado do 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: []
)