Protokol XMPP Firebase Cloud Messaging

Dokumen ini menyediakan referensi untuk sintaksis XMPP yang digunakan untuk meneruskan pesan antara server aplikasi Anda, aplikasi klien, dan Firebase Cloud Messaging (FCM). Server aplikasi Anda harus terhubung ke endpoint berikut ini:

// Production
fcm-xmpp.googleapis.com:5235

// Testing
fcm-xmpp.googleapis.com:5236

Parameter dan opsi yang tersedia masuk ke dalam beberapa kategori berikut ini:

Sintaksis pesan downstream

Bagian ini memberikan sintaksis untuk mengirim pesan downstream.

Pesan XMPP Downstream (JSON)

Tabel berikut ini berisi daftar target, opsi, dan payload untuk pesan JSON XMPP.

Tabel 1 Target, opsi, dan payload untuk pesan XMPP downstream (JSON).

Parameter Penggunaan Deskripsi
Target
to Opsional, string

Parameter ini menetapkan penerima pesan.

Nilainya dapat berupa token pendaftaran perangkat, kunci notifikasi grup perangkat, atau topik tunggal (diawali dengan /topics/). Untuk mengirim ke beberapa topik, gunakan parameter condition.
condition Opsional, string

Parameter ini menetapkan ekspresi logika dari kondisi yang menentukan target pesan.

Kondisi yang didukung: Topik, yang diformat sebagai "'yourTopic' dalam topik". Nilai ini tidak peka huruf besar/kecil.

Operator yang didukung: &&, ||. Maksimum dua operator per pesan topik yang didukung.
Opsi
message_id Wajib, string

Parameter ini secara unik mengidentifikasi pesan dalam koneksi XMPP.
collapse_key Opsional, string

Parameter ini mengidentifikasi grup pesan (misalnya, dengan collapse_key: "Updates Available") yang dapat diciutkan sehingga hanya pesan terakhir yang dikirim saat pengiriman dilanjutkan. Tujuannya adalah agar tidak terlalu banyak mengirim pesan yang sama ketika perangkat kembali online atau keluar dari mode Istirahat.

Tidak ada jaminan untuk urutan pesan yang akan dikirim.

Catatan: Maksimum 4 kunci penciutan berbeda diizinkan pada waktu tertentu. Artinya, FCM dapat menyimpan 4 pesan berbeda secara bersamaan per aplikasi klien. Jika Anda melebihi jumlah ini, tidak ada jaminan manakah dari empat kunci penciutan ini yang akan disimpan oleh FCM.

priority Opsional, string

Menetapkan prioritas pesan. Nilai yang valid adalah "normal" dan "high". Di platform Apple, hal ini sesuai dengan prioritas APN 5 dan 10.

Secara default, pesan notifikasi dikirim dengan prioritas tinggi dan pesan data dikirim dengan prioritas normal. Prioritas normal mengoptimalkan konsumsi baterai aplikasi klien dan sebaiknya digunakan kecuali jika diperlukan pengiriman dengan segera. Untuk pesan dengan prioritas normal, aplikasi dapat menerima pesan dengan penundaan yang tidak ditetapkan.

Jika dikirim dengan prioritas tinggi, pesan akan dikirim dengan segera dan aplikasi dapat menampilkan notifikasi.
content_available Opsional, boolean

Di platform Apple, gunakan kolom ini untuk mewakili content-available dalam payload APN. Saat notifikasi atau pesan dikirim dan parameter ini disetel ke true, aplikasi klien yang tidak aktif akan diaktifkan, serta pesan akan dikirim melalui APN sebagai notifikasi diam dan tidak melalui FCM. Perhatikan bahwa notifikasi diam pada APN tidak dijamin akan dikirim, dan dapat bergantung pada faktor-faktor, seperti apakah pengguna mengaktifkan Mode Daya Rendah, menghentikan aplikasi secara paksa, dll. Di Android, secara default pesan data akan mengaktifkan aplikasi. Pada Chrome, untuk saat ini belum didukung.
mutable_content Opsional, boolean JSON

Di platform Apple, gunakan kolom ini untuk mewakili mutable-content dalam payload APN. Jika notifikasi dikirim dan parameter ini ditetapkan ke true, isi notifikasi dapat dimodifikasi sebelum ditampilkan dengan menggunakan ekstensi aplikasi Notification Service. Parameter ini akan diabaikan untuk Android dan web.

time_to_live Opsional, angka

Parameter ini menetapkan berapa lama (dalam detik) pesan harus disimpan dalam penyimpanan FCM jika perangkat sedang offline. Time to live maksimum yang didukung adalah 4 minggu, dan nilai defaultnya adalah 4 minggu. Untuk informasi lebih lanjut, lihat Menetapkan masa aktif pesan.

dry_run Opsional, boolean

Jika disetel ke true, parameter ini memungkinkan developer untuk menguji permintaan tanpa benar-benar mengirim pesan.

Nilai defaultnya adalah false.
Payload
data Opsional, objek

Parameter ini menetapkan key-value pair payload pesan.

Misalnya, dengan data:{"score":"3x1"}:

Di platform Apple, jika pesan dikirim melalui APN, pesan tersebut mewakili kolom data kustom. Jika dikirimkan oleh FCM, pesan tersebut ditunjukkan sebagai kamus nilai kunci di AppDelegate application:didReceiveRemoteNotification:.

Di Android, parameter ini menghasilkan tambahan intent bernama score dengan nilai string 3x1.

Kunci tidak boleh berupa kata yang telah digunakan ("from" atau "message_type", atau kata apa pun yang dimulai dengan "google" atau "gcm"). Jangan gunakan kata apa pun yang didefinisikan dalam tabel ini (seperti collapse_key).

Nilai dalam jenis string direkomendasikan. Anda harus mengonversi nilai dalam objek atau jenis data non-string lainnya (misalnya, bilangan bulat atau boolean) menjadi string.
notification Opsional, objek Parameter ini menetapkan key-value pair bawaan yang dapat dilihat pengguna untuk payload notifikasi. Lihat Dukungan payload notifikasi untuk mengetahui detailnya. Untuk mengetahui informasi lebih lanjut mengenai opsi pesan notifikasi dan pesan data, lihat Jenis pesan. Jika payload notifikasi disediakan, atau opsi content_available ditetapkan ke true untuk pesan ke perangkat Apple, pesan tersebut akan dikirim melalui APN. Sebaliknya, pesan akan dikirim melalui FCM.

Dukungan payload notifikasi

Tabel di bawah ini mencantumkan kunci bawaan yang tersedia untuk membuat pesan notifikasi untuk platform Apple dan Android.

Tabel 2a. Apple — kunci untuk pesan notifikasi

Parameter Penggunaan Deskripsi
title Opsional, string

Judul notifikasi.

Kolom ini tidak ditampilkan di ponsel dan tablet.
body Opsional, string

Teks isi notifikasi.
sound Opsional, string

Suara yang diputar saat perangkat menerima notifikasi.

String yang menentukan file suara dalam paket utama aplikasi klien atau dalam folder Library/Sounds di container data aplikasi. Lihat Library Developer iOS untuk informasi selengkapnya.

badge Opsional, string

Nilai badge pada ikon aplikasi layar utama.

Jika tidak ditentukan, badge tidak diubah.

Jika disetel ke 0, badge dihapus.
click_action Opsional, string

Tindakan yang terkait dengan klik pengguna pada notifikasi.

Terkait dengan category dalam payload APN.
subtitle Opsional, string

Subjudul notifikasi.
body_loc_key Opsional, string

Kunci untuk string isi di dalam resource string aplikasi yang akan digunakan untuk melokalkan teks isi ke bahasa pengguna saat ini.

Terkait dengan loc-key dalam payload APN.

Baca Referensi Kunci Payload dan Melokalkan Isi Notifikasi Jarak Jauh untuk mengetahui informasi selengkapnya.
body_loc_args Opsional, array JSON sebagai string

Nilai string variabel yang akan digunakan sebagai pengganti penentu format dalam body_loc_key untuk melokalkan teks isi ke bahasa pengguna saat ini.

Terkait dengan loc-args dalam payload APN.

Baca Referensi Kunci Payload dan Melokalkan Isi Notifikasi Jarak Jauh untuk mengetahui informasi selengkapnya.
title_loc_key Opsional, string

Kunci untuk string judul di dalam resource string aplikasi yang akan digunakan untuk melokalkan teks judul ke bahasa pengguna saat ini.

Terkait dengan title-loc-key dalam payload APN.

Baca Referensi Kunci Payload dan Melokalkan Isi Notifikasi Jarak Jauh untuk mengetahui informasi selengkapnya.
title_loc_args Opsional, array JSON sebagai string

Nilai string variabel yang akan digunakan sebagai pengganti penentu format dalam title_loc_key untuk melokalkan teks judul ke bahasa pengguna saat ini.

Terkait dengan title-loc-args dalam payload APN.

Baca Referensi Kunci Payload dan Melokalkan Isi Notifikasi Jarak Jauh untuk mengetahui informasi selengkapnya.

Tabel 2b. Android — kunci untuk pesan notifikasi

Parameter Penggunaan Deskripsi
title Opsional, string

Judul notifikasi.
body Opsional, string

Teks isi notifikasi.
android_channel_id Opsional, string

ID saluran notifikasi (baru di Android O).

Aplikasi harus membuat saluran dengan ID saluran ini sebelum menerima notifikasi apa pun dengan ID saluran ini.

Jika Anda tidak mengirim ID saluran ini pada permintaan, atau jika ID saluran yang disediakan belum dibuat oleh aplikasi, FCM akan menggunakan ID saluran yang ditentukan dalam manifes aplikasi.

icon Opsional, string

Ikon notifikasi.

Menyetel ikon notifikasi ke myicon untuk resource drawable myicon. Jika Anda tidak mengirim kunci ini dalam permintaan, FCM akan menampilkan ikon peluncur yang ditentukan dalam manifes aplikasi.

sound Opsional, string

Suara yang diputar saat perangkat menerima notifikasi.

Mendukung "default" atau nama file resource suara yang dipaketkan dalam aplikasi. File suara harus berada di /res/raw/.
tag Opsional, string

ID yang digunakan untuk mengganti notifikasi yang ada di panel samping notifikasi.

Jika tidak ditentukan, setiap permintaan akan membuat notifikasi baru.

Jika ditentukan dan notifikasi dengan tag yang sama telah ditampilkan, notifikasi yang baru akan menggantikan notifikasi lama di panel samping notifikasi.
color Opsional, string

Warna ikon notifikasi, dinyatakan dalam format #rrggbb.
click_action Opsional, string

Tindakan yang terkait dengan klik pengguna pada notifikasi.

Jika ditentukan, aktivitas dengan filter intent yang cocok akan diluncurkan ketika pengguna mengklik notifikasi.
body_loc_key Opsional, string

Kunci untuk string isi di dalam resource string aplikasi yang akan digunakan untuk melokalkan teks isi ke bahasa pengguna saat ini.

Lihat Resource String untuk informasi lebih lanjut.

body_loc_args Opsional, array JSON sebagai string

Nilai string variabel yang akan digunakan sebagai pengganti penentu format dalam body_loc_key untuk melokalkan teks isi ke bahasa pengguna saat ini.

Lihat Pengaturan Format dan Gaya untuk informasi lebih lanjut.

title_loc_key Opsional, string

Kunci untuk string judul di dalam resource string aplikasi yang akan digunakan untuk melokalkan teks judul ke bahasa pengguna saat ini.

Lihat Resource String untuk informasi lebih lanjut.

title_loc_args Opsional, array JSON sebagai string

Nilai string variabel yang akan digunakan sebagai pengganti penentu format dalam title_loc_key untuk melokalkan teks judul ke bahasa pengguna saat ini.

Lihat Pengaturan Format dan Gaya untuk informasi lebih lanjut.

Tabel 2c. Web (JavaScript) — kunci untuk pesan notifikasi

Parameter Penggunaan Deskripsi
title Opsional, string

Judul notifikasi.
body Opsional, string

Teks isi notifikasi.
icon Opsional, string

URL yang akan digunakan untuk ikon notifikasi.
click_action Opsional, string

Tindakan yang terkait dengan klik pengguna pada notifikasi.

Untuk semua nilai URL, diperlukan HTTPS.

Menafsirkan respons pesan XMPP downstream

Tabel berikut berisi daftar kolom yang muncul dalam respons pesan XMPP downstream.

Tabel 3 Isi respons XMPP pesan downstream.

Parameter Penggunaan Deskripsi
from Wajib, string

Parameter ini menetapkan siapa yang mengirim respons ini.

Nilainya adalah token pendaftaran aplikasi klien.
message_id Wajib, string Parameter ini secara unik mengidentifikasi pesan dalam koneksi XMPP. Nilainya adalah string yang secara unik mengidentifikasi pesan yang terkait.
message_type Wajib, string

Parameter ini menentukan pesan ack atau nack dari FCM ke server aplikasi.

Jika nilainya disetel ke nack, server aplikasi harus melihat error dan error_description untuk mendapatkan informasi kegagalan.

error Opsional, string Parameter ini menetapkan error yang terkait dengan pesan downstream. Ini ditetapkan ketika message_type adalah nack. Lihat tabel 4 untuk detailnya.
error_description Opsional, string Parameter ini menyediakan informasi deskriptif untuk error. Ini ditetapkan ketika message_type adalah nack.

Kode respons error untuk pesan downstream

Tabel berikut berisi daftar kode respons error untuk pesan downstream.

Tabel 4 Kode respons error pesan downstream.

Error Kode XMPP Tindakan yang disarankan
Token Pendaftaran Hilang INVALID_JSON Periksa apakah permintaan memuat token pendaftaran (pada registration_id dalam pesan teks biasa, atau pada kolom to atau registration_ids dalam JSON).
Pendaftaran APN Tidak Valid INVALID_JSON Untuk pendaftaran iOS, pastikan permintaan pendaftaran dari klien berisi token APN dan ID aplikasi yang valid.
Token Pendaftaran Tidak Valid BAD_REGISTRATION Periksa format token pendaftaran yang Anda teruskan ke server. Pastikan token tersebut sama dengan token pendaftaran yang diterima aplikasi klien ketika mendaftar ke FCM. Jangan memotong atau memasukkan karakter tambahan.
Perangkat Tidak Terdaftar DEVICE_UNREGISTERED Token pendaftaran yang ada bisa menjadi tidak valid dalam sejumlah skenario, termasuk:
  • Jika aplikasi klien membatalkan pendaftaran di FCM.
  • Jika pendaftaran aplikasi klien dibatalkan secara otomatis, yang bisa terjadi jika pengguna meng-uninstal aplikasi. Misalnya, pada iOS, jika APN melaporkan token APN sebagai tidak valid.
  • Jika masa berlaku token pendaftaran habis (misalnya, Google mungkin memutuskan untuk memperbarui token pendaftaran, atau token APN sudah tidak berlaku untuk perangkat).
  • Jika aplikasi klien diupdate tetapi versi yang baru belum dikonfigurasi untuk menerima pesan.
Untuk semua kasus tersebut, hapus token pendaftaran dari server aplikasi dan jangan gunakan lagi untuk mengirim pesan.
Pengirim Tidak Cocok SENDER_ID_MISMATCH Token pendaftaran terikat pada grup pengirim tertentu. Ketika aplikasi klien mendaftar ke FCM, aplikasi tersebut harus menetapkan pengirim mana saja yang diizinkan untuk mengirim pesan. Anda harus menggunakan salah satu ID pengirim tersebut ketika mengirim pesan ke aplikasi klien. Jika Anda beralih ke pengirim yang berbeda, token pendaftaran yang ada tidak akan berfungsi.
JSON tidak valid INVALID_JSON Pastikan pesan JSON diformat dengan benar dan berisi kolom yang valid (misalnya, memastikan bahwa jenis data yang diteruskan benar).
Pesan Terlalu Besar INVALID_JSON Pastikan ukuran total data payload yang disertakan dalam pesan tidak melebihi batas FCM, yaitu 4.096 byte untuk sebagian besar pesan atau 2.048 byte untuk pesan ke topik. Ini mencakup kunci dan nilainya.
Kunci Data Tidak Valid INVALID_JSON Pastikan data payload tidak berisi kunci (seperti from, gcm, atau nilai apa pun yang diawali dengan google) yang digunakan secara internal oleh FCM. Perlu diperhatikan bahwa beberapa kata (misalnya collapse_key) juga digunakan oleh FCM, tetapi diizinkan dalam payload. Dalam hal ini, nilai payload akan diganti oleh nilai FCM.
Time to Live (TTL) Tidak Valid INVALID_JSON Pastikan nilai yang digunakan dalam time_to_live adalah bilangan bulat yang mewakili durasi dalam detik antara 0 dan 2.419.200 (4 minggu).
Pesan ACK buruk BAD_ACK Pastikan pesan ack diformat dengan benar sebelum mencoba ulang. Lihat tabel 6 untuk detailnya.
Waktu Tunggu Habis SERVICE_UNAVAILABLE

Server tidak bisa memproses permintaan secara tepat waktu. Coba lagi permintaan yang sama, tetapi Anda harus:

  • Menerapkan backoff eksponensial dalam mekanisme percobaan ulang. (misalnya jika Anda menunggu satu detik sebelum percobaan ulang pertama, tunggu setidaknya dua detik sebelum percobaan berikutnya, lalu empat detik, dan seterusnya). Jika Anda mengirim beberapa pesan, tunda setiap pesan secara terpisah dengan jumlah acak tambahan agar tidak mengeluarkan permintaan baru untuk semua pesan secara bersamaan.
  • Penundaan percobaan ulang pertama harus diatur ke satu detik.

Catatan: Pengirim yang menyebabkan masalah berisiko dimasukkan ke daftar hitam.
Error Server Internal INTERNAL_SERVER_
ERROR		 Server mengalami error ketika mencoba memproses permintaan. Anda bisa mencoba lagi permintaan yang sama sesuai persyaratan yang tercantum dalam "Waktu Tunggu" (lihat baris di atas).
Tingkat Pengiriman Pesan ke Perangkat Terlampaui DEVICE_MESSAGE_RATE
_EXCEEDED		 Tingkat pengiriman pesan ke perangkat tertentu terlalu tinggi. Kurangi jumlah pesan yang dikirim ke perangkat ini, dan jangan langsung mencoba mengirimkan pesan lagi ke perangkat ini.
Tingkat Pengiriman Pesan Topik Terlampaui TOPICS_MESSAGE_RATE
_EXCEEDED		 Tingkat pengiriman pesan ke pelanggan topik tertentu terlalu tinggi. Kurangi jumlah pesan yang dikirim ke topik ini, dan jangan langsung mencoba mengirimkan pesan lagi.
Pengosongan Koneksi CONNECTION_DRAINING Pesan tidak bisa diproses karena koneksi dikosongkan. Hal ini terjadi karena FCM perlu menutup koneksi secara berkala untuk melakukan load balancing. Coba lagi proses pesan tersebut melalui koneksi XMPP yang lain.
Kredensial APN Tidak Valid INVALID_APNS_CREDENTIAL Pesan yang ditargetkan ke perangkat iOS tidak bisa dikirim, karena kunci autentikasi APN yang diperlukan tidak diupload atau masa berlakunya sudah habis. Periksa validitas kredensial pengembangan dan produksi Anda.
Autentikasi Gagal AUTHENTICATION_FAILED Gagal melakukan autentikasi dengan layanan push eksternal. Pastikan Anda menggunakan sertifikat web push yang benar.

Sintaksis pesan upstream

Pesan upstream adalah pesan yang dikirim oleh aplikasi klien ke server aplikasi. Saat ini, hanya XMPP yang mendukung pengiriman pesan upstream. Lihat dokumentasi untuk platform Anda guna mendapatkan informasi lebih lanjut mengenai cara mengirim pesan dari aplikasi klien.

Menafsirkan pesan XMPP upstream

Tabel berikut memberikan penjelasan tentang berbagai kolom di dalam stanza XMPP yang dihasilkan oleh FCM sebagai respons terhadap permintaan pesan upstream dari aplikasi klien.

Tabel 5 Pesan XMPP upstream.

Parameter Penggunaan Deskripsi
from Wajib, string

Parameter ini menetapkan siapa yang mengirim pesan.

Nilainya adalah token pendaftaran aplikasi klien.
category Wajib, string Parameter ini menetapkan nama paket aplikasi dari aplikasi klien yang mengirim pesan.
message_id Wajib, string Parameter ini menetapkan ID unik pesan.
data Opsional, string Parameter ini menetapkan key-value pair payload pesan.

Mengirim pesan ACK

Tabel berikut ini menjelaskan respons ACK yang diharapkan untuk dikirim oleh server aplikasi ke FCM sebagai respons terhadap pesan upstream yang diterima server aplikasi.

Tabel 6 Respons pesan XMPP upstream.

Parameter Penggunaan Deskripsi
to Wajib, string

Parameter ini menetapkan penerima pesan respons.

Nilainya harus berupa token pendaftaran aplikasi klien yang mengirim pesan upstream.
message_id Wajib, string Parameter ini menetapkan untuk pesan mana respons tersebut ditujukan. Nilainya harus berupa nilai message_id dari pesan upstream yang sesuai.
message_type Wajib, string Parameter ini menentukan pesan ack dari server aplikasi ke CCS. Untuk pesan upstream, parameter ini harus selalu disetel ke ack.

Pesan server FCM (XMPP)

Ini adalah pesan yang dikirim dari FCM ke server aplikasi. Berikut adalah jenis pesan utama yang dikirim FCM ke server aplikasi:

  • Kontrol: Pesan buatan CCS ini menunjukkan bahwa tindakan diperlukan dari server aplikasi.

Tabel berikut menjelaskan kolom yang disertakan dalam pesan yang dikirim oleh CCS ke server aplikasi.

Tabel 7 Pesan kontrol FCM (XMPP).

Parameter Penggunaan Deskripsi
Kolom umum
message_type Wajib, string

Parameter ini menentukan jenis pesan: kontrol.

Jika disetel ke control, pesan akan menyertakan control_type untuk menunjukkan jenis pesan kontrol.
control_type Opsional, string

Parameter ini menetapkan jenis pesan kontrol yang dikirim dari FCM.

Saat ini, hanya CONNECTION_DRAINING yang didukung. FCM mengirim pesan kontrol ini sebelum menutup koneksi untuk melakukan load balancing. Ketika koneksi dikosongkan, tidak ada pesan yang diizinkan untuk dikirim ke koneksi tersebut, tetapi pesan yang sudah ada dalam pipeline terus diproses.