Notification Category: o que é, quais categorias existem e como funcionam no iOS

O que é Notification Category no iOS?

Notification Category é um recurso do iOS (desde a versão 8.0) que permite aos desenvolvedores classificar notificações push e adicionar ações interativas a elas. Quando um usuário recebe uma notificação e pressiona com força (3D Touch) ou faz uma pressão longa, aparecem botões definidos pela categoria. Isso torna as notificações interativas e permite que os usuários ajam sem abrir o aplicativo.

Uma categoria é registrada através de um objeto UNNotificationCategory, que contém um identificador, uma matriz de ações e parâmetros de exibição opcionais. O sistema usa o identificador de categoria do payload APNS para encontrar a categoria registrada e exibir os botões correspondentes.

Ao contrário do Android Notification Channel, o iOS Category não gerencia importância, som ou vibração. Seu único propósito é fornecer capacidades interativas para as notificações: botões de resposta, confirmação, cancelamento ou entrada de texto.

As categorias são obrigatórias?

As categorias não são obrigatórias para exibir notificações push no iOS. A notificação aparecerá de qualquer forma — com botões se uma categoria estiver registrada, ou sem eles. As categorias são necessárias apenas para adicionar interatividade às notificações.

Como funcionam as categorias de notificação?

O mecanismo de categorias consiste em quatro etapas: registrar a categoria no cliente, enviar um payload APNS com a categoria, o sistema reconhecer a categoria e processar a ação do usuário.

• Registro — o aplicativo cria uma UNNotificationCategory com uma matriz de ações e a registra no UNUserNotificationCenter
• Envio — o servidor inclui a chave category no payload APNS com um valor que corresponde ao identificador da categoria
• Exibição — o iOS exibe a notificação e ao pressionar com força mostra os botões associados à categoria
• Processamento — o usuário toca em um botão, acionando UNUserNotificationCenterDelegate.didReceive response

As ações em uma categoria podem ser de dois tipos: foreground (abrem o aplicativo) e background (executam em segundo plano). Para ações em segundo plano, o aplicativo tem tempo limitado (cerca de 30 segundos) para processar em UNNotificationActionHandler.

Opções ao registrar uma categoria

UNNotificationCategory suporta várias opções através do parâmetro options: customDismissAction — receber um evento ao deslizar a notificação, allowInCarPlay — mostrar ações no CarPlay, hiddenPreviewsBodyPlaceholder — texto placeholder personalizado para visualizações ocultas.

UNNotificationAction: tipos de ações

O iOS fornece dois tipos de ações para categorias de notificação. Cada tipo tem seu próprio propósito e forma de interagir com o usuário.

UNTextInputAction é um recurso único do iOS. Quando o usuário toca no botão “Responder”, o sistema mostra um campo de texto onde o usuário digita sua resposta. O texto inserido é passado ao delegado junto com o identificador da ação. Isso permite implementar respostas rápidas sem abrir o aplicativo.

Opções de ação: options.authenticationRequired — requer desbloquear o dispositivo, options.destructive — destaca o botão em vermelho (para ações perigosas), options.foreground — abre o aplicativo após tocar.

Configurar uma categoria no código iOS

As categorias são registradas na inicialização do aplicativo, normalmente no método didFinishLaunchingWithOptions. O registro é feito através do UNUserNotificationCenter, após solicitar permissão de notificação. As categorias podem ser atualizadas a cada inicialização — versões antigas são substituídas por novas.

import UserNotifications

class AppDelegate: UIResponder, UIApplicationDelegate {

    func registerNotificationCategories() {
        let replyAction = UNTextInputNotificationAction(
            identifier: "reply",
            title: "Responder",
            options: [.foreground],
            textInputButtonTitle: "Enviar",
            textInputPlaceholder: "Digite uma mensagem..."
        )

        let deleteAction = UNNotificationAction(
            identifier: "delete",
            title: "Excluir",
            options: [.destructive]
        )

        let messageCategory = UNNotificationCategory(
            identifier: "message",
            actions: [replyAction, deleteAction],
            intentIdentifiers: [],
            options: [.customDismissAction]
        )

        UNUserNotificationCenter.current()
            .setNotificationCategories([messageCategory])
    }

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions options: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        UNUserNotificationCenter.current().delegate = self
        registerNotificationCategories()
        return true
    }
}

Após registrar a categoria, qualquer notificação com category = “message” no payload APNS mostrará os botões “Responder” e “Excluir”. O processamento de toques ocorre em userNotificationCenter:didReceive response, onde actionIdentifier determina qual botão foi pressionado.

Processamento de toque no delegado

Quando o usuário toca em um botão de categoria, o iOS chama o UNUserNotificationCenterDelegate com um objeto UNNotificationResponse. O response.actionIdentifier contém o identificador do botão tocado, e response.notification.request.content.userInfo contém os dados personalizados do payload.

Diferenças dos canais Android

Desenvolvedores familiarizados com Android Notification Channels muitas vezes os confundem com iOS Notification Categories. Apesar do nome semelhante, esses mecanismos resolvem tarefas diferentes e funcionam de forma distinta.

• Propósito — Android Channels gerenciam importância e visibilidade das notificações; iOS Categories gerenciam ações interativas
• Obrigatoriedade — Android Channel é obrigatório para exibir uma notificação; iOS Category é opcional
• Controle do usuário — usuários Android configuram canais nas configurações do sistema; categorias iOS não são visíveis diretamente para o usuário
• Agrupamento — Android Channels podem ser agrupados em ChannelGroups; iOS Categories não são agrupadas

Ambas as plataformas podem combinar ambos os mecanismos: no Android, uma notificação pode pertencer a um canal com ações do NotificationCompat, enquanto no iOS, uma categoria complementa os canais, que no iOS são chamados de thread-id e servem para agrupar notificações no centro de notificações.

Payload APNS com categoria

Para que uma notificação seja exibida com os botões da categoria, o servidor deve incluir a chave category no payload APNS. Sem esta chave, o sistema não saberá qual categoria aplicar à notificação.

{
    "aps": {
        "alert": {
            "title": "Nova mensagem",
            "body": "Ana: Olá! Como vai?"
        },
        "category": "message",
        "thread-id": "chat_123",
        "badge": 5,
        "sound": "default"
    }
}

A chave category deve corresponder exatamente ao identificador registrado através de setNotificationCategories no cliente. Maiúsculas e minúsculas importam — “message” e “Message” são consideradas categorias diferentes. Se a categoria não for encontrada, a notificação aparece sem botões, sem erros nos logs.

Processamento de categorias desconhecidas

Se o servidor enviar uma notificação com uma categoria que não está registrada no cliente, o iOS ignora a categoria e exibe a notificação sem botões. O erro não é registrado e o aplicativo não fica sabendo da incompatibilidade. Recomenda-se sincronizar a lista de categorias entre o servidor e o cliente.

Padrões de design de categorias

Ao projetar categorias de notificação no iOS, siga o princípio de uma categoria — um cenário. Cada categoria deve corresponder a um tipo específico de interação: responder a uma mensagem, confirmar uma ação ou recusar uma solicitação. Não misture cenários diferentes em uma mesma categoria.

Use UNTextInputAction para cenários onde o usuário precisa inserir texto sem abrir o aplicativo: respostas de mensagens, comentários, notas rápidas. Ações de texto aumentam o engajamento — o usuário realiza uma ação significativa em 2 toques em vez de 5+ dentro do aplicativo.

Para ações perigosas (excluir, bloquear), use a opção destructive. O iOS destacará esses botões em vermelho, alertando o usuário sobre a irreversibilidade da ação. Para ações que exigem desbloquear o dispositivo (visualizar dados pessoais), especifique authenticationRequired.

Teste as categorias em diferentes dispositivos: no iPhone com 3D Touch, no iPhone sem 3D Touch (long-press), no iPad e no Mac. O comportamento das categorias pode diferir ligeiramente entre as plataformas Apple. Atenção especial ao CarPlay: os botões de categoria aparecem na tela do carro e devem ser projetados com texto mínimo para a segurança do motorista.