Topic Subscription в пуш-уведомлениях — что это, как работает и настраивается

Что такое Topic Subscription в FCM

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

Принцип работы топиков

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

Топики против индивидуальной отправки

Основное преимущество топиков — масштабируемость. Чтобы отправить уведомление миллиону пользователей, достаточно одного HTTP-запроса к FCM с именем топика. При индивидуальной отправке потребовалось бы миллион запросов или batch-отправка до 500 токенов за раз. Топики также упрощают логику серверной части — не нужно хранить списки токенов для каждой категории.

Примеры использования топиков

Topic Subscription широко применяется в новостных приложениях для категоризации контента — подписка на топики «Спорт», «Политика», «Технологии» позволяет доставлять релевантные уведомления. В e-commerce топики используются для уведомлений о скидках в конкретных категориях товаров. В мессенджерах и социальных сетях топики применяются для оповещений о событиях в группах.

Ограничения и лимиты 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", "Unsubscribed: ${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", "Subscription error: \(error)")
            } else {
                Log.d("FCM", "Subscribed to \(topic)")
            }
        }
    }

    func unsubscribeFromTopic(topic: String) {
        Messaging.messaging().unsubscribe(fromTopic: topic) { error in
            if let error = error {
                Log.e("FCM", "Unsubscribe error: \(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("Subscribe error", error)
    }
}

Сценарии использования серверного управления

Серверное управление подписками применяется в нескольких сценариях. При регистрации пользователя сервер автоматически подписывает его на базовые топики. При изменении предпочтений в веб-версии сервер синхронизирует подписки на мобильном устройстве. Администраторы могут подписывать тестовые устройства на внутренние топики для отладки. Для массовых операций FCM предоставляет метод Instance Group, позволяющий управлять подписками группы устройств через единый идентификатор группы.

Мониторинг состояния подписок

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