Topic Subscription dalam notifikasi push — apa itu, cara kerja dan pengaturannya

Apa itu Topic Subscription di FCM

Topic Subscription — adalah mekanisme pengiriman notifikasi push grup, di mana perangkat berlangganan ke saluran bernama (topik) dan menerima pesan yang dikirim ke saluran tersebut. Setiap topik diidentifikasi dengan nama string, misalnya news_sports atau weather_alerts.

Prinsip kerja topik

Ketika perangkat berlangganan ke topik, FCM menambahkan Registration Token-nya ke daftar penerima topik tersebut. Saat mengirim pesan ke topik, FCM secara otomatis mengarahkan salinan ke setiap perangkat yang berlangganan. Firebase tidak membatasi jumlah langganan per perangkat — aplikasi dapat melanggankan pengguna ke puluhan topik sekaligus.

Topik vs pengiriman individual

Keuntungan utama topik adalah skalabilitas. Untuk mengirim notifikasi ke satu juta pengguna, cukup satu permintaan HTTP ke FCM dengan nama topik. Pada pengiriman individual, diperlukan satu juta permintaan atau pengiriman batch hingga 500 token sekaligus. Topik juga menyederhanakan logika sisi server — tidak perlu menyimpan daftar token untuk setiap kategori.

Contoh penggunaan topik

Topic Subscription banyak digunakan di aplikasi berita untuk kategorisasi konten — berlangganan topik "Olahraga", "Politik", "Teknologi" memungkinkan pengiriman notifikasi yang relevan. Di e-commerce, topik digunakan untuk notifikasi diskon di kategori produk tertentu. Di aplikasi pesan dan media sosial, topik digunakan untuk notifikasi tentang acara di grup.

Batasan dan limit FCM

Firebase memberlakukan batasan pada kerja dengan topik. Satu aplikasi dapat memiliki hingga 2000 topik. Setiap perangkat dapat berlangganan tidak lebih dari 2000 topik. Frekuensi langganan/berhenti berlangganan juga dibatasi — tidak lebih dari 3000 operasi per menit per proyek. Melebihi batas menyebabkan pemblokiran sementara. Untuk proyek dengan jumlah topik besar, disarankan menggunakan kondisi (condition) daripada topik — FCM mendukung ekspresi logika untuk penargetan.

Cara kerja langganan topik

Proses Topic Subscription terdiri dari tiga tahap: inisialisasi langganan di klien, pendaftaran di infrastruktur FCM, dan konfirmasi operasi. Setelah berhasil berlangganan, perangkat mulai menerima pesan yang dikirim ke topik tersebut.

Siklus hidup langganan

Ketika klien memanggil metode subscribeToTopic(), Firebase SDK mengirim permintaan ke server FCM. Server memeriksa kelayakan operasi dan menambahkan token perangkat ke daftar pelanggan topik. FCM mengembalikan konfirmasi keberhasilan langganan kepada klien. Mulai saat itu, semua pesan ke topik ini akan dikirim ke perangkat.

Pembuatan topik otomatis

Topik tidak perlu dibuat sebelumnya di konsol Firebase. Saat langganan pertama perangkat mana pun ke topik bernama news_promo, FCM secara otomatis membuatnya. Jika perangkat terakhir berhenti berlangganan, topik tetap ada di sistem tetapi tidak aktif, dan melanjutkan pekerjaannya saat ada langganan baru.

Langganan topik di Android

Di Android, berlangganan dan berhenti berlangganan topik dilakukan melalui FirebaseMessaging SDK. Metode subscribeToTopic() dan unsubscribeFromTopic() menerima nama topik sebagai parameter. Operasi bersifat asinkron dan memerlukan penanganan hasil.

Langganan dasar ke topik

Untuk berlangganan, cukup panggil subscribeToTopic() dengan nama topik yang dituju. Firebase SDK secara mandiri mengelola permintaan jaringan dan percobaan ulang saat kegagalan. Disarankan untuk berlangganan topik setelah berhasil menerima 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", "Berhenti berlangganan: ${task.isSuccessful}")
            }
    }
}

Mengelola beberapa langganan

Di aplikasi nyata, pengguna dapat berlangganan ke beberapa kategori. Untuk pengelolaan yang mudah, buat kelas manajer yang menyinkronkan status langganan dengan sisi server. Saat pengguna masuk, pulihkan langganan mereka dari profil.

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

Langganan topik di iOS

Di iOS, proses berlangganan topik secara logika identik dengan Android, tetapi menggunakan Swift API Firebase Messaging. Metode subscribe dan unsubscribe dipanggil pada instance Messaging dan juga bersifat asinkron.

Implementasi langganan di iOS

Untuk berlangganan topik di aplikasi iOS, gunakan metode Messaging.subscribe(). Penting untuk memanggil langganan setelah inisialisasi Firebase dan menerima Registration Token. Apple merekomendasikan meminta izin notifikasi sebelum berlangganan topik.

import FirebaseMessaging

class PushTopicManager {

    func subscribeToTopic(topic: String) {
        Messaging.messaging().subscribe(toTopic: topic) { error in
            if let error = error {
                Log.e("FCM", "Kesalahan langganan: \(error)")
            } else {
                Log.d("FCM", "Berlangganan ke \(topic)")
            }
        }
    }

    func unsubscribeFromTopic(topic: String) {
        Messaging.messaging().unsubscribe(fromTopic: topic) { error in
            if let error = error {
                Log.e("FCM", "Kesalahan berhenti berlangganan: \(error)")
            }
        }
    }
}

Karakteristik langganan iOS

Di iOS, langganan topik juga terikat ke Registration Token yang diterima Firebase dari APNs. Jika token APNs berubah (misalnya setelah pemulihan perangkat), Firebase secara otomatis memindahkan langganan ke token baru. Namun, dalam kasus yang jarang terjadi, mungkin diperlukan langganan ulang setelah pembaruan Registration Token.

Mengelola langganan dari server

Manajemen server langganan memungkinkan berlangganan dan berhenti berlangganan perangkat tanpa keterlibatan aplikasi klien. Ini berguna untuk administrasi, pengujian A/B, dan manajemen langganan di sisi backend.

FCM HTTP API untuk manajemen langganan

Firebase menyediakan REST API untuk manajemen langganan massal. Metode /v1/projects/{project_id}/subscriptions memungkinkan berlangganan hingga 1000 perangkat dalam satu permintaan. API menggunakan Registration Token perangkat untuk identifikasi.

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("Kesalahan langganan", error)
    }
}

Skenario penggunaan manajemen server

Manajemen server langganan digunakan dalam beberapa skenario. Saat pendaftaran pengguna, server secara otomatis melanggankannya ke topik dasar. Saat perubahan preferensi di versi web, server menyinkronkan langganan di perangkat seluler. Administrator dapat melanggankan perangkat uji ke topik internal untuk debugging. Untuk operasi massal, FCM menyediakan metode Instance Group, yang memungkinkan pengelolaan langganan grup perangkat melalui satu pengenal grup.

Pemantauan status langganan

Firebase tidak menyediakan API bawaan untuk memeriksa langganan saat ini dari suatu perangkat. Pengembang disarankan untuk menyimpan basis data langganan sendiri di sisi server. Setiap kali aplikasi dijalankan, klien menyinkronkan langganannya dengan server dengan mengirim daftar topik aktif. Ini memungkinkan deteksi ketidaksinkronan dan pemulihan langganan jika diperlukan. Untuk audit, gunakan log Firebase Cloud Functions — setiap operasi subscribe/unsubscribe dapat dicatat.