Abbonamento agli Argomenti nelle Notifiche Push — Cos'è, Come Funziona e Come Si Configura

Cos'è l'Abbonamento agli Argomenti in FCM

L'Abbonamento agli Argomenti è un meccanismo di consegna di gruppo di notifiche push in cui i dispositivi si abbonano a canali nominati (argomenti) e ricevono messaggi inviati a tali canali. Ogni argomento è identificato da un nome stringa, come news_sports o weather_alerts.

Principio di funzionamento degli argomenti

Quando un dispositivo si abbona a un argomento, FCM aggiunge il suo Registration Token all'elenco dei destinatari di quell'argomento. Quando si invia un messaggio all'argomento, FCM instrada automaticamente una copia a ogni dispositivo abbonato. Firebase non limita il numero di abbonamenti per dispositivo — un'app può abbonare un utente a dozzine di argomenti contemporaneamente.

Argomenti vs invio individuale

Il principale vantaggio degli argomenti è la scalabilità. Per inviare una notifica a un milione di utenti, è sufficiente una richiesta HTTP a FCM con il nome dell'argomento. Con l'invio individuale, sarebbero necessarie un milione di richieste o un invio batch di fino a 500 token alla volta. Gli argomenti semplificano anche la logica lato server — non è necessario memorizzare elenchi di token per ogni categoria.

Esempi di utilizzo degli argomenti

L'Abbonamento agli Argomenti è ampiamente utilizzato nelle app di notizie per la categorizzazione dei contenuti — abbonarsi agli argomenti “Sport”, “Politica”, “Tecnologia” consente di consegnare notifiche pertinenti. Nell'e-commerce, gli argomenti vengono utilizzati per notifiche sugli sconti in categorie di prodotti specifici. Nei messenger e nei social network, gli argomenti vengono utilizzati per notifiche sugli eventi nei gruppi.

Limitazioni e quote FCM

Firebase impone restrizioni sul lavoro con gli argomenti. Una singola app può avere fino a 2000 argomenti. Ogni dispositivo può abbonarsi a non più di 2000 argomenti. Anche la frequenza delle operazioni di abbonamento/disdetta è limitata — non più di 3000 operazioni al minuto per progetto. Il superamento di questi limiti comporta il blocco temporaneo. Per i progetti con un gran numero di argomenti, si consiglia di utilizzare condizioni invece di argomenti — FCM supporta espressioni logiche per il targeting.

Come funziona l'abbonamento agli argomenti

Il processo di Abbonamento agli Argomenti si compone di tre fasi: inizializzazione dell'abbonamento sul client, registrazione nell'infrastruttura FCM e conferma dell'operazione. Dopo l'abbonamento riuscito, il dispositivo inizia a ricevere i messaggi inviati a quell'argomento.

Ciclo di vita dell'abbonamento

Quando il client chiama il metodo subscribeToTopic(), l'SDK Firebase invia una richiesta ai server FCM. Il server verifica la validità dell'operazione e aggiunge il token del dispositivo all'elenco degli abbonati dell'argomento. FCM restituisce al client una conferma di abbonamento riuscito. Da questo momento, tutti i messaggi a questo argomento verranno consegnati al dispositivo.

Creazione automatica dell'argomento

Non è necessario creare un argomento in anticipo nella console Firebase. Quando il primo dispositivo si abbona a un argomento chiamato news_promo, FCM lo crea automaticamente. Se l'ultimo dispositivo si disabbona, l'argomento rimane nel sistema ma inattivo e riprende il funzionamento quando si verifica un nuovo abbonamento.

Abbonamento agli argomenti su Android

Su Android, l'abbonamento e la disdetta dagli argomenti avvengono tramite l'SDK FirebaseMessaging. I metodi subscribeToTopic() e unsubscribeFromTopic() accettano il nome dell'argomento come parametro. Le operazioni sono asincrone e richiedono la gestione del risultato.

Abbonamento base a un argomento

Per abbonarsi, basta chiamare subscribeToTopic() con il nome dell'argomento desiderato. L'SDK Firebase gestisce automaticamente le richieste di rete e i tentativi in caso di errore. Si consiglia di abbonarsi agli argomenti dopo aver ottenuto con successo un 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", "Disdetto: ${task.isSuccessful}")
            }
    }
}

Gestione di più abbonamenti

Nelle app reali, un utente può abbonarsi a diverse categorie. Per una gestione comoda, crea una classe manager che sincronizzi lo stato degli abbonamenti con il server. Quando un utente accede, ripristina i suoi abbonamenti dal profilo.

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")
    }
}

Abbonamento agli argomenti su iOS

Su iOS, il processo di abbonamento agli argomenti è identico a quello di Android nella logica, ma utilizza l'API Swift Firebase Messaging. I metodi subscribe e unsubscribe vengono chiamati sull'istanza di Messaging e sono anch'essi asincroni.

Implementazione dell'abbonamento su iOS

Per abbonarsi a un argomento in un'app iOS, utilizza il metodo Messaging.subscribe(). È importante chiamare l'abbonamento dopo l'inizializzazione di Firebase e l'ottenimento del Registration Token. Apple raccomanda di richiedere l'autorizzazione alle notifiche prima di abbonarsi agli argomenti.

import FirebaseMessaging

class PushTopicManager {

    func subscribeToTopic(topic: String) {
        Messaging.messaging().subscribe(toTopic: topic) { error in
            if let error = error {
                Log.e("FCM", "Errore di abbonamento: \(error)")
            } else {
                Log.d("FCM", "Abbonato a \(topic)")
            }
        }
    }

    func unsubscribeFromTopic(topic: String) {
        Messaging.messaging().unsubscribe(fromTopic: topic) { error in
            if let error = error {
                Log.e("FCM", "Errore di disdetta: \(error)")
            }
        }
    }
}

Particolarità degli abbonamenti iOS

Su iOS, l'abbonamento agli argomenti è anche legato al Registration Token che Firebase riceve da APNs. Se il token APNs cambia (ad esempio, dopo il ripristino del dispositivo), Firebase trasferisce automaticamente gli abbonamenti al nuovo token. Tuttavia, in rari casi, potrebbe essere necessario un re-abbonamento dopo un aggiornamento del Registration Token.

Gestione degli abbonamenti dal server

La gestione lato server degli abbonamenti consente di abbonare e disdire dispositivi senza coinvolgere l'app client. Ciò è utile per l'amministrazione, i test A/B e la gestione degli abbonamenti lato backend.

API HTTP FCM per la gestione degli abbonamenti

Firebase fornisce un'API REST per la gestione di massa degli abbonamenti. L'endpoint /v1/projects/{project_id}/subscriptions consente di abbonare fino a 1000 dispositivi in una singola richiesta. L'API utilizza i Registration Token dei dispositivi per l'identificazione.

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("Errore di abbonamento", error)
    }
}

Scenari di utilizzo della gestione lato server

La gestione lato server degli abbonamenti viene utilizzata in diversi scenari. Quando un utente si registra, il server lo abbona automaticamente agli argomenti di base. Quando le preferenze cambiano nella versione web, il server sincronizza gli abbonamenti sul dispositivo mobile. Gli amministratori possono abbonare dispositivi di test ad argomenti interni per il debug. Per le operazioni di massa, FCM fornisce il metodo Instance Group, che consente di gestire gli abbonamenti di un gruppo di dispositivi tramite un singolo identificatore di gruppo.

Monitoraggio dello stato degli abbonamenti

Firebase non fornisce un'API integrata per verificare gli abbonamenti correnti di un dispositivo. Si consiglia agli sviluppatori di mantenere un proprio database di abbonamenti lato server. A ogni avvio dell'app, il client sincronizza i propri abbonamenti con il server inviando l'elenco degli argomenti attivi. Ciò aiuta a identificare la desincronizzazione e ripristinare gli abbonamenti se necessario. Per l'audit, utilizza i log di Firebase Cloud Functions — ogni operazione di subscribe/unsubscribe può essere registrata.