Ikuti semua informasi yang diumumkan di Firebase Summit, dan pelajari bagaimana Firebase dapat membantu Anda mempercepat pengembangan aplikasi dan menjalankan aplikasi dengan percaya diri. Pelajari Lebih Lanjut
Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Lingkungan server dan FCM Anda

Sisi server Firebase Cloud Messaging terdiri dari dua komponen:

  • Backend FCM disediakan oleh Google.
  • Server aplikasi Anda atau lingkungan server tepercaya lainnya tempat logika server Anda berjalan, seperti Cloud Functions for Firebase atau lingkungan cloud lain yang dikelola oleh Google.

Server aplikasi atau lingkungan server tepercaya Anda mengirimkan permintaan pesan ke backend FCM, yang kemudian merutekan pesan ke aplikasi klien yang berjalan di perangkat pengguna.

Persyaratan untuk lingkungan server tepercaya

Lingkungan server aplikasi Anda harus memenuhi kriteria berikut:

  • Dapat mengirim permintaan pesan yang diformat dengan benar ke backend FCM.
  • Mampu menangani permintaan dan mengirimkannya kembali menggunakan back-off eksponensial.
  • Mampu menyimpan kredensial otorisasi server dan token pendaftaran klien dengan aman.
  • Untuk protokol XMPP (jika digunakan), server harus dapat menghasilkan ID pesan untuk mengidentifikasi secara unik setiap pesan yang dikirimnya (backend HTTP FCM menghasilkan ID pesan dan mengembalikannya dalam respons). ID pesan XMPP harus unik per ID pengirim.

Memilih opsi server

Anda harus memutuskan cara berinteraksi dengan server FCM: menggunakan Firebase Admin SDK atau protokol mentah. Karena dukungannya di seluruh bahasa pemrograman populer dan metode praktisnya untuk menangani autentikasi dan otorisasi, Firebase Admin SDK adalah metode yang direkomendasikan.

Opsi untuk berinteraksi dengan server FCM mencakup hal berikut:

  • Firebase Admin SDK, yang mendukung Node , Java , Python , C# , dan Go .
  • FCM HTTP v1 API , yang merupakan opsi protokol paling mutakhir, dengan otorisasi yang lebih aman dan kemampuan perpesanan lintas platform yang fleksibel (Firebase Admin SDK didasarkan pada protokol ini dan memberikan semua kelebihan bawaannya). Karena fitur baru biasanya hanya ditambahkan ke API HTTP v1, kami menyarankan penggunaan API ini untuk sebagian besar kasus penggunaan.
  • Protokol HTTP lama . Project baru sangat disarankan untuk mengadopsi FCM v1 HTTP API, bukan protokol lama.
  • Protokol server XMPP lama . Project baru sangat disarankan untuk mengadopsi FCM v1 HTTP API, bukan protokol lama.

Firebase Admin SDK untuk FCM

Admin FCM API menangani autentikasi dengan backend dan memfasilitasi pengiriman pesan dan pengelolaan langganan topik. Dengan Firebase Admin SDK, Anda dapat:

  • Kirim pesan ke perangkat individu
  • Kirim pesan ke topik dan pernyataan kondisi yang cocok dengan satu atau beberapa topik.
  • Berlangganan dan berhenti berlangganan perangkat ke dan dari topik
  • Bangun muatan pesan yang disesuaikan dengan platform target yang berbeda

Admin Node.js SDK menyediakan metode untuk mengirim pesan ke grup perangkat.

Untuk menyiapkan Firebase Admin SDK, lihat Menambahkan Firebase Admin SDK ke Server Anda . Jika Anda sudah memiliki proyek Firebase, mulailah dengan Add the SDK . Selain itu, pastikan untuk mengaktifkan Cloud Messagin API di halaman setelan Cloud Messaging untuk project Anda. Kemudian, setelah Firebase Admin SDK diinstal, Anda dapat mulai menulis logika untuk membuat permintaan pengiriman .

Protokol Server FCM

Saat ini FCM menyediakan protokol server mentah berikut:

Server aplikasi Anda dapat menggunakan protokol ini secara terpisah atau bersama-sama. Karena ini adalah yang paling mutakhir dan paling fleksibel untuk mengirim pesan ke berbagai platform, API HTTP v1 FCM direkomendasikan jika memungkinkan. Jika kebutuhan Anda mencakup perpesanan upstream dari perangkat ke server, Anda harus mengimplementasikan protokol XMPP.

Perpesanan XMPP berbeda dari perpesanan HTTP dengan cara berikut:

  • Pesan upstream/downstream
    • HTTP: Hanya downstream, cloud-to-device.
    • XMPP: Hulu dan hilir (perangkat ke cloud, cloud ke perangkat).
  • Perpesanan (sinkron atau asinkron)
    • HTTP: Sinkron. Server aplikasi mengirim pesan sebagai permintaan HTTP POST dan menunggu tanggapan. Mekanisme ini sinkron dan memblokir pengirim dari mengirim pesan lain hingga respons diterima.
    • XMPP: Asinkron. Server aplikasi mengirim/menerima pesan ke/dari semua perangkat mereka dengan kecepatan jalur penuh melalui koneksi XMPP yang persisten. Server koneksi XMPP mengirimkan pemberitahuan pengakuan atau kegagalan (dalam bentuk pesan XMPP yang disandikan ACK dan NACK JSON khusus) secara asinkron.
  • JSON
    • HTTP: Pesan JSON dikirim sebagai HTTP POST.
    • XMPP: Pesan JSON dienkapsulasi dalam pesan XMPP.
  • Teks Biasa
    • HTTP: Pesan Teks Biasa dikirim sebagai HTTP POST.
    • XMPP: Tidak didukung.
  • Pengiriman hilir multicast ke beberapa token pendaftaran.
    • HTTP: Didukung dalam format pesan JSON.
    • XMPP: Tidak didukung.

Menerapkan protokol server HTTP

Untuk mengirim pesan, server aplikasi mengeluarkan permintaan POST dengan header HTTP dan badan HTTP yang terdiri dari pasangan nilai kunci JSON. Untuk mengetahui detail tentang opsi header dan body, lihat Build App Server Send Requests

Menerapkan protokol server XMPP

Muatan JSON untuk pesan FCM serupa dengan protokol HTTP, dengan pengecualian berikut:

  • Tidak ada dukungan untuk banyak penerima.
  • FCM menambahkan kolom message_id , yang wajib diisi. ID ini secara unik mengidentifikasi pesan dalam koneksi XMPP. ACK atau NACK dari FCM menggunakan message_id untuk mengidentifikasi pesan yang dikirim dari server aplikasi ke FCM. Oleh karena itu, penting agar message_id ini tidak hanya unik (per ID pengirim ), tetapi selalu ada.
  • XMPP menggunakan kunci server untuk mengotorisasi koneksi persisten ke FCM. Lihat Otorisasi Kirim Permintaan untuk informasi lebih lanjut.

Selain pesan FCM reguler, pesan kontrol dikirim, ditunjukkan oleh kolom message_type di objek JSON. Nilainya bisa berupa 'ack' atau 'nack', atau 'control' (lihat format di bawah). Setiap pesan FCM dengan message_type yang tidak diketahui dapat diabaikan oleh server Anda.

Untuk setiap pesan perangkat yang diterima server aplikasi Anda dari FCM, pesan ACK harus dikirim. Tidak perlu mengirim pesan NACK. Jika Anda tidak mengirimkan ACK untuk sebuah pesan, FCM akan mengirimkannya kembali saat berikutnya koneksi XMPP baru dibuat, kecuali pesan tersebut kedaluwarsa terlebih dahulu.

FCM juga mengirimkan ACK atau NACK untuk setiap pesan server-ke-perangkat. Jika Anda tidak menerima keduanya, itu berarti koneksi TCP ditutup di tengah operasi dan server Anda perlu mengirim ulang pesan. Lihat Kontrol Aliran untuk detailnya.

Lihat Referensi Protokol untuk daftar semua parameter pesan.

Format permintaan

Pesan dengan payload — pesan pemberitahuan

Berikut adalah bait XMPP untuk pesan notifikasi:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
     "to":"REGISTRATION_ID",  // "to" replaces "registration_ids"
     "notification": {
        "title": "Portugal vs. Denmark”,
        "body”: "5 to 1”
      },
      "time_to_live":"600"
  }
  </gcm>
</message>

Pesan dengan payload — pesan data

Berikut adalah bait XMPP yang berisi pesan JSON dari server aplikasi ke FCM:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to":"REGISTRATION_ID",  // "to" replaces "registration_ids"
      "message_id":"m-1366082849205" // new required field
      "data":
      {
          "hello":"world",
      }
      "time_to_live":"600",
  }
  </gcm>
</message>

Format respons

Respons FCM dapat memiliki tiga kemungkinan bentuk. Yang pertama adalah pesan 'ack' biasa. Namun jika respons berisi kesalahan, ada 2 bentuk pesan yang berbeda, yang dijelaskan di bawah ini.

pesan ACK

Berikut adalah bait XMPP yang berisi pesan ACK/NACK dari FCM ke server aplikasi:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "from":"REGID",
      "message_id":"m-1366082849205"
      "message_type":"ack"
  }
  </gcm>
</message>

pesan NACK

Kesalahan NACK adalah pesan XMPP biasa di mana pesan status message_type adalah "nack". Pesan NACK berisi:

  • Kode kesalahan NACK.
  • Deskripsi kesalahan NACK.

Di bawah ini adalah beberapa contoh.

Registrasi buruk:

<message>
  <gcm xmlns="google:mobile:data">
  {
    "message_type":"nack",
    "message_id":"msgId1",
    "from":"SomeInvalidRegistrationToken",
    "error":"BAD_REGISTRATION",
    "error_description":"Invalid token on 'to' field: SomeInvalidRegistrationId"
  }
  </gcm>
</message>

JSON tidak valid:

<message>
 <gcm xmlns="google:mobile:data">
 {
   "message_type":"nack",
   "message_id":"msgId1",
   "from":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
   "error":"INVALID_JSON",
   "error_description":"InvalidJson: JSON_TYPE_ERROR : Field \"time_to_live\" must be a JSON java.lang.Number: abc"
 }
 </gcm>
</message>

Kecepatan Pesan Perangkat Terlampaui:

<message id="...">
  <gcm xmlns="google:mobile:data">
  {
    "message_type":"nack",
    "message_id":"msgId1",
    "from":"REGID",
    "error":"DEVICE_MESSAGE_RATE_EXCEEDED",
    "error_description":"Downstream message rate exceeded for this registration id"
  }
  </gcm>
</message>

Lihat Referensi Server untuk daftar lengkap kode kesalahan NACK. Kecuali dinyatakan lain, pesan NACK tidak boleh dicoba lagi. Kode kesalahan NACK yang tidak terduga harus diperlakukan sama dengan INTERNAL_SERVER_ERROR .

Kesalahan bait

Anda juga bisa mendapatkan kesalahan bait dalam kasus tertentu. Kesalahan bait berisi:

  • Kode kesalahan bait.
  • Deskripsi kesalahan bait (teks bebas).

Sebagai contoh:

<message id="3" type="error" to="123456789@fcm.googleapis.com/ABC">
  <gcm xmlns="google:mobile:data">
     {"random": "text"}
  </gcm>
  <error code="400" type="modify">
    <bad-request xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
    <text xmlns="urn:ietf:params:xml:ns:xmpp-stanzas">
      InvalidJson: JSON_PARSING_ERROR : Missing Required Field: message_id\n
    </text>
  </error>
</message>

Kontrol pesan

Secara berkala, FCM perlu menutup koneksi untuk melakukan load balancing. Sebelum menutup koneksi, FCM mengirimkan pesan CONNECTION_DRAINING untuk menunjukkan bahwa koneksi sedang dikosongkan dan akan segera ditutup. "Menguras" mengacu pada mematikan aliran pesan yang masuk ke koneksi, tetapi membiarkan apa pun yang sudah ada di dalam pipa untuk melanjutkan. Saat Anda menerima pesan CONNECTION_DRAINING , Anda harus segera mulai mengirim pesan ke koneksi FCM lain, membuka koneksi baru jika perlu. Namun, Anda harus tetap membuka koneksi asli dan terus menerima pesan yang mungkin datang melalui koneksi (dan ACKing pesan tersebut)—FCM menangani inisiasi penutupan koneksi jika sudah siap.

Pesan CONNECTION_DRAINING terlihat seperti ini:

<message>
  <data:gcm xmlns:data="google:mobile:data">
  {
    "message_type":"control"
    "control_type":"CONNECTION_DRAINING"
  }
  </data:gcm>
</message>

CONNECTION_DRAINING saat ini adalah satu-satunya control_type yang didukung.

Alur kontrol

Setiap pesan yang dikirim ke FCM menerima respons ACK atau NACK. Pesan yang belum menerima salah satu tanggapan ini dianggap tertunda. Jika jumlah pesan tertunda mencapai 100, server aplikasi harus berhenti mengirim pesan baru dan menunggu FCM untuk mengakui beberapa pesan tertunda yang ada seperti yang diilustrasikan pada gambar 1:

Diagram detail alur kontrol antara FCM dan server aplikasi

Gambar 1. Alur pesan/balasan.

Sebaliknya, untuk menghindari kelebihan server aplikasi, FCM berhenti mengirim jika ada terlalu banyak pesan yang tidak diakui. Oleh karena itu, server aplikasi harus melakukan "ACK" pesan upstream, yang diterima dari aplikasi klien melalui FCM, sesegera mungkin untuk mempertahankan aliran pesan masuk yang konstan. Batas pesan tertunda yang disebutkan di atas tidak berlaku untuk ACK ini. Meskipun jumlah pesan tertunda mencapai 100, server aplikasi harus terus mengirimkan ACK untuk pesan yang diterima dari FCM guna menghindari pemblokiran pengiriman pesan upstream baru.

ACK hanya valid dalam konteks satu koneksi. Jika koneksi ditutup sebelum pesan dapat di-ACK, server aplikasi harus menunggu FCM mengirim ulang pesan upstream sebelum melakukan ACK lagi. Demikian pula, semua pesan tertunda yang ACK/NACK-nya belum diterima dari FCM sebelum koneksi ditutup harus dikirim lagi.