Topic Subscription în notificările push — ce este, cum funcționează și se configurează

Ce este Topic Subscription în FCM

Topic Subscription — este un mecanism de trimitere în grup a notificărilor push, prin care dispozitivele se abonează la canale denumite (subiecte) și primesc mesajele trimise pe aceste canale. Fiecare subiect este identificat printr-un nume de tip string, de exemplu news_sports sau weather_alerts.

Principiul de funcționare al subiectelor

Când un dispozitiv se abonează la un subiect, FCM adaugă Registration Token-ul său în lista de destinatari ai acelui subiect. La trimiterea unui mesaj către un subiect, FCM direcționează automat o copie către fiecare dispozitiv abonat. Firebase nu limitează numărul de abonamente pentru un dispozitiv — aplicația poate abona utilizatorul la zeci de subiecte simultan.

Subiecte versus trimitere individuală

Principalul avantaj al subiectelor este scalabilitatea. Pentru a trimite o notificare la un milion de utilizatori, este suficientă o singură cerere HTTP către FCM cu numele subiectului. La trimiterea individuală ar fi necesare un milion de cereri sau trimiterea în lot de până la 500 de tokeni odată. Subiectele simplifică, de asemenea, logica părții de server — nu este nevoie să stocați liste de tokeni pentru fiecare categorie.

Exemple de utilizare a subiectelor

Topic Subscription este utilizat pe scară largă în aplicațiile de știri pentru categorizarea conținutului — abonarea la subiectele "Sport", "Politică", "Tehnologii" permite livrarea notificărilor relevante. În e-commerce, subiectele sunt folosite pentru notificări despre reduceri în categorii specifice de produse. În mesagerie și rețelele sociale, subiectele sunt utilizate pentru notificări despre evenimente în grupuri.

Limitări și restricții FCM

Firebase impune limitări pentru lucrul cu subiectele. O aplicație poate avea până la 2000 de subiecte. Fiecare dispozitiv se poate abona la cel mult 2000 de subiecte. Frecvența abonărilor/dezabonărilor este, de asemenea, limitată — nu mai mult de 3000 de operații pe minut per proiect. Depășirea limitelor duce la blocarea temporară. Pentru proiectele cu un număr mare de subiecte, se recomandă utilizarea condiției (condition) în locul subiectului — FCM suportă expresii logice pentru targetare.

Cum funcționează abonamentul pe subiecte

Procesul Topic Subscription constă din trei etape: inițializarea abonamentului pe client, înregistrarea în infrastructura FCM și confirmarea operației. După abonarea cu succes, dispozitivul începe să primească mesajele trimise pe acel subiect.

Ciclul de viață al abonamentului

Când clientul apelează metoda subscribeToTopic(), Firebase SDK trimite o cerere către serverele FCM. Serverul verifică admisibilitatea operației și adaugă tokenul dispozitivului în lista abonaților subiectului. FCM returnează clientului confirmarea abonării reușite. Din acest moment, toate mesajele pe acest subiect vor fi livrate dispozitivului.

Crearea automată a subiectului

Subiectul nu trebuie creat în prealabil în consola Firebase. La prima abonare a oricărui dispozitiv la un subiect numit news_promo, FCM îl creează automat. Dacă ultimul dispozitiv se dezabonează, subiectul rămâne în sistem, dar inactiv, și își reia activitatea la o nouă abonare.

Abonamentul pe subiecte pe Android

Pe Android, abonarea și dezabonarea de la subiecte se realizează prin FirebaseMessaging SDK. Metodele subscribeToTopic() și unsubscribeFromTopic() primesc numele subiectului ca parametru. Operațiile sunt asincrone și necesită gestionarea rezultatului.

Abonarea de bază la un subiect

Pentru abonare, este suficient să apelați subscribeToTopic() cu numele subiectului vizat. Firebase SDK gestionează independent cererile de rețea și reîncercările în caz de eșec. Se recomandă abonarea la subiecte după primirea cu succes a 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", "Dezabonat: ${task.isSuccessful}")
            }
    }
}

Gestionarea abonamentelor multiple

În aplicațiile reale, utilizatorul se poate abona la mai multe categorii. Pentru o gestionare convenabilă, creați o clasă manager care sincronizează starea abonamentelor cu partea de server. La autentificarea utilizatorului, restaurați abonamentele sale din profil.

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

Abonamentul pe subiecte pe iOS

Pe iOS, procesul de abonare la subiecte este identic ca logică cu Android, dar utilizează Swift API Firebase Messaging. Metodele subscribe și unsubscribe sunt apelate pe instanța Messaging și sunt, de asemenea, asincrone.

Implementarea abonării pe iOS

Pentru a vă abona la un subiect într-o aplicație iOS, se utilizează metoda Messaging.subscribe(). Este important să apelați abonarea după inițializarea Firebase și primirea Registration Token. Apple recomandă solicitarea permisiunii pentru notificări înainte de abonarea la subiecte.

import FirebaseMessaging

class PushTopicManager {

    func subscribeToTopic(topic: String) {
        Messaging.messaging().subscribe(toTopic: topic) { error in
            if let error = error {
                Log.e("FCM", "Eroare de abonare: \(error)")
            } else {
                Log.d("FCM", "Abonat la \(topic)")
            }
        }
    }

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

Particularitățile abonamentelor pe iOS

Pe iOS, abonarea la un subiect este, de asemenea, legată de Registration Token pe care Firebase îl primește de la APNs. Dacă tokenul APNs se schimbă (de exemplu, după restaurarea dispozitivului), Firebase transferă automat abonamentele pe noul token. Cu toate acestea, în cazuri rare, poate fi necesară reabonarea după actualizarea Registration Token.

Gestionarea abonamentelor de pe server

Gestionarea de pe server a abonamentelor permite abonarea și dezabonarea dispozitivelor fără implicarea aplicației client. Acest lucru este util pentru administrare, testare A/B și gestionarea abonamentelor pe partea de backend.

FCM HTTP API pentru gestionarea abonamentelor

Firebase oferă un API REST pentru gestionarea în masă a abonamentelor. Metoda /v1/projects/{project_id}/subscriptions permite abonarea a până la 1000 de dispozitive într-o singură cerere. API-ul utilizează Registration Token-urile dispozitivelor pentru identificare.

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("Eroare de abonare", error)
    }
}

Scenarii de utilizare a gestionării de pe server

Gestionarea de pe server a abonamentelor este utilizată în mai multe scenarii. La înregistrarea utilizatorului, serverul îl abonează automat la subiectele de bază. La modificarea preferințelor în versiunea web, serverul sincronizează abonamentele pe dispozitivul mobil. Administratorii pot abona dispozitivele de test la subiecte interne pentru depanare. Pentru operații în masă, FCM oferă metoda Instance Group, permițând gestionarea abonamentelor unui grup de dispozitive printr-un singur identificator de grup.

Monitorizarea stării abonamentelor

Firebase nu oferă un API încorporat pentru verificarea abonamentelor curente ale unui dispozitiv. Dezvoltatorilor li se recomandă să mențină o bază de date proprie a abonamentelor pe partea de server. La fiecare pornire a aplicației, clientul își sincronizează abonamentele cu serverul, trimițând lista de subiecte active. Acest lucru permite detectarea desincronizării și restaurarea abonamentelor la nevoie. Pentru audit, utilizați logurile Firebase Cloud Functions — fiecare operație subscribe/unsubscribe poate fi înregistrată.