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.
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 baki 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"
}
}
}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.
Menyetel 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.
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:
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.
Kredensial
Bergantung pada fitur FCM yang diterapkan, Anda mungkin membutuhkan kredensial berikut dari project Firebase Anda:
| ID Project | 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. |