Buka konsol

Protokol XMPP Firebase Cloud Messaging

Dokumen ini menyediakan referensi untuk sintaks 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:

Sintaks pesan downstream

Bagian ini memberikan sintaks 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.

Nilai 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 condition yang menentukan target pesan.

Condition yang didukung: Topik, yang diformat sebagai "'yourTopic' dalam topik". Nilai ini peka terhadap huruf besar dan huruf kecil.

Operator yang didukung: &&, ||. Maksimum 2 operator per pesan topik yang didukung.

Opsi
message_id Diperlukan, 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. Hal ini dimaksudkan untuk mencegah mengirim terlalu banyak pesan yang sama ketika perangkat kembali online atau kembali aktif.

Tidak ada jaminan untuk urutan pesan yang akan dikirim.

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

priority Opsional, string

Menetapkan prioritas pesan. Nilai yang valid adalah "normal" dan "tinggi." Pada iOS, ini sama dengan prioritas APN 5 dan 10.

Secara default, pesan notifikasi dikirim dengan prioritas tinggi dan pesan data dikirim dengan prioritas normal. Prioritas normal mengoptimalkan pemakaian baterai aplikasi klien dan harus 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

Pada iOS, gunakan kolom ini untuk mewakili content-available dalam payload APN. Jika notifikasi atau pesan dikirim dan parameter ini disetel ke true, aplikasi klien yang tidak aktif akan diaktifkan, dan pesan akan dikirim melalui APN sebagai notifikasi diam dan tidak melalui server koneksi 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. Pada Android, secara default pesan data akan mengaktifkan aplikasi. Pada Chrome, untuk saat ini belum didukung.

mutable_content Opsional, boolean JSON

Saat ini hanya untuk perangkat iOS 10+. Di iOS, gunakan kolom ini untuk mewakili mutable-content di dalam payload APNS. 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 Menyetel masa aktif pesan.

delivery_receipt_
requested
Opsional, boolean

Parameter ini memungkinkan server aplikasi meminta konfirmasi penyampaian pesan.

Jika parameter ini disetel ke true, FCM akan mengirim tanda terima pengiriman ketika perangkat mengonfirmasi bahwa pesan telah diterima.

Catatan: parameter ini tidak didukung untuk pesan yang dikirim ke perangkat iOS. Nilai defaultnya adalah false.

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 pada payload pesan.

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

Pada iOS, jika pesan dikirim melalui APN, pesan tersebut mewakili kolom data khusus. Jika pesan dikirim melalui FCM, pesan tersebut diwakili sebagai kamus nilai kunci di AppDelegate application:didReceiveRemoteNotification:.

Pada Android, ini akan menghasilkan tambahan intent yang disebut score dengan nilai string 3x1.

Kunci tidak boleh berupa kata yang telah digunakan ("from" atau kata apa pun yang dimulai dengan "google" atau "gcm"). Jangan menggunakan kata apa pun yang ditentukan 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 iOS, pesan tersebut akan dikirim melalui APN. Jika tidak, pesan akan dikirim melalui server koneksi FCM.

Dukungan payload notifikasi

Tabel di bawah ini mencantumkan kunci yang telah ditetapkan sebelumnya yang tersedia untuk membuat pesan notifikasi untuk iOS dan Android.

Tabel 2a. iOS — kunci untuk pesan notifikasi

Parameter Penggunaan Deskripsi
title Opsional, string

Judul notifikasi.

Kolom ini tidak ditampilkan di ponsel dan tablet iOS.

body Opsional, string

Teks isi notifikasi.

sound Opsional, string, atau Kamus

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.

Untuk notifikasi penting, gunakan kamus yang berisi informasi suara untuk pemberitahuan penting. Lihat Library Developer iOS untuk kunci yang diperlukan. Untuk notifikasi reguler, gunakan string suara sebagai gantinya.

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.

Sesuai dengan category dalam payload APN.

subtitle Opsional, string

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

Sesuai dengan loc-key di 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.

Sesuai 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 ke string judul di dalam resource string aplikasi yang akan digunakan untuk melokalkan teks judul ke bahasa pengguna saat ini.

Sesuai dengan title-loc-key di 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.

Sesuai 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 myicon yang dapat digambar. 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 disertakan dalam aplikasi. File suara harus berada di /res/raw/.

tag Opsional, string

Pengenal 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 ke 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 ke 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 nilai 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 disetel ketika message_type adalah nack. Lihat tabel 4 untuk detailnya.
error_description Opsional, string Parameter ini menyediakan informasi deskriptif untuk error. Ini disetel 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 Pastikan permintaan berisi token pendaftaran (dalam registration_id di pesan teks biasa, atau di kolom to atau registration_ids di JSON).
Token Pendaftaran Tidak Valid BAD_REGISTRATION Periksa format token pendaftaran yang Anda teruskan ke server. Pastikan format tersebut cocok dengan token pendaftaran yang diterima aplikasi klien ketika mendaftar dengan FCM. Jangan memotong atau menambahkan 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 token pendaftaran masa berlakunya habis (misalnya, Google mungkin memutuskan untuk memperbarui token pendaftaran, atau token APN sudah tidak berlaku untuk perangkat iOS).
  • Jika aplikasi klien diupdate tetapi versi yang baru belum dikonfigurasi untuk menerima pesan.
Untuk semua kasus tersebut, hapus token pendaftaran ini 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, maka 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 benar diteruskan).
Ukuran 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 nilai.
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 (seperti collapse_key) juga digunakan oleh FCM tetapi diizinkan di payload, yang dalam hal ini nilai payload diganti dengan 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 lagi. Lihat tabel 6 untuk detailnya.
Waktu tunggu SERVICE_UNAVAILABLE

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

  • Mengimplementasikan backoff eksponensial dalam mekanisme percobaan ulang Anda. (mis. jika Anda menunggu 1 detik sebelum percobaan ulang pertama, tunggulah setidaknya 2 detik sebelum percobaan ulang berikutnya, kemudian 4 detik, dan seterusnya). Jika Anda mengirim beberapa pesan, tunda setiap pesan secara independen dengan jumlah acak tambahan agar tidak mengeluarkan permintaan baru untuk semua pesan secara bersamaan.
  • Penundaan percobaan ulang awal harus diatur ke 1 detik.

Catatan: Pengirim yang menyebabkan masalah berisiko dimasukkan ke daftar hitam.

Error pada 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).
Jumlah Pesan Perangkat Terlampaui DEVICE_MESSAGE_RATE
_EXCEEDED
Jumlah pesan untuk perangkat tertentu terlalu tinggi. Kurangi jumlah pesan yang dikirim ke perangkat ini, dan jangan langsung mencoba mengirimkan pesan lagi ke perangkat ini.
Jumlah Pesan Topik Terlampaui TOPICS_MESSAGE_RATE
_EXCEEDED
Jumlah pesan untuk pelanggan pada topik tertentu terlalu tinggi. Kurangi jumlah pesan yang dikirim untuk topik ini, dan jangan langsung mencoba mengirimkan pesan lagi.
Pengurasan Koneksi CONNECTION_DRAINING Pesan tidak bisa diproses karena koneksi terkuras. 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.

Sintaks 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 menjelaskan 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 pada 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:

  • Tanda Terima Pengiriman: Jika server aplikasi menyertakan delivery_receipt_requested dalam pesan downstream, FCM akan mengirim tanda terima pengiriman ketika menerima konfirmasi bahwa perangkat telah menerima pesan tersebut.
  • 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 menetapkan jenis pesan: baik tanda terima pengiriman maupun kontrol.

Jika disetel ke receipt, maka pesan akan menyertakan kolom from, message_id, category, dan data untuk memberikan informasi tambahan.

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

Khusus tanda terima pengiriman
from Wajib, string Parameter ini disetel ke gcm.googleapis.com yang menunjukkan bahwa pesan tersebut dikirim dari FCM.
message_id Wajib, string Parameter ini menetapkan ID pesan asli yang akan menerima tanda terima, yang diawali dengan dr2: untuk menunjukkan bahwa pesan tersebut adalah tanda terima pengiriman. Server aplikasi harus mengirim pesan ack dengan ID pesan ini untuk mengonfirmasi bahwa tanda terima pengiriman telah diterima. Lihat tabel 6 untuk mengetahui format pesan ack.
category Opsional, string Parameter ini menetapkan nama paket aplikasi dari aplikasi klien yang menerima pesan yang dilaporkan oleh tanda terima pengiriman ini. Ini tersedia jika message_type adalah receipt.
data Opsional, string Parameter ini menetapkan key-value pair untuk pesan tanda terima pengiriman. Ini tersedia jika jenis pesan adalah receipt.
  • message_status: Parameter ini menetapkan status pesan tanda terima. Parameter ini disetel ke MESSAGE_SENT_TO_DEVICE untuk menunjukkan bahwa perangkat telah mengonfirmasi penerimaan pesan asli.
  • original_message_id: Parameter ini menetapkan ID pesan asli yang dikirim oleh server aplikasi ke aplikasi klien.
  • device_registration_id: Parameter ini menetapkan token pendaftaran aplikasi klien tujuan pesan asli dikirim.
Khusus 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 terkuras, tidak ada pesan yang diizinkan untuk dikirim ke koneksi, tetapi pesan yang sudah ada dalam pipeline terus diproses.