Topic Subscription in Push Notifications — What It Is, How It Works and Configuration

What Is Topic Subscription in FCM

Topic Subscription is a group push notification delivery mechanism where devices subscribe to named channels (topics) and receive messages sent to those channels. Each topic is identified by a string name, such as news_sports or weather_alerts.

How Topics Work

When a device subscribes to a topic, FCM adds its Registration Token to the list of recipients for that topic. When a message is sent to the topic, FCM automatically routes a copy to every subscribed device. Firebase does not limit the number of subscriptions per device — an app can subscribe a user to dozens of topics simultaneously.

Topics vs Individual Sending

The main advantage of topics is scalability. To send a notification to a million users, only one HTTP request to FCM with the topic name is needed. With individual sending, it would require a million requests or batch sending of up to 500 tokens at a time. Topics also simplify server-side logic — there is no need to store token lists for each category.

Use Cases for Topics

Topic Subscription is widely used in news apps for content categorization — subscribing to “Sports”, “Politics”, “Technology” topics delivers relevant notifications. In e-commerce, topics are used for notifications about discounts in specific product categories. In messengers and social networks, topics are used for event notifications in groups.

FCM Limitations and Quotas

Firebase imposes restrictions on working with topics. A single app can have up to 2000 topics. Each device can subscribe to no more than 2000 topics. The frequency of subscribe/unsubscribe operations is also limited — no more than 3000 operations per minute per project. Exceeding these limits results in temporary blocking. For projects with a large number of topics, it is recommended to use conditions instead of topics — FCM supports logical expressions for targeting.

How Topic Subscription Works

The Topic Subscription process consists of three stages: initializing the subscription on the client, registering in the FCM infrastructure, and confirming the operation. After successful subscription, the device starts receiving messages sent to that topic.

Subscription Lifecycle

When the client calls the subscribeToTopic() method, the Firebase SDK sends a request to the FCM servers. The server validates the operation and adds the device token to the topic's subscriber list. FCM returns a confirmation to the client of successful subscription. From that point on, all messages to this topic will be delivered to the device.

Automatic Topic Creation

A topic does not need to be created in advance in the Firebase console. When the first device subscribes to a topic named news_promo, FCM automatically creates it. If the last device unsubscribes, the topic remains in the system but inactive, and resumes working when a new subscription occurs.

Topic Subscription on Android

On Android, subscribing and unsubscribing from topics is done via the FirebaseMessaging SDK. The methods subscribeToTopic() and unsubscribeFromTopic() accept the topic name as a parameter. Operations are asynchronous and require result handling.

Basic Topic Subscription

To subscribe, simply call subscribeToTopic() with the target topic name. The Firebase SDK handles network requests and retries automatically on failures. It is recommended to subscribe to topics after successfully obtaining 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", "Unsubscribed: ${task.isSuccessful}")
            }
    }
}

Managing Multiple Subscriptions

In real-world apps, a user may subscribe to several categories. For convenient management, create a manager class that synchronizes subscription state with the server side. When a user logs in, restore their subscriptions from their profile.

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

Topic Subscription on iOS

On iOS, the topic subscription process is identical to Android in logic but uses the Swift Firebase Messaging API. The subscribe and unsubscribe methods are called on the Messaging instance and are also asynchronous.

Implementing Subscription on iOS

To subscribe to a topic in an iOS app, use the Messaging.subscribe() method. It is important to call subscription after Firebase initialization and obtaining the Registration Token. Apple recommends requesting notification permission before subscribing to topics.

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 Subscription Specifics

On iOS, topic subscription is also tied to the Registration Token that Firebase receives from APNs. If the APNs token changes (e.g., after device restoration), Firebase automatically transfers subscriptions to the new token. However, in rare cases, re-subscription may be required after a Registration Token update.

Server-Side Subscription Management

Server-side management of subscriptions allows subscribing and unsubscribing devices without involving the client app. This is useful for administration, A/B testing, and managing subscriptions on the backend side.

FCM HTTP API for Subscription Management

Firebase provides a REST API for mass subscription management. The /v1/projects/{project_id}/subscriptions endpoint allows subscribing up to 1000 devices in a single request. The API uses device Registration Tokens for identification.

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

Server-Side Management Use Cases

Server-side subscription management is used in several scenarios. When a user registers, the server automatically subscribes them to basic topics. When preferences change in the web version, the server synchronizes subscriptions on the mobile device. Administrators can subscribe test devices to internal topics for debugging. For mass operations, FCM provides the Instance Group method, which allows managing subscriptions of a device group through a single group identifier.

Monitoring Subscription Status

Firebase does not provide a built-in API for checking a device's current subscriptions. Developers are advised to maintain their own subscription database on the server side. On each app launch, the client synchronizes its subscriptions with the server by sending the list of active topics. This helps identify desynchronization and restore subscriptions if necessary. For auditing, use Firebase Cloud Functions logs — each subscribe/unsubscribe operation can be logged.