Topic Subscription в push известията — какво е, как работи и се настройва

Какво е Topic Subscription в FCM

Topic Subscription — е механизъм за групово изпращане на push известия, при който устройствата се абонират за именувани канали (теми) и получават съобщения, изпратени до тези канали. Всяка тема се идентифицира с низово име, например news_sports или weather_alerts.

Принцип на работа на темите

Когато устройство се абонира за тема, FCM добавя неговия Registration Token към списъка на получателите на тази тема. При изпращане на съобщение до тема, FCM автоматично насочва копие до всяко абонирано устройство. Firebase не ограничава броя на абонаментите на устройство — приложението може да абонира потребителя за десетки теми едновременно.

Теми срещу индивидуално изпращане

Основното предимство на темите е мащабируемостта. За да изпратите известие до милион потребители, е достатъчна една HTTP заявка към FCM с името на темата. При индивидуално изпращане биха били необходими милион заявки или пакетно изпращане до 500 токена наведнъж. Темите също опростяват логиката на сървърната част — няма нужда да съхранявате списъци с токени за всяка категория.

Примери за използване на теми

Topic Subscription се използва широко в новинарски приложения за категоризация на съдържание — абонамент за теми "Спорт", "Политика", "Технологии" позволява доставяне на подходящи известия. В електронната търговия темите се използват за известия за отстъпки в конкретни категории продукти. В месинджъри и социални мрежи темите се използват за известия за събития в групи.

Ограничения и лимити на FCM

Firebase налага ограничения за работа с теми. Едно приложение може да има до 2000 теми. Всяко устройство може да се абонира за не повече от 2000 теми. Честотата на абонаменти/отписвания също е ограничена — не повече от 3000 операции в минута на проект. Превишаването на лимитите води до временно блокиране. За проекти с голям брой теми се препоръчва използване на условие (condition) вместо тема — FCM поддържа логически изрази за таргетиране.

Как работи абонаментът за теми

Процесът Topic Subscription се състои от три етапа: инициализация на абонамента на клиента, регистрация в инфраструктурата на FCM и потвърждение на операцията. След успешен абонамент устройството започва да получава съобщения, изпратени до тази тема.

Жизнен цикъл на абонамента

Когато клиентът извика метода subscribeToTopic(), Firebase SDK изпраща заявка до сървърите на FCM. Сървърът проверява допустимостта на операцията и добавя токена на устройството към списъка на абонатите на темата. FCM връща на клиента потвърждение за успешен абонамент. От този момент всички съобщения до тази тема ще бъдат доставени на устройството.

Автоматично създаване на тема

Темата не е необходимо да се създава предварително в конзолата на Firebase. При първия абонамент на което и да е устройство за тема с име news_promo, FCM я създава автоматично. Ако последното устройство се отпише, темата остава в системата, но неактивна, и подновява работата си при нов абонамент.

Абонамент за теми на Android

На Android абонаментът и отписването от теми се извършва чрез FirebaseMessaging SDK. Методите subscribeToTopic() и unsubscribeFromTopic() приемат името на темата като параметър. Операциите са асинхронни и изискват обработка на резултата.

Основен абонамент за тема

За абонамент е достатъчно да извикате subscribeToTopic() с името на целевата тема. Firebase SDK самостоятелно управлява мрежовите заявки и повторните опити при грешки. Препоръчва се да се абонирате за теми след успешно получаване на 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", "Отписан: ${task.isSuccessful}")
            }
    }
}

Управление на множество абонаменти

В реални приложения потребителят може да се абонира за няколко категории. За удобно управление създайте клас-мениджър, който синхронизира състоянието на абонаментите със сървърната част. При влизане на потребителя възстановете неговите абонаменти от профила.

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

Абонамент за теми на iOS

На iOS процесът на абониране за теми е логически идентичен с Android, но използва Swift API на Firebase Messaging. Методите subscribe и unsubscribe се извикват на инстанцията Messaging и също са асинхронни.

Имплементация на абонамент на iOS

За абонамент за тема в iOS приложение се използва методът Messaging.subscribe(). Важно е да извикате абонамента след инициализация на Firebase и получаване на Registration Token. Apple препоръчва да поискате разрешение за известия преди абонамент за теми.

import FirebaseMessaging

class PushTopicManager {

    func subscribeToTopic(topic: String) {
        Messaging.messaging().subscribe(toTopic: topic) { error in
            if let error = error {
                Log.e("FCM", "Грешка при абонамент: \(error)")
            } else {
                Log.d("FCM", "Абониран за \(topic)")
            }
        }
    }

    func unsubscribeFromTopic(topic: String) {
        Messaging.messaging().unsubscribe(fromTopic: topic) { error in
            if let error = error {
                Log.e("FCM", "Грешка при отписване: \(error)")
            }
        }
    }
}

Особености на iOS абонаменти

На iOS абонаментът за тема също е обвързан с Registration Token, който Firebase получава от APNs. Ако APNs токенът се промени (например след възстановяване на устройството), Firebase автоматично прехвърля абонаментите към новия токен. В редки случаи обаче може да се наложи повторен абонамент след актуализация на Registration Token.

Управление на абонаменти от сървъра

Сървърно управление на абонаменти позволява абониране и отписване на устройства без участие на клиентското приложение. Това е полезно за администриране, A/B тестване и управление на абонаменти от страна на backend.

FCM HTTP API за управление на абонаменти

Firebase предоставя REST API за масово управление на абонаменти. Методът /v1/projects/{project_id}/subscriptions позволява абониране на до 1000 устройства в една заявка. API използва Registration Token на устройствата за идентификация.

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("Грешка при абонамент", error)
    }
}

Сценарии за използване на сървърно управление

Сървърното управление на абонаменти се използва в няколко сценария. При регистрация на потребител сървърът автоматично го абонира за основни теми. При промяна на предпочитанията в уеб версията сървърът синхронизира абонаментите на мобилното устройство. Администратори могат да абонират тестови устройства за вътрешни теми за отстраняване на грешки. За масови операции FCM предоставя метода Instance Group, който позволява управление на абонаменти на група устройства чрез един идентификатор на група.

Мониторинг на състоянието на абонаменти

Firebase не предоставя вграден API за проверка на текущите абонаменти на устройство. Препоръчва се на разработчиците да водят собствена база данни с абонаменти от сървърната страна. При всяко стартиране на приложението клиентът синхронизира своите абонаменти със сървъра, изпращайки списък с активни теми. Това позволява откриване на десинхронизация и възстановяване на абонаменти при необходимост. За одит използвайте логовете на Firebase Cloud Functions — всяка операция subscribe/unsubscribe може да бъде записана.