Підписка на теми в push-сповіщеннях — що це, як працює та налаштовується

Що таке підписка на теми в FCM

Підписка на теми — це механізм групової розсилки push-сповіщень, при якому пристрої підписуються на іменовані канали (теми) та отримують повідомлення, надіслані на ці канали. Кожна тема ідентифікується рядком імені, наприклад news_sports або weather_alerts.

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

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

Теми проти індивідуального надсилання

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

Приклади використання тем

Підписка на теми широко застосовується в новинних додатках для категоризації контенту — підписка на теми «Спорт», «Політика», «Технології» дозволяє доставляти релевантні сповіщення. У e-commerce теми використовуються для сповіщень про знижки в конкретних категоріях товарів. У месенджерах і соціальних мережах теми застосовуються для оповіщень про події в групах.

Обмеження та ліміти FCM

Firebase накладає обмеження на роботу з темами. Один додаток може мати до 2000 тем. Кожен пристрій може підписатися не більше ніж на 2000 тем. Частота підписок/відписок також лімітована — не більше 3000 операцій на хвилину на проект. Перевищення лімітів призводить до тимчасового блокування. Для проектів з великою кількістю тем рекомендується використовувати умову (condition) замість теми — FCM підтримує логічні вирази для таргетингу.

Як працює підписка на теми

Процес підписки на теми складається з трьох етапів: ініціалізація підписки на клієнті, реєстрація в інфраструктурі 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 може бути залогована.