Subskrypcja tematów w powiadomieniach push — co to jest, jak działa i jak ją skonfigurować

Czym jest Topic Subscription w FCM

Topic Subscription — to mechanizm grupowej wysyłki powiadomień push, w którym urządzenia subskrybują nazwane kanały (tematy) i otrzymują wiadomości wysłane na te kanały. Każdy temat jest identyfikowany przez nazwę, na przykład news_sports lub weather_alerts.

Zasada działania tematów

Kiedy urządzenie subskrybuje temat, FCM dodaje jego Registration Token do listy odbiorców tego tematu. Przy wysyłaniu wiadomości na temat FCM automatycznie kieruje kopię do każdego subskrybującego urządzenia. Firebase nie ogranicza liczby subskrypcji na jedno urządzenie — aplikacja może subskrybować użytkownika na dziesiątki tematów jednocześnie.

Tematy a wysyłka indywidualna

Główną zaletą tematów jest skalowalność. Aby wysłać powiadomienie do miliona użytkowników, wystarczy jedno żądanie HTTP do FCM z nazwą tematu. Przy wysyłce indywidualnej potrzeba by miliona żądań lub wysyłki wsadowej do 500 tokenów na raz. Tematy upraszczają również logikę serwerową — nie trzeba przechowywać list tokenów dla każdej kategorii.

Przykłady użycia tematów

Topic Subscription jest szeroko stosowany w aplikacjach informacyjnych do kategoryzacji treści — subskrypcja tematów "Sport", "Polityka", "Technologie" pozwala dostarczać odpowiednie powiadomienia. W e-commerce tematy są używane do powiadomień o zniżkach w konkretnych kategoriach produktów. W komunikatorach i sieciach społecznościowych tematy są wykorzystywane do powiadomień o wydarzeniach w grupach.

Ograniczenia i limity FCM

Firebase nakłada ograniczenia na pracę z tematami. Jedna aplikacja może mieć do 2000 tematów. Każde urządzenie może subskrybować nie więcej niż 2000 tematów. Częstotliwość subskrypcji/anulowania subskrypcji jest również limitowana — nie więcej niż 3000 operacji na minutę na projekt. Przekroczenie limitów prowadzi do tymczasowej blokady. Dla projektów z dużą liczbą tematów zaleca się używanie warunku (condition) zamiast tematu — FCM obsługuje wyrażenia logiczne do targetowania.

Jak działa subskrypcja tematów

Proces Topic Subscription składa się z trzech etapów: inicjalizacja subskrypcji na kliencie, rejestracja w infrastrukturze FCM i potwierdzenie operacji. Po pomyślnej subskrypcji urządzenie zaczyna otrzymywać wiadomości wysłane na dany temat.

Cykl życia subskrypcji

Gdy klient wywołuje metodę subscribeToTopic(), Firebase SDK wysyła żądanie do serwerów FCM. Serwer sprawdza dopuszczalność operacji i dodaje token urządzenia do listy subskrybentów tematu. FCM zwraca klientowi potwierdzenie pomyślnej subskrypcji. Od tego momentu wszystkie wiadomości na dany temat będą dostarczane do urządzenia.

Automatyczne tworzenie tematu

Temat nie wymaga wcześniejszego tworzenia w konsoli Firebase. Przy pierwszej subskrypcji dowolnego urządzenia na temat o nazwie news_promo FCM automatycznie go tworzy. Jeśli ostatnie urządzenie anuluje subskrypcję, temat pozostaje w systemie, ale nieaktywny, i wznawia działanie przy nowej subskrypcji.

Subskrypcja tematów na Androidzie

Na Androidzie subskrypcja i anulowanie subskrypcji tematów odbywa się przez FirebaseMessaging SDK. Metody subscribeToTopic() i unsubscribeFromTopic() przyjmują nazwę tematu jako parametr. Operacje są asynchroniczne i wymagają obsługi wyniku.

Podstawowa subskrypcja tematu

Aby subskrybować, wystarczy wywołać subscribeToTopic() z nazwą docelowego tematu. Firebase SDK samodzielnie zarządza żądaniami sieciowymi i ponownymi próbami w przypadku awarii. Zaleca się subskrybowanie tematów po pomyślnym otrzymaniu 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", "Anulowano subskrypcję: ${task.isSuccessful}")
            }
    }
}

Zarządzanie wieloma subskrypcjami

W rzeczywistych aplikacjach użytkownik może subskrybować wiele kategorii. Dla wygodnego zarządzania utwórz klasę-menadżer, która synchronizuje stan subskrypcji z częścią serwerową. Przy logowaniu użytkownika przywracaj jego subskrypcje z profilu.

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

Subskrypcja tematów na iOS

Na iOS proces subskrypcji tematów jest identyczny logiką jak na Androidzie, ale używa Swift API Firebase Messaging. Metody subscribe i unsubscribe są wywoływane na instancji Messaging i również są asynchroniczne.

Implementacja subskrypcji na iOS

Aby subskrybować temat w aplikacji iOS, używa się metody Messaging.subscribe(). Ważne jest, aby wywołać subskrypcję po inicjalizacji Firebase i otrzymaniu Registration Token. Apple zaleca proszenie o zgodę na powiadomienia przed subskrypcją tematów.

import FirebaseMessaging

class PushTopicManager {

    func subscribeToTopic(topic: String) {
        Messaging.messaging().subscribe(toTopic: topic) { error in
            if let error = error {
                Log.e("FCM", "Błąd subskrypcji: \(error)")
            } else {
                Log.d("FCM", "Zasubskrybowano \(topic)")
            }
        }
    }

    func unsubscribeFromTopic(topic: String) {
        Messaging.messaging().unsubscribe(fromTopic: topic) { error in
            if let error = error {
                Log.e("FCM", "Błąd anulowania subskrypcji: \(error)")
            }
        }
    }
}

Specyfika subskrypcji na iOS

Na iOS subskrypcja tematu również jest powiązana z Registration Token, który Firebase otrzymuje od APNs. Jeśli token APNs się zmieni (na przykład po przywróceniu urządzenia), Firebase automatycznie przenosi subskrypcje na nowy token. Jednak w rzadkich przypadkach może być wymagana ponowna subskrypcja po aktualizacji Registration Token.

Zarządzanie subskrypcjami z serwera

Zarządzanie serwerowe subskrypcjami pozwala subskrybować i anulować subskrypcje urządzeń bez udziału aplikacji klienckiej. Jest to przydatne do administrowania, testów A/B i zarządzania subskrypcjami po stronie backendu.

FCM HTTP API do zarządzania subskrypcjami

Firebase udostępnia REST API do masowego zarządzania subskrypcjami. Metoda /v1/projects/{project_id}/subscriptions pozwala subskrybować do 1000 urządzeń w jednym żądaniu. API używa Registration Token urządzeń do identyfikacji.

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("Błąd subskrypcji", error)
    }
}

Scenariusze użycia zarządzania serwerowego

Zarządzanie serwerowe subskrypcjami jest stosowane w kilku scenariuszach. Przy rejestracji użytkownika serwer automatycznie subskrybuje go do podstawowych tematów. Przy zmianie preferencji w wersji webowej serwer synchronizuje subskrypcje na urządzeniu mobilnym. Administratorzy mogą subskrybować urządzenia testowe do wewnętrznych tematów w celu debugowania. Dla operacji masowych FCM udostępnia metodę Instance Group, pozwalającą zarządzać subskrypcjami grupy urządzeń przez jeden identyfikator grupy.

Monitorowanie stanu subskrypcji

Firebase nie udostępnia wbudowanego API do sprawdzania bieżących subskrypcji urządzenia. Deweloperom zaleca się prowadzenie własnej bazy subskrypcji po stronie serwerowej. Przy każdym uruchomieniu aplikacji klient synchronizuje swoje subskrypcje z serwerem, wysyłając listę aktywnych tematów. Pozwala to wykryć desynchronizację i przywrócić subskrypcje w razie potrzeby. Do audytu używaj logów Firebase Cloud Functions — każda operacja subscribe/unsubscribe może być logowana.