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

Lingkungan server Anda dan FCM

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 lainnya 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:

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

Memilih opsi server

Anda harus memutuskan cara berinteraksi dengan server FCM: baik menggunakan Firebase Admin SDK atau protokol mentah. Karena dukungannya di seluruh bahasa pemrograman populer dan metode kemudahannya 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 terbaru, dengan otorisasi yang lebih aman dan kemampuan pengiriman pesan lintas platform yang fleksibel (Firebase Admin SDK didasarkan pada protokol ini dan memberikan semua keunggulan bawaannya). Karena fitur baru biasanya ditambahkan ke HTTP v1 API saja, kami menyarankan untuk menggunakan 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 lawas . Project baru sangat disarankan untuk mengadopsi FCM v1 HTTP API, bukan protokol lama.

SDK Admin Firebase 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 individual
  • 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 pengaturan Cloud Messaging untuk proyek 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 ini:

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, FCM HTTP v1 API direkomendasikan jika memungkinkan. Jika persyaratan Anda mencakup pesan upstream dari perangkat ke server, Anda harus menerapkan protokol XMPP.

Pesan XMPP berbeda dari pesan HTTP dalam hal berikut:

  • Pesan Upstream/Downstream
    • HTTP: Hanya hilir, cloud-to-device.
    • XMPP: Hulu dan hilir (perangkat-ke-awan, awan-ke-perangkat).
  • Perpesanan (sinkron atau asinkron)
    • HTTP: Sinkron. Server aplikasi mengirim pesan sebagai permintaan HTTP POST dan menunggu tanggapan. Mekanisme ini sinkron dan menghalangi pengirim untuk mengirim pesan lain hingga respons diterima.
    • XMPP: Asinkron. Server aplikasi mengirim/menerima pesan ke/dari semua perangkat mereka dengan kecepatan penuh melalui koneksi XMPP yang persisten. Server koneksi XMPP mengirimkan pemberitahuan pengakuan atau kegagalan (dalam bentuk pesan XMPP berkode 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 detail tentang opsi tajuk dan isi, lihat Membangun Permintaan Kirim Server Aplikasi

Menerapkan protokol server XMPP

Payload JSON untuk pesan FCM mirip dengan protokol HTTP, dengan pengecualian berikut:

  • Tidak ada dukungan untuk banyak penerima.
  • FCM menambahkan bidang message_id , yang diperlukan. 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 biasa, pesan kontrol dikirim, ditunjukkan oleh bidang message_type di objek JSON. Nilainya dapat berupa 'ack' atau 'nack', atau 'control' (lihat format di bawah). Pesan FCM apa pun dengan message_type yang tidak dikenal dapat diabaikan oleh server Anda.

Untuk setiap pesan perangkat yang diterima server aplikasi Anda dari FCM, itu perlu mengirim pesan ACK. Tidak perlu mengirim pesan NACK. Jika Anda tidak mengirim ACK untuk sebuah pesan, FCM akan mengirim ulang saat berikutnya koneksi XMPP baru dibuat, kecuali jika 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 muatan — 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 muatan — 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 tanggapan

Respons FCM dapat memiliki tiga kemungkinan bentuk. Yang pertama adalah pesan 'ack' biasa. Tetapi ketika respons mengandung 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.

Pendaftaran 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>

Tingkat Pesan Perangkat Melebihi:

<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 ulang. Kode kesalahan NACK yang tidak terduga harus diperlakukan sama seperti 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 penyeimbangan beban. Sebelum menutup koneksi, FCM mengirimkan pesan CONNECTION_DRAINING untuk menunjukkan bahwa koneksi sedang dikuras dan akan segera ditutup. "Menguras" mengacu pada mematikan aliran pesan yang masuk ke koneksi, tetapi membiarkan apa pun yang sudah ada di saluran untuk melanjutkan. Saat Anda menerima pesan CONNECTION_DRAINING , Anda harus segera mulai mengirim pesan ke koneksi FCM lain, membuka koneksi baru jika perlu. Anda harus, bagaimanapun, menjaga koneksi asli tetap terbuka dan terus menerima pesan yang mungkin datang melalui koneksi (dan ACKing mereka)—FCM menangani memulai koneksi dekat ketika 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 aliran kontrol antara FCM dan server aplikasi

Gambar 1. Aliran pesan/ack.

Sebaliknya, untuk menghindari kelebihan server aplikasi, FCM berhenti mengirim jika ada terlalu banyak pesan yang tidak diakui. Oleh karena itu, server aplikasi harus "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 meng-ACK-nya lagi. Demikian pula, semua pesan tertunda yang ACK/NACK tidak diterima dari FCM sebelum koneksi ditutup harus dikirim lagi.