Mengirim pesan ke grup perangkat di Android

Dengan pesan grup perangkat, Anda dapat menambahkan beberapa perangkat ke satu grup. Kemampuan ini mirip dengan pengiriman pesan menurut topik, tetapi yang ini mencakup autentikasi untuk memastikan bahwa keanggotaan grup hanya dikelola oleh server Anda. Misalnya, jika Anda ingin mengirim berbagai pesan ke model ponsel berbeda, server Anda dapat menambahkan/menghapus pendaftaran ke grup yang sesuai dan mengirim pesan yang sesuai ke setiap grup. Pengiriman pesan ke grup perangkat berbeda dari pengiriman pesan menurut topik karena grup perangkat dikelola dari server Anda, bukan langsung di aplikasi.

Anda dapat menggunakan pengiriman pesan ke grup perangkat melalui protokol XMPP atau HTTP lama pada server aplikasi. Firebase Admin SDK untuk Node.js yang berbasis protokol lama juga menyediakan kemampuan pengiriman pesan ke grup perangkat. Jumlah anggota maksimum yang diizinkan untuk kunci notifikasi adalah 20.

Mengelola grup perangkat

Sebelum mengirim pesan ke grup perangkat, Anda harus:

Memperoleh token pendaftaran untuk setiap perangkat yang ingin Anda tambahkan ke grup.
Membuat notification_key, yang mengidentifikasi grup perangkat dengan memetakan grup tertentu (biasanya pengguna) ke semua token pendaftaran terkait milik grup. Anda dapat membuat kunci notifikasi pada server aplikasi.

Pengelolaan dasar grup perangkat — membuat dan menghapus grup, serta menambahkan atau menghapus perangkat — dilakukan melalui server aplikasi. Baca bagian referensi protokol HTTP lama untuk mengetahui daftar kunci yang didukung.

Mengelola grup perangkat di server aplikasi

Membuat grup perangkat

Untuk membuat grup perangkat, kirim permintaan POST yang memberikan nama untuk grup tersebut, dan daftar token pendaftaran untuk perangkat tersebut. FCM menampilkan notification_key baru yang mewakili grup perangkat.

Permintaan POST HTTP

Kirim permintaan seperti berikut ini ke https://fcm.googleapis.com/fcm/notification:

https://fcm.googleapis.com/fcm/notification
Content-Type:application/json
Authorization:key=API_KEY
project_id:SENDER_ID

{
   "operation": "create",
   "notification_key_name": "appUser-Chris",
   "registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
                        "cR1rjyj4_Kc:APA91bGusqbypSuMdsh7jSNrW4nzsM...",
                        ... ]

notification_key_name adalah nama atau ID (misalnya, dapat berupa nama pengguna) yang unik untuk suatu grup. notification_key_name dan notification_key bersifat unik untuk grup token pendaftaran. notification_key_name harus bersifat unik untuk setiap aplikasi klien jika Anda memiliki beberapa aplikasi klien untuk ID pengirim yang sama. Hal ini untuk memastikan bahwa pesan hanya disampaikan ke aplikasi sasaran yang dimaksud.

Format respons

Permintaan yang berhasil akan menampilkan notification_key seperti berikut:

{
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}

Simpan notification_key dan notification_key_name yang sesuai untuk digunakan dalam operasi berikutnya.

Mengambil kunci notifikasi

Jika perlu mengambil kunci notifikasi yang ada, gunakan notification_key_name dalam permintaan GET seperti yang ditunjukkan berikut ini:

https://fcm.googleapis.com/fcm/notification?notification_key_name=appUser-Chris
Content-Type:application/json
Authorization:key=API_KEY
project_id:SENDER_ID
{}

Pada setiap permintaan GET untuk mendapatkan nama kunci notifikasi tertentu, server akan menampilkan string berenkode unik. Meskipun mungkin tampak seperti kunci yang berbeda, setiap string sebenarnya merupakan nilai `notification_key` yang valid.

Menambahkan dan menghapus perangkat dari grup perangkat

Untuk menambahkan atau menghapus perangkat dari grup yang ada, kirim permintaan POST dengan menyetel parameter operation ke add atau remove, dan berikan token pendaftaran untuk penambahan atau penghapusan.

Permintaan POST HTTP

Misalnya, untuk menambahkan perangkat dengan token pendaftaran bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1... ke appUser-Chris, kirim permintaan ini:

{
   "operation": "add",
   "notification_key_name": "appUser-Chris",
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
   "registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."]
}

Format respons

Permintaan yang berhasil untuk menambahkan atau menghapus perangkat akan menampilkan notification_key seperti berikut:

{
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}

Mengirim pesan downstream ke grup perangkat

Mengirim pesan ke grup perangkat sangat mirip dengan mengirim pesan ke satu perangkat. Setel parameter to ke kunci notifikasi unik untuk grup perangkat. Baca bagian Jenis pesan untuk mengetahui detail tentang dukungan payload. Contoh di halaman ini menunjukkan cara mengirimkan pesan data ke grup perangkat pada protokol HTTP dan XMPP.

Permintaan POST HTTP Grup Perangkat

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{
  "to": "aUniqueKey",
  "data": {
    "hello": "This is a Firebase Cloud Messaging Device Group Message!",
   }
}

Respons HTTP Grup Perangkat

Berikut ini contoh "berhasil" — notification_key memiliki 2 token pendaftaran yang terkait dengannya dan pesan berhasil dikirim ke keduanya:

{
  "success": 2,
  "failure": 0
}

Berikut ini contoh "berhasil sebagian" — notification_key memiliki 3 token pendaftaran yang terkait dengannya. Pesan hanya berhasil dikirim ke 1 token pendaftaran. Pesan respons mencantumkan token pendaftaran (registration_ids) yang gagal menerima pesan:

{
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

Jika pesan gagal dikirim ke satu atau beberapa token pendaftaran yang terkait dengan notification_key, server aplikasi harus mencoba lagi dengan backoff di antara percobaan ulang.

Jika server mencoba mengirim pesan ke grup perangkat yang tidak memiliki anggota, responsnya akan terlihat seperti berikut, dengan 0 keberhasilan dan 0 kegagalan:

{
  "success": 0,
  "failure": 0
}

Pesan XMPP Grup Perangkat

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to": "aUniqueKey",
      "message_id": "m-1366082849205" ,
      "data": {
          "hello":"This is a Firebase Cloud Messaging Device Group Message!"
      }
  }
  </gcm>
</message>

Respons XMPP Grup Perangkat

Jika pesan berhasil dikirim ke salah satu perangkat dalam grup, server koneksi XMPP akan merespons dengan ACK. Jika semua pesan gagal dikirim ke semua perangkat dalam grup, server koneksi XMPP akan merespons dengan NACK.

Berikut ini contoh "berhasil" — notification_key memiliki 3 token pendaftaran yang terkait dengannya dan pesan berhasil dikirim ke ketiganya:

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success": 3,
  "failure": 0,
  "message_id": "m-1366082849205"
}

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

Jika server koneksi FCM gagal mengirim ke semua perangkat dalam grup, server aplikasi akan menerima respons NACK.

Untuk mengetahui daftar lengkap opsi pesan, lihat informasi referensi untuk protokol server koneksi pilihan Anda, HTTP atau XMPP.