Tentang pesan FCM

Firebase Cloud Messaging (FCM) menawarkan berbagai opsi dan kemampuan pesan. Informasi di halaman ini dimaksudkan untuk membantu Anda memahami berbagai jenis pesan FCM, serta hal-hal yang dapat Anda lakukan dengan jenis pesan tersebut.

Jenis pesan

Dengan FCM, Anda dapat mengirim dua jenis pesan ke klien:

• Pesan notifikasi, terkadang dianggap sebagai "pesan tampilan". Pesan ini ditangani oleh FCM SDK secara otomatis.
• Pesan data, yang ditangani oleh aplikasi klien.

Pesan notifikasi memiliki serangkaian kunci bawaan yang terlihat oleh pengguna. Sebaliknya, pesan data hanya memuat key-value pair kustom yang ditentukan pengguna. Pesan notifikasi bisa berisi payload data opsional. Payload maksimum untuk kedua jenis pesan tersebut adalah 4.096 byte, kecuali jika mengirim pesan dari Firebase console, yang memberlakukan batas 1.000 karakter.

	Skenario penggunaan	Cara mengirim
Pesan notifikasi	FCM SDK menampilkan pesan ke perangkat pengguna akhir atas nama aplikasi klien saat aplikasi tersebut berjalan di latar belakang. Atau, jika aplikasi berjalan di latar depan saat notifikasi diterima, kode aplikasi akan menentukan perilakunya. Pesan notifikasi memiliki serangkaian kunci bawaan yang terlihat oleh pengguna dan payload data opsional untuk key-value pair kustom.	Dalam lingkungan tepercaya, seperti Cloud Functions atau server aplikasi Anda, gunakan Admin SDK atau HTTP v1 API. Tetapkan kunci notification. Dapat memiliki payload data opsional. Selalu dapat diciutkan. Lihat beberapa contoh notifikasi tampilan dan payload permintaan kirim. Gunakan Notifications composer: Isi Message Text, Title, dan lain-lain, lalu kirim. Tambahkan payload data opsional dengan memberikan Custom data.
Pesan data	Aplikasi klien bertanggung jawab memproses pesan data. Pesan data hanya memiliki key-value pair kustom tanpa nama kunci yang dicadangkan (lihat di bawah).	Dalam lingkungan tepercaya, seperti Cloud Functions atau server aplikasi Anda, gunakan Admin SDK atau Protokol Server FCM. Dalam permintaan kirim, Tetapkan kunci data.

Gunakan pesan notifikasi jika Anda ingin FCM SDK menangani tampilan notifikasi secara otomatis saat aplikasi berjalan di latar belakang. Gunakan pesan data jika Anda ingin memproses pesan dengan kode aplikasi klien Anda sendiri.

FCM dapat mengirim pesan notifikasi yang mencakup payload data opsional. Dalam kasus semacam ini, FCM menangani penampilan payload notifikasi, sedangkan aplikasi klien menangani payload data.

Pesan notifikasi

Untuk pengujian atau pemasaran dan re-engagement pengguna, Anda dapat mengirim pesan notifikasi menggunakan Firebase console. Firebase console menyediakan pengujian A/B berbasis analisis untuk membantu Anda meningkatkan kualitas pesan pemasaran.

Untuk mengirim pesan notifikasi secara terprogram menggunakan Admin SDK atau protokol FCM, tetapkan kunci notification dengan serangkaian opsi key-value bawaan yang diperlukan untuk bagian pesan notifikasi yang terlihat oleh pengguna. Misalnya, berikut adalah pesan notifikasi berformat JSON dalam suatu aplikasi IM. Pengguna akan menerima pesan berjudul "Portugal vs. Denmark" dan teks "great match!" di perangkat:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    }
  }
}

Pesan notifikasi dikirimkan ke area notifikasi saat aplikasi berjalan di latar belakang. Untuk aplikasi yang berjalan di latar depan, pesan ditangani oleh fungsi callback.

Baca dokumentasi referensi objek notifikasi Protokol HTTP v1 untuk mengetahui daftar lengkap kunci bawaan yang tersedia untuk mem-build pesan notifikasi.

Pesan data

Tetapkan kunci yang sesuai dengan key-value pair kustom Anda untuk mengirim payload data ke aplikasi klien.

Pastikan Anda tidak menggunakan kata yang dicadangkan dalam key-value pair kustom Anda. Kata-kata yang dicadangkan tersebut meliputi "from", "notification", "message_type", atau kata apa pun yang diawali dengan "google" atau "gcm".

Misalnya, berikut adalah pesan berformat JSON dalam aplikasi IM yang sama seperti di atas. Di sini informasi dienkapsulasi dalam kunci data umum dan aplikasi klien diharapkan untuk menafsirkan kontennya:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    }
  }
}

Contoh di atas menunjukkan penggunaan kolom data umum atau tingkat atas, yang ditafsirkan oleh klien di semua platform yang menerima pesan tersebut. Di setiap platform, aplikasi klien menerima payload data dalam fungsi callback.

Enkripsi untuk pesan data

Android Transport Layer (lihat arsitektur FCM) menggunakan enkripsi titik ke titik. Bergantung pada kebutuhan, Anda dapat memutuskan untuk menambahkan enkripsi end-to-end ke pesan data. FCM tidak menyediakan solusi menyeluruh. Namun, ada solusi eksternal yang tersedia, seperti Capillary atau DTLS.

Pesan notifikasi dengan payload data opsional

Baik secara terprogram maupun melalui Firebase console, Anda dapat mengirim pesan notifikasi yang berisi payload opsional key-value pair kustom. Di Notifications composer, gunakan kolom Custom data di Advanced options.

Perilaku aplikasi saat menerima pesan yang memuat payload data dan notifikasi bergantung pada apakah aplikasi itu berjalan di latar belakang atau latar depan; intinya, aktif atau tidaknya aplikasi pada saat menerima pesan.

• Saat berjalan di latar belakang, aplikasi menerima payload notifikasi di area notifikasi, dan hanya menangani payload data saat pengguna mengetuk notifikasi.
• Saat berjalan di latar depan, aplikasi Anda menerima objek pesan dengan kedua payload yang tersedia.

Berikut adalah pesan berformat JSON yang memuat kunci notification dan juga kunci data:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    },
    "data" : {
      "Nick" : "Mario",
      "Room" : "PortugalVSDenmark"
    }
  }
}

Menyesuaikan pesan di seluruh platform

Melalui Firebase Admin SDK dan protokol HTTP FCM v1, permintaan pesan Anda dapat menetapkan semua kolom yang tersedia di objek message. Hal ini mencakup:

• sekumpulan kolom umum untuk ditafsirkan oleh semua instance aplikasi yang menerima pesan tersebut.
• kumpulan kolom khusus platform, seperti AndroidConfig dan WebpushConfig, yang hanya ditafsirkan oleh instance aplikasi yang berjalan pada platform yang ditentukan.

Blok khusus platform memberi Anda fleksibilitas dalam menyesuaikan pesan untuk berbagai platform, guna memastikan pesan ditangani dengan benar saat diterima. Backend FCM akan mempertimbangkan semua parameter yang telah ditentukan dan menyesuaikan pesan untuk setiap platform.

Kapan kolom umum digunakan

Gunakan kolom umum saat Anda:

• Menarget instance aplikasi di semua platform, baik Apple, Android, maupun web
• Mengirim pesan ke topik

Semua instance aplikasi, dari platform apa saja, dapat menafsirkan kolom umum berikut:

• message.notification.title
• message.notification.body
• message.data

Kapan kolom khusus platform digunakan

Gunakan kolom khusus platform ketika Anda ingin:

• Mengirim kolom hanya ke platform tertentu
• Mengirim kolom khusus platform bersama dengan kolom umum

Kapan pun Anda ingin mengirim nilai ke platform tertentu saja, jangan gunakan kolom umum; gunakan kolom khusus platform. Misalnya, untuk mengirim notifikasi ke platform Apple dan web saja, tetapi tidak ke Android, Anda harus menggunakan dua kumpulan kolom terpisah, yaitu satu untuk Apple dan satu lagi untuk web.

Saat Anda mengirim pesan dengan opsi pengiriman tertentu, gunakan kolom khusus platform untuk menetapkannya. Anda dapat menentukan beragam nilai untuk setiap platform jika mau. Namun, meskipun Anda ingin menetapkan nilai yang sama pada platform yang berbeda, Anda harus menggunakan kolom khusus platform. Alasannya, setiap platform mungkin menafsirkan nilai dengan sedikit berbeda. Misalnya, time to live ditetapkan di Android sebagai waktu habis masa berlaku dalam hitungan detik, sedangkan di Apple ditetapkan sebagai tanggal habis masa berlaku.

Contoh: pesan notifikasi dengan opsi pengiriman khusus platform

Permintaan kirim v1 berikut mengirimkan judul dan konten notifikasi umum ke semua platform, serta mengirimkan beberapa penggantian khusus platform. Secara khusus, permintaan:

• menetapkan time to live yang lama untuk platform Android dan Web, sekaligus menetapkan prioritas pesan APN (platform Apple) ke setelan rendah
• menetapkan kunci yang sesuai untuk menentukan hasil ketukan pengguna pada notifikasi di Android dan Apple — click_action, dan category.

{
  "message":{
     "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
     "notification":{
       "title":"Match update",
       "body":"Arsenal goal in added time, score is now 3-0"
     },
     "android":{
       "ttl":"86400s",
       "notification"{
         "click_action":"OPEN_ACTIVITY_1"
       }
     },
     "apns": {
       "headers": {
         "apns-priority": "5",
       },
       "payload": {
         "aps": {
           "category": "NEW_MESSAGE_CATEGORY"
         }
       }
     },
     "webpush":{
       "headers":{
         "TTL":"86400"
       }
     }
   }
 }

Baca dokumentasi referensi HTTP v1 untuk mengetahui detail lengkap tentang kunci yang tersedia di blok khusus platform dalam isi pesan. Untuk mengetahui informasi lebih lanjut tentang cara mem-build permintaan kirim yang memiliki isi pesan, baca Mem-build Permintaan Kirim.

Opsi pengiriman

FCM menyediakan sekumpulan opsi pengiriman khusus untuk pesan yang dikirim ke perangkat Android, dan membuat opsi serupa tersedia untuk platform Apple dan web. Misalnya, perilaku pesan yang "dapat diciutkan" didukung di perangkat Android melalui collapse_key FCM, di Apple melalui apns-collapse-id, dan di JavaScript/Web melalui Topic. Untuk mengetahui detailnya, baca deskripsi di bagian ini dan dokumentasi referensi terkait.

Pesan yang dapat dan tidak dapat diciutkan

Pesan yang tidak dapat diciutkan menunjukkan bahwa setiap pesan dikirimkan ke perangkat. Selain itu, pesan ini juga mengirimkan beberapa konten berguna. Ini kebalikan dari pesan yang dapat diciutkan yang, misalnya, berupa "ping" tanpa konten ke aplikasi seluler untuk menghubungi server agar mengambil data.

FCM tidak menjamin urutan pengiriman.

Beberapa kasus penggunaan umum untuk pesan yang tidak dapat diciutkan adalah pesan chat dan pesan penting. Misalnya, pada aplikasi IM, Anda tentunya ingin mengirim setiap pesan, karena setiap pesan memiliki konten berbeda.

Untuk Android, ada batas 100 pesan yang bisa disimpan tanpa diciutkan. Jika batas ini tercapai, semua pesan yang disimpan akan dihapus. Saat kembali online, perangkat akan menerima pesan khusus yang memberitahukan bahwa batas telah tercapai. Selanjutnya, aplikasi bisa menangani situasi ini dengan tepat, umumnya dengan meminta sinkronisasi penuh dari server aplikasi.

Pesan yang dapat diciutkan adalah pesan yang dapat diganti dengan pesan baru jika pesan tersebut belum dikirimkan ke perangkat.

Kasus penggunaan umum pesan yang dapat diciutkan adalah pesan yang digunakan untuk memberi tahu aplikasi seluler agar menyinkronkan data dari server. Contohnya adalah aplikasi olahraga yang mengirimkan informasi skor pertandingan terbaru kepada pengguna. Hanya pesan terbaru yang dianggap relevan.

Untuk menandai pesan sebagai dapat diciutkan di Android, sertakan parameter collapse_key dalam payload pesan. Secara default, kunci penciutan adalah nama paket aplikasi yang terdaftar di Firebase console. Server FCM bisa menyimpan empat pesan berbeda yang bisa diciutkan per perangkat secara bersamaan, masing-masing dengan kunci penciutan berbeda. Jika Anda melampaui angka ini, FCM hanya akan menyimpan empat kunci penciutan, tanpa jaminan kunci mana yang akan disimpan.

Pesan topik tanpa payload dapat diciutkan secara default. Pesan notifikasi selalu dapat diciutkan dan akan mengabaikan parameter collapse_key.

Mana yang harus saya gunakan?

Pesan yang dapat diciutkan merupakan pilihan yang lebih baik dari sudut pandang performa, apabila aplikasi Anda tidak perlu menggunakan pesan yang tidak dapat diciutkan. Akan tetapi, jika Anda menggunakan pesan yang dapat diciutkan, ingatlah bahwa FCM hanya mengizinkan maksimum empat kunci penciutan berbeda untuk digunakan oleh FCM per token pendaftaran pada suatu waktu tertentu. Anda tidak boleh melampaui jumlah ini; jika tidak, mungkin timbul konsekuensi yang tak bisa diprediksi.

	Skenario penggunaan	Cara mengirim
Tidak dapat diciutkan	Setiap pesan bersifat penting bagi aplikasi klien dan harus dikirimkan.	Semua pesan tidak dapat diciutkan secara default, kecuali pesan notifikasi.
Dapat diciutkan	Jika ada pesan baru yang membuat pesan lama terkait menjadi tidak relevan bagi aplikasi klien, FCM akan mengganti pesan lama. Misalnya: pesan yang digunakan untuk memulai sinkronisasi data dari server, atau pesan notifikasi usang.	Tetapkan parameter yang sesuai dalam permintaan pesan Anda: collapseKey di Android apns-collapse-id di Apple Topic di Web collapse_key dalam protokol lama (semua platform)

Menetapkan prioritas pesan

Anda memiliki dua opsi untuk menetapkan prioritas pengiriman pesan downstream: prioritas normal dan tinggi. Meskipun perilakunya sedikit berbeda di seluruh platform, pengiriman pesan berprioritas normal dan tinggi berfungsi seperti ini:

• Prioritas normal. Pesan berprioritas normal segera dikirim saat aplikasi berjalan di latar depan. Untuk aplikasi yang berjalan di latar belakang, pengiriman mungkin tertunda. Untuk pesan yang kurang mendesak dari segi waktu, misalnya notifikasi email baru, demi menjaga agar UI selalu sinkron, atau menyinkronkan data aplikasi di latar belakang, pilihlah prioritas pengiriman normal.

• Prioritas tinggi. FCM mencoba langsung mengirimkan pesan berprioritas tinggi meskipun perangkat berada dalam mode istirahat. Pesan berprioritas tinggi ditujukan untuk konten yang sensitif waktu dan terlihat oleh pengguna.

Saat mengirim pesan data ke perangkat Apple, prioritasnya harus ditetapkan ke 5, yaitu prioritas normal. Pesan yang dikirim dengan prioritas tinggi ditolak oleh backend FCM dengan error INVALID_ARGUMENT.

Berikut adalah contoh pesan berprioritas normal yang dikirim melalui protokol HTTP v1 FCM untuk memberi tahu pelanggan majalah bahwa konten baru siap didownload:

{
  "message":{
    "topic":"subscriber-updates",
    "notification":{
      "body" : "This week's edition is now available.",
      "title" : "NewsMagazine.com",
    },
    "data" : {
      "volume" : "3.21.15",
      "contents" : "http://www.news-magazine.com/world-week/21659772"
    },
    "android":{
      "priority":"normal"
    },
    "apns":{
      "headers":{
        "apns-priority":"5"
      }
    },
    "webpush": {
      "headers": {
        "Urgency": "high"
      }
    }
  }
}

Untuk mengetahui detail khusus platform selengkapnya terkait penetapan prioritas pesan:

• Dokumentasi APN
• Menetapkan dan mengelola prioritas pesan (Android)
• Urgensi pesan web push

Kasus penggunaan yang sangat penting

FCM API tidak dirancang untuk peringatan darurat atau aktivitas berisiko tinggi lainnya yang penggunaan atau kegagalan API-nya dapat mengakibatkan kematian, cedera pribadi, atau kerusakan lingkungan (seperti pengoperasian fasilitas nuklir, kontrol lalu lintas udara, atau sistem bantuan hidup). Penggunaan semacam itu secara tegas dilarang berdasarkan Pasal 4. a. 7 Persyaratan Layanan. Anda bertanggung jawab penuh atas pengelolaan kepatuhan aplikasi Anda terhadap Persyaratan dan segala kerusakan yang timbul dari ketidakpatuhan Anda. Google menyediakan API "apa adanya", dan berhak menghentikan API atau bagian atau fitur apa pun atau akses Anda ke API tersebut, dengan alasan apa pun dan kapan saja, tanpa tanggung jawab atau kewajiban lain kepada Anda atau pengguna Anda.

Menetapkan masa aktif pesan

FCM biasanya mengantarkan pesan segera setelah pesan dikirim. Namun, hal tersebut terkadang tidak dapat dilakukan. Misalnya, untuk platform Android, perangkat mungkin dimatikan, offline, atau tidak tersedia. Atau FCM mungkin sengaja menunda pesan agar aplikasi tidak menggunakan resource secara berlebihan dan berpengaruh negatif pada masa pakai baterai.

Jika ini terjadi, FCM akan menyimpan pesan dan mengirimkannya segera setelah kondisinya memungkinkan. Meskipun dalam kebanyakan kasus hal ini tidak menjadi masalah, ada beberapa aplikasi yang pesannya harus dikirim tepat waktu. Misalnya, untuk pesan berupa notifikasi video chat atau panggilan masuk, pesan tersebut hanya bermakna untuk periode waktu yang singkat sebelum panggilan tersebut diakhiri. Atau, jika pesan itu merupakan undangan ke sebuah acara, pesan tidak akan berguna jika diterima setelah acaranya berakhir.

Di Android dan Web/JavaScript, Anda dapat menentukan masa aktif maksimum suatu pesan. Nilainya harus berupa durasi dari 0 hingga 2.419.200 detik (28 hari), yaitu sama dengan periode waktu maksimum FCM menyimpan dan mencoba mengirimkan pesan. Permintaan yang tidak memuat kolom ini akan ditetapkan ke periode maksimum default empat minggu.

Berikut adalah beberapa kemungkinan penggunaan fitur ini:

• Panggilan masuk video chat
• Acara undangan yang akan segera kedaluwarsa
• Acara kalender

Keuntungan lain dari penetapan masa aktif pesan adalah FCM tidak menerapkan throttle pesan yang dapat diciutkan pada pesan yang memiliki nilai time to live 0 detik. FCM memberikan upaya penanganan pesan terbaik yang harus diberikan "sekarang atau tidak sama sekali". Perlu diingat bahwa jika nilai time_to_live 0, berarti pesan yang tidak dapat segera dikirimkan akan dihapus. Namun, karena pesan seperti itu tidak pernah disimpan, hal ini memberikan latensi terbaik untuk mengirim pesan notifikasi.

Berikut adalah contoh permintaan yang mencakup TTL:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    },
    "apns":{
      "headers":{
        "apns-expiration":"1604750400"
      }
    },
    "android":{
      "ttl":"4500s"
    },
    "webpush":{
      "headers":{
        "TTL":"4500"
      }
    }
  }
}

Masa aktif pesan

Saat server aplikasi memposting pesan ke FCM dan menerima kembali ID pesan, itu tidak berarti bahwa pesan sudah dikirimkan ke perangkat. Hal itu hanya berarti bahwa pesan telah diterima untuk dikirimkan. Apa yang terjadi pada pesan setelah diterima dipengaruhi oleh banyak faktor.

Dalam skenario kasus terbaik, jika perangkat terhubung dengan FCM, layarnya menyala, dan tidak ada pembatasan throttling, pesan akan segera dikirimkan.

Jika perangkat terhubung tetapi dalam mode Istirahat, pesan berprioritas rendah akan disimpan oleh FCM hingga perangkat keluar dari mode Istirahat. Di sinilah peran flag collapse_key: jika sudah ada pesan dengan kunci penciutan (dan token pendaftaran) yang sama tersimpan dan menunggu dikirimkan, pesan lama akan dihapus dan pesan baru akan menggantikannya (artinya, pesan lama diciutkan oleh pesan baru). Namun, jika kunci penciutan tidak ditetapkan, baik pesan lama maupun pesan baru akan disimpan untuk dikirimkan kemudian.

Jika perangkat tidak terhubung ke FCM, pesan akan disimpan hingga terhubung (lagi-lagi dengan mematuhi aturan kunci penciutan). Saat terhubung, FCM akan mengirimkan semua pesan yang tertunda ke perangkat. Jika perangkat tidak pernah terhubung kembali (misalnya, jika perangkat direset ke setelan pabrik), pesan akan kehabisan waktu dan dihapus dari penyimpanan FCM. Waktu tunggu default adalah empat minggu, kecuali jika flag time_to_live ditetapkan.

Untuk menganalisis lebih lanjut pengiriman pesan:

Untuk menganalisis lebih lanjut pengiriman pesan di Android atau platform Apple, lihat dasbor pelaporan FCM, yang mencatat jumlah pesan yang terkirim dan dibuka di perangkat Apple dan Android, beserta data untuk "tayangan" (notifikasi yang dilihat oleh pengguna) untuk aplikasi Android.

Untuk perangkat Android yang mengaktifkan pesan saluran langsung, jika perangkat tidak terhubung ke FCM selama lebih dari satu bulan, FCM akan tetap menerima pesan, tetapi akan segera menghapusnya. Jika perangkat terhubung dalam waktu empat minggu sejak terakhir dikirimi pesan data, klien Anda akan menerima callback onDeletedMessages(). Selanjutnya, aplikasi bisa menangani situasi ini dengan tepat, umumnya dengan meminta sinkronisasi penuh dari server aplikasi.

Terakhir, ketika FCM mencoba mengirimkan pesan ke perangkat dan aplikasi sudah di-uninstal, FCM akan langsung menghapus pesan tersebut dan membatalkan validasi token pendaftaran. Setelah itu, semua upaya pengiriman pesan ke perangkat tersebut akan menghasilkan error NotRegistered.

Throttling dan kuota

Kami berupaya untuk menyampaikan setiap pesan yang dikirimkan melalui FCM. Namun, jika kami menyampaikan setiap pesan, pengalaman pengguna secara keseluruhan dapat terganggu. Selain itu, kami perlu menetapkan batasan untuk memastikan bahwa FCM menyediakan layanan yang skalabel bagi semua pengirim. Jenis batas dan kuota yang dijelaskan di bagian ini membantu kami menyeimbangkan faktor penting ini.

Catatan: Batas yang dibahas dalam bagian ini dapat berubah sewaktu-waktu.

Throttling pesan downstream

HTTP v1 API memperkenalkan kuota per project, per menit untuk pesan downstream. Kuota default 600 ribu pesan per menit mencakup lebih dari 99% developer FCM sekaligus melindungi stabilitas sistem dan meminimalkan dampak project yang tidak stabil.

Pola traffic yang melonjak dapat mengakibatkan error kuota terlampaui. Dalam skenario di mana kuota terlampaui, sistem akan menampilkan kode status HTTP 429 (QUOTA_EXCEEDED) hingga kuota diisi ulang pada menit berikutnya. 429 respons juga dapat ditampilkan dalam situasi kelebihan beban, jadi sebaiknya Anda menangani 429 respons sesuai dengan rekomendasi yang dipublikasikan.

Perhatikan bahwa:

• Kuota downstream mengukur pesan, bukan permintaan.
• Error klien (kode status HTTP 400-499) dihitung (tidak termasuk 429).
• Kuota dihitung per menit, tetapi menit ini tidak selaras dengan jam.

Kuota pemantauan

Anda dapat melihat kuota, penggunaan, dan error di Konsol Google Cloud:

1. Buka Google Cloud console
2. Pilih APIs & services
3. Dari daftar tabel, pilih Firebase Cloud Messaging API
4. Pilih QUOTA & SYSTEM LIMITS.

CATATAN: Grafik ini tidak selaras secara tepat dengan menit kuota, artinya 429 mungkin disajikan saat traffic terlihat berada di bawah kuota.

Meminta penambahan kuota

Sebelum meminta penambahan kuota, pastikan:

• Penggunaan Anda secara rutin ≥ 80% dari kuota selama minimal 5 menit berturut-turut per hari.
• Anda memiliki rasio error klien < 5%, terutama selama traffic puncak.
• Anda mematuhi praktik terbaik untuk mengirim pesan dalam skala besar.

Jika memenuhi kriteria ini, Anda dapat mengirimkan permintaan peningkatan kuota hingga +25% dan FCM akan melakukan setiap upaya praktis untuk memenuhi permintaan tersebut (tidak ada peningkatan yang dapat dijamin).

Jika Anda memerlukan kuota pesan downstream lebih banyak karena peluncuran yang akan datang atau peristiwa sementara, mintalah kuota Anda setidaknya 15 hari sebelumnya agar terdapat waktu yang cukup untuk menangani permintaan tersebut. Untuk permintaan besar (>18 juta pesan per menit), setidaknya diperlukan pemberitahuan 30 hari sebelumnya. Peluncuran dan permintaan peristiwa khusus masih tunduk pada persyaratan rasio error klien dan praktik terbaik.

Lihat juga FAQ tentang kuota FCM.

Batas pesan topik

Tingkat penambahan/penghapusan langganan topik dibatasi hingga 3.000 QPS per project.

Untuk mengetahui tingkat pengiriman pesan, baca artikel mengenai Throttling Fanout.

Throttling fanout

Fanout pesan adalah proses pengiriman pesan ke beberapa perangkat, seperti saat Anda menarget topik dan grup, atau saat Anda menggunakan Notifications composer untuk menarget audience atau segmen pengguna.

Fanout pesan tidak berjalan seketika, jadi terkadang ada beberapa fanout yang sedang diproses secara bersamaan. Batas jumlah fanout pesan yang diproses secara bersamaan per project adalah 1.000. Di atas itu, kami dapat menolak permintaan fanout tambahan atau menunda fanout permintaan tersebut sampai beberapa fanout yang sedang diproses selesai.

Kapasitas fanout aktual yang dapat dicapai dipengaruhi oleh jumlah project yang meminta fanout pada saat yang bersamaan. Tidak jarang fanout untuk suatu project mencapai 10.000 QPS, tetapi angka tersebut bukan jaminan dan merupakan hasil dari total beban pada sistem. Penting untuk diperhatikan bahwa kapasitas fanout yang tersedia dibagi antar-project dan bukan untuk seluruh permintaan fanout. Jadi, jika project Anda memiliki dua fanout yang sedang diproses, setiap fanout hanya akan mendapatkan setengah dari kapasitas fanout yang tersedia. Cara yang disarankan untuk memaksimalkan kecepatan fanout Anda adalah dengan hanya memiliki satu fanout aktif yang sedang diproses dalam satu waktu.

Throttling pesan yang dapat diciutkan

Seperti dijelaskan di atas, pesan yang dapat diciutkan adalah notifikasi bebas konten yang didesain agar dapat menciut secara bertumpuk. Jika developer terlalu sering mengulangi pesan yang sama ke suatu aplikasi, kami akan menunda (men-throttle) pesan untuk mengurangi dampak pada baterai pengguna.

Misalnya, jika Anda mengirim sejumlah besar permintaan sinkronisasi email baru ke satu perangkat, kami mungkin menunda permintaan sinkronisasi email berikutnya selama beberapa menit sehingga perangkat dapat melakukan sinkronisasi pada tingkat rata-rata yang lebih rendah. Throttling ini dilakukan semata-mata untuk membatasi dampak pada baterai yang dialami oleh pengguna.

Jika kasus penggunaan Anda membutuhkan pola pengiriman burst tinggi, maka pesan yang tidak dapat diciutkan mungkin merupakan pilihan yang tepat. Untuk pesan semacam itu, pastikan Anda memasukkan konten ke dalam pesan tersebut untuk mengurangi dampak pada baterai.

Kami membatasi burst berisi 20 pesan yang dapat diciutkan per aplikasi per perangkat, dengan isi ulang 1 pesan setiap 3 menit.

Throttling server XMPP

Perhatian: Mengirim pesan (termasuk pesan upstream) dengan API lama XMPP dan HTTP FCM sudah tidak digunakan lagi pada 20 Juni 2023, dan akan dihapus pada Juni 2024.. Jika Anda menggunakan API kirim FCM yang lama, sebaiknya lakukan migrasi ke HTTP v1 API atau pertimbangkan untuk menggunakan Admin SDK untuk membuat permintaan kirim.

Kami membatasi koneksi Anda ke server XMPP FCM hingga 400 koneksi per menit per project. Hal ini seharusnya tidak menjadi masalah untuk pengiriman pesan, tetapi diperlukan untuk memastikan kestabilan sistem kami. Untuk setiap project, FCM mengizinkan 2.500 koneksi secara paralel.

Untuk pengiriman pesan upstream dengan XMPP, FCM membatasi pesan upstream hingga 1.500.000/menit per project agar server tujuan upstream tidak kelebihan beban.

Kami membatasi pesan upstream per perangkat hingga 1.000/menit agar tidak menguras baterai akibat perilaku aplikasi yang buruk.

Tingkat pesan maksimum ke satu perangkat

Untuk Android, Anda dapat mengirim hingga 240 pesan/menit dan 5.000 pesan/jam ke satu perangkat. Ambang batas tinggi ini dimaksudkan untuk memungkinkan burst traffic jangka pendek, seperti ketika pengguna berinteraksi dengan cepat melalui chat. Batas ini mencegah error dalam logika pengiriman karena menghabiskan baterai pada suatu perangkat secara tidak sengaja.

Untuk iOS, kami akan menampilkan error saat tarif melebihi batas APN.

Perhatian: Jangan rutin mengirim pesan dengan jumlah yang mendekati tingkat maksimum ini. Hal ini dapat memboroskan resource pengguna akhir, dan aplikasi Anda berisiko ditandai sebagai aplikasi yang merugikan.

FCM port dan firewall Anda

Jika organisasi Anda memiliki firewall untuk membatasi traffic ke atau dari Internet, Anda harus mengonfigurasinya agar perangkat seluler dapat terhubung dengan FCM dan perangkat di jaringan Anda dapat menerima pesan. FCM biasanya menggunakan port 5228, tetapi kadang menggunakan 443, 5229, dan 5230.

Untuk perangkat yang terhubung di jaringan Anda, FCM tidak memberikan IP khusus karena rentang IP kami terlalu sering berubah dan aturan firewall Anda dapat habis masa berlakunya, sehingga memengaruhi pengalaman pengguna Anda. Idealnya, beri akses port 5228-5230 & 443 tanpa pembatasan IP. Namun, jika harus memiliki pembatasan IP, Anda harus memberikan akses ke semua alamat IP yang tercantum di goog.json. Daftar besar ini diperbarui secara berkala, jadi sebaiknya perbarui aturan Anda setiap bulan. Masalah yang disebabkan oleh pembatasan IP firewall biasanya terkadang hilang dan kemudian muncul kembali, serta sulit didiagnosis.

Kami menawarkan serangkaian nama domain yang dapat diberi akses, bukan alamat IP. Nama host tersebut tercantum di bawah ini. Jika kami mulai menggunakan nama host tambahan, kami akan memperbarui daftar di sini. Menggunakan nama domain untuk aturan firewall mungkin berfungsi atau tidak berfungsi di perangkat firewall Anda.

Port TCP yang akan dibuka:

• 5228
• 5229
• 5230
• 443

Nama host yang akan dibuka:

• mtalk.google.com
• mtalk4.google.com
• mtalk-staging.google.com
• mtalk-dev.google.com
• alt1-mtalk.google.com
• alt2-mtalk.google.com
• alt3-mtalk.google.com
• alt4-mtalk.google.com
• alt5-mtalk.google.com
• alt6-mtalk.google.com
• alt7-mtalk.google.com
• alt8-mtalk.google.com
• android.apis.google.com
• device-provisioning.googleapis.com
• firebaseinstallations.googleapis.com

Firewall Penafsiran Alamat Jaringan (NAT) dan/atau Stateful Packet Inspection:

Jika jaringan Anda menerapkan Penafsiran Alamat Jaringan (NAT) atau Stateful Packet Inspection (SPI), terapkan waktu tunggu 30 menit atau lebih untuk koneksi kami melalui port 5228-5230. Dengan begitu, kami dapat menyediakan konektivitas yang andal sekaligus mengurangi konsumsi baterai pada perangkat seluler pengguna Anda.

Catatan: Jika Anda menerima notifikasi melalui APN, pastikan Anda juga telah membuka port yang ditentukan oleh Apple.

Interaksi dan kemampuan untuk mengabaikan VPN

Firebase Cloud Messaging mengambil berbagai langkah untuk memastikan bahwa koneksi pesan push dari ponsel ke server dapat diandalkan dan tersedia sesering mungkin. Penggunaan VPN akan mempersulit upaya ini.

VPN menyamarkan informasi pokok yang diperlukan FCM untuk menyesuaikan koneksinya guna memaksimalkan keandalan & masa pakai baterai. Dalam beberapa kasus, VPN secara aktif memutuskan koneksi jangka panjang yang mengakibatkan pengalaman pengguna yang buruk karena pesan yang hilang atau tertunda, atau biaya baterai yang tinggi. Ketika VPN dikonfigurasi untuk mengizinkan kita melakukannya, kita akan mengabaikan VPN menggunakan koneksi terenkripsi (melalui jaringan dasar Wi-Fi atau LTE) memastikan pengalaman yang andal dan ramah baterai. Penggunaan VPN yang dapat diabaikan oleh FCM dikhususkan untuk saluran Notifikasi Push FCM. Traffic FCM lainnya, seperti traffic pendaftaran, menggunakan VPN jika aktif. Saat koneksi FCM mengabaikan VPN, manfaat tambahan yang mungkin diberikan oleh VPN akan hilang, seperti penyamaran IP.

VPN yang berbeda akan memiliki metode yang berbeda untuk mengontrol apakah VPN tersebut dapat diabaikan atau tidak. Lihat dokumentasi untuk VPN spesifik Anda guna mengetahui petunjuknya.

Jika VPN tidak dikonfigurasi agar dapat diabaikan, Firebase Cloud Messaging akan menggunakan jaringan VPN untuk terhubung ke server. Hal ini dapat menyebabkan periode waktu saat pesan tertunda dan dapat menyebabkan lebih banyak penggunaan baterai karena Cloud Messaging berfungsi untuk mempertahankan koneksi melalui koneksi VPN.

Kredensial

Bergantung pada fitur FCM yang diterapkan, Anda mungkin membutuhkan kredensial berikut dari project Firebase Anda:

Project ID	ID unik untuk project Firebase Anda, yang digunakan dalam permintaan ke endpoint HTTP FCM v1. Nilai ini tersedia di panel Settings Firebase console.
Token pendaftaran	String token unik yang mengidentifikasi setiap instance aplikasi klien. Token pendaftaran diperlukan untuk pengiriman pesan satu perangkat dan grup perangkat. Perlu diperhatikan bahwa token pendaftaran harus dirahasiakan.
ID Pengirim	Nilai numerik unik yang dibuat saat Anda membuat project Firebase, yang tersedia di tab Cloud Messaging pada panel Settings Firebase console. ID pengirim digunakan untuk mengidentifikasi setiap pengirim yang dapat mengirim pesan ke aplikasi klien.
Token akses	Token OAuth 2.0 berumur pendek yang mengizinkan permintaan ke HTTP v1 API. Token ini dikaitkan dengan akun layanan milik project Firebase Anda. Untuk membuat dan merotasi token akses, ikuti langkah-langkah yang dijelaskan di artikel Mengizinkan Permintaan Kirim.
Kunci server (untuk protokol lama **tidak digunakan lagi**)	Kunci server yang memberikan otorisasi kepada server aplikasi untuk mengakses layanan Google, termasuk mengirim pesan lewat protokol lama Firebase Cloud Messaging yang sudah tidak lagi digunakan. Penting: Jangan sertakan kunci server di mana pun pada kode klien. Selain itu, pastikan Anda hanya menggunakan kunci server untuk memberikan otorisasi kepada server aplikasi. Kunci Android, platform Apple, dan browser ditolak oleh FCM.