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
Kode respons error untuk pesan downstream
Sintaksis pesan upstream
Pesan kontrol FCM

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 empat 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. Waktu aktif 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 ke 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, maka 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.
Waktu untuk Aktif 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 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 1 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.
Pengurasan 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

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`.

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

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.

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.