Assinatura de Tópico em Notificações Push — O Que É, Como Funciona e Como Configurar

O que é Assinatura de Tópico no FCM

A Assinatura de Tópico é um mecanismo de entrega em grupo de notificações push onde dispositivos se inscrevem em canais nomeados (tópicos) e recebem mensagens enviadas a esses canais. Cada tópico é identificado por um nome de string, como news_sports ou weather_alerts.

Como os tópicos funcionam

Quando um dispositivo se inscreve em um tópico, o FCM adiciona seu Registration Token à lista de destinatários desse tópico. Ao enviar uma mensagem para o tópico, o FCM roteia automaticamente uma cópia para cada dispositivo inscrito. O Firebase não limita o número de assinaturas por dispositivo — um aplicativo pode inscrever um usuário em dezenas de tópicos simultaneamente.

Tópicos vs envio individual

A principal vantagem dos tópicos é a escalabilidade. Para enviar uma notificação a um milhão de usuários, basta uma requisição HTTP ao FCM com o nome do tópico. Com o envio individual, seriam necessárias um milhão de requisições ou um envio em lote de até 500 tokens por vez. Os tópicos também simplificam a lógica do servidor — não é necessário armazenar listas de tokens para cada categoria.

Exemplos de uso de tópicos

A Assinatura de Tópico é amplamente utilizada em aplicativos de notícias para categorização de conteúdo — inscrever-se nos tópicos “Esportes”, “Política”, “Tecnologia” permite entregar notificações relevantes. No e-commerce, os tópicos são usados para notificações sobre descontos em categorias específicas de produtos. Em mensageiros e redes sociais, os tópicos são utilizados para notificações sobre eventos em grupos.

Limitações e cotas do FCM

O Firebase impõe restrições ao trabalhar com tópicos. Um único aplicativo pode ter até 2000 tópicos. Cada dispositivo pode se inscrever em no máximo 2000 tópicos. A frequência de operações de inscrição/cancelamento também é limitada — no máximo 3000 operações por minuto por projeto. Exceder esses limites resulta em bloqueio temporário. Para projetos com um grande número de tópicos, recomenda-se usar condições em vez de tópicos — o FCM suporta expressões lógicas para segmentação.

Como funciona a assinatura de tópicos

O processo de Assinatura de Tópico consiste em três etapas: inicialização da assinatura no cliente, registro na infraestrutura do FCM e confirmação da operação. Após a assinatura bem-sucedida, o dispositivo começa a receber mensagens enviadas para esse tópico.

Ciclo de vida da assinatura

Quando o cliente chama o método subscribeToTopic(), o SDK do Firebase envia uma requisição aos servidores do FCM. O servidor valida a operação e adiciona o token do dispositivo à lista de assinantes do tópico. O FCM retorna ao cliente uma confirmação de assinatura bem-sucedida. A partir desse momento, todas as mensagens para este tópico serão entregues ao dispositivo.

Criação automática de tópicos

Não é necessário criar um tópico previamente no console do Firebase. Quando o primeiro dispositivo se inscreve em um tópico chamado news_promo, o FCM o cria automaticamente. Se o último dispositivo cancelar a inscrição, o tópico permanece no sistema, mas inativo, e retoma o funcionamento quando uma nova inscrição ocorrer.

Assinatura de tópicos no Android

No Android, a inscrição e o cancelamento de tópicos são feitos através do SDK do FirebaseMessaging. Os métodos subscribeToTopic() e unsubscribeFromTopic() aceitam o nome do tópico como parâmetro. As operações são assíncronas e exigem tratamento do resultado.

Assinatura básica de tópico

Para se inscrever, basta chamar subscribeToTopic() com o nome do tópico desejado. O SDK do Firebase gerencia as requisições de rede e as tentativas automaticamente em caso de falha. Recomenda-se inscrever-se em tópicos após obter com sucesso um Registration Token.

class TopicSubscriber(private val context: Context) {

    fun subscribeToNewsTopic() {
        FirebaseMessaging.getInstance()
            .subscribeToTopic("news_latest")
            .addOnCompleteListener { task ->
                val msg = if (task.isSuccessful) {
                    "Subscribed to news topic"
                } else {
                    "Subscription failed"
                }
                Log.d("FCM", msg)
            }
    }

    fun unsubscribeFromNewsTopic() {
        FirebaseMessaging.getInstance()
            .unsubscribeFromTopic("news_latest")
            .addOnCompleteListener { task ->
                Log.d("FCM", "Cancelado: ${task.isSuccessful}")
            }
    }
}

Gerenciando múltiplas assinaturas

Em aplicativos reais, um usuário pode se inscrever em várias categorias. Para um gerenciamento conveniente, crie uma classe gerenciadora que sincronize o estado das assinaturas com o servidor. Quando um usuário fizer login, restaure suas assinaturas a partir do perfil.

class SubscriptionManager(private val context: Context) {

    private val fcm = FirebaseMessaging.getInstance()

    suspend fun syncSubscriptions(topics: List<String>) {
        topics.forEach { topic ->
            fcm.subscribeToTopic(topic).await()
        }
    }

    suspend fun removeAllSubscriptions() {
        val savedTopics = getSavedTopics()
        savedTopics.forEach { topic ->
            fcm.unsubscribeFromTopic(topic).await()
        }
    }

    private fun getSavedTopics(): List<String> {
        return listOf("news_latest", "promotions", "updates")
    }
}

Assinatura de tópicos no iOS

No iOS, o processo de assinatura de tópicos é idêntico ao do Android em lógica, mas usa a API Swift do Firebase Messaging. Os métodos subscribe e unsubscribe são chamados na instância do Messaging e também são assíncronos.

Implementando assinatura no iOS

Para se inscrever em um tópico em um aplicativo iOS, use o método Messaging.subscribe(). É importante chamar a assinatura após a inicialização do Firebase e a obtenção do Registration Token. A Apple recomenda solicitar permissão de notificações antes de se inscrever em tópicos.

import FirebaseMessaging

class PushTopicManager {

    func subscribeToTopic(topic: String) {
        Messaging.messaging().subscribe(toTopic: topic) { error in
            if let error = error {
                Log.e("FCM", "Erro de assinatura: \(error)")
            } else {
                Log.d("FCM", "Inscrito em \(topic)")
            }
        }
    }

    func unsubscribeFromTopic(topic: String) {
        Messaging.messaging().unsubscribe(fromTopic: topic) { error in
            if let error = error {
                Log.e("FCM", "Erro ao cancelar assinatura: \(error)")
            }
        }
    }
}

Particularidades das assinaturas no iOS

No iOS, a assinatura de tópicos também está vinculada ao Registration Token que o Firebase recebe do APNs. Se o token do APNs mudar (por exemplo, após a restauração do dispositivo), o Firebase transfere automaticamente as assinaturas para o novo token. No entanto, em casos raros, pode ser necessário reinscrever-se após uma atualização do Registration Token.

Gerenciamento de assinaturas pelo servidor

O gerenciamento pelo servidor de assinaturas permite inscrever e cancelar dispositivos sem envolver o aplicativo cliente. Isso é útil para administração, testes A/B e gerenciamento de assinaturas no backend.

API HTTP do FCM para gerenciamento de assinaturas

O Firebase fornece uma API REST para gerenciamento em massa de assinaturas. O endpoint /v1/projects/{project_id}/subscriptions permite inscrever até 1000 dispositivos em uma única requisição. A API usa os Registration Tokens dos dispositivos para identificação.

const admin = require("firebase-admin")

async function subscribeUsersToTopic(tokens, topic) {
    try {
        const response = await admin
            .messaging()
            .subscribeToTopic(tokens, topic)
        Log.info(`Success: ${response.successCount}`)
        Log.info(`Failures: ${response.failureCount}`)
    } catch (error) {
        Log.error("Erro de assinatura", error)
    }
}

Cenários de uso do gerenciamento pelo servidor

O gerenciamento de assinaturas pelo servidor é usado em vários cenários. Quando um usuário se registra, o servidor automaticamente o inscreve em tópicos básicos. Quando as preferências mudam na versão web, o servidor sincroniza as assinaturas no dispositivo móvel. Os administradores podem inscrever dispositivos de teste em tópicos internos para depuração. Para operações em massa, o FCM fornece o método Instance Group, que permite gerenciar assinaturas de um grupo de dispositivos através de um único identificador de grupo.

Monitoramento do estado das assinaturas

O Firebase não fornece uma API embutida para verificar as assinaturas atuais de um dispositivo. Recomenda-se que os desenvolvedores mantenham seu próprio banco de dados de assinaturas no servidor. A cada inicialização do aplicativo, o cliente sincroniza suas assinaturas com o servidor enviando a lista de tópicos ativos. Isso ajuda a identificar dessincronização e restaurar assinaturas se necessário. Para auditoria, use os logs do Firebase Cloud Functions — cada operação de subscribe/unsubscribe pode ser registrada.