Dengan pengiriman pesan grup perangkat, Anda dapat menambahkan beberapa perangkat ke satu grup. Metode ini serupa dengan pengiriman pesan topik, tetapi mencakup autentikasi untuk memastikan bahwa keanggotaan grup hanya dikelola oleh server Anda. Misalnya, jika Anda ingin mengirim pesan berbeda ke model ponsel berbeda, server Anda dapat menambahkan/menghapus pendaftaran ke grup yang sesuai dan mengirim pesan yang sesuai ke setiap grup. Pengiriman pesan grup perangkat berbeda dengan pengiriman pesan topik karena di dalamnya terdapat pengelolaan grup perangkat dari server Anda, bukan langsung di aplikasi Anda.
Anda dapat menggunakan pengiriman pesan grup perangkat melalui protokol XMPP atau HTTP lama pada server aplikasi. Firebase Admin SDK untuk Node.js berdasarkan pada protokol lama juga menyediakan kemampuan pengiriman pesan 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 cara memetakan grup tertentu (biasanya pengguna) ke semua token pendaftaran terkait milik grup tersebut. Anda dapat membuat kunci notifikasi di server aplikasi atau di aplikasi klien Android.
Pengelolaan dasar grup perangkat — membuat dan menghapus grup, serta menambahkan atau menghapus perangkat — biasanya dilakukan melalui server aplikasi. Baca bagian referensi protokol HTTP lama untuk mengetahui daftar kunci yang didukung.
Secara opsional, aplikasi klien Android dapat mengelola grup perangkat dari sisi klien.
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 akan menampilkan notification_key
baru yang mewakili grup perangkat tersebut.
Permintaan HTTP POST
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": ["4", "8", "15", "16", "23", "42"] }
notification_key_name
adalah nama atau ID (misalnya, dapat berupa nama pengguna) yang unik untuk grup tertentu. notification_key_name
dan notification_key
bersifat unik untuk grup token pendaftaran. notification_key_name
harus unik untuk setiap aplikasi klien jika Anda memiliki beberapa aplikasi klien untuk ID pengirim yang sama. Hal ini untuk memastikan bahwa pesan hanya dikirim ke aplikasi target yang dimaksud.
Format respons
Permintaan yang berhasil akan menampilkan notification_key
seperti berikut ini:
{ "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ" }
Simpan notification_key
dan notification_key_name
yang sesuai untuk digunakan dalam operasi berikutnya.
Mengambil kunci notifikasi
Jika Anda harus mengambil kunci notifikasi yang ada, gunakan notification_key_name
dalam permintaan GET seperti 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 nama kunci notifikasi tertentu, server akan menampilkan string berenkode unik. Meskipun setiap string mungkin tampak sebagai kunci yang berbeda, sebenarnya ini adalah 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 HTTP POST
Misalnya, untuk menambahkan perangkat yang memiliki ID pendaftaran 51 ke appUser-Chris, Anda akan mengirimkan permintaan ini:
{
"operation": "add",
"notification_key_name": "appUser-Chris",
"notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
"registration_ids": ["51"]
}
Format respons
Permintaan yang berhasil menambahkan atau menghapus perangkat akan menampilkan notification_key
seperti berikut ini:
{ "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ" }
Mengirim pesan downstream ke grup perangkat
Mengirim pesan ke grup perangkat sangat mirip dengan pengiriman pesan ke suatu perangkat. Tetapkan parameter to
ke kunci notifikasi unik untuk grup perangkat tersebut. Baca bagian Jenis pesan untuk mengetahui informasi tentang dukungan payload. Contoh di halaman ini menunjukkan cara mengirimkan pesan data ke grup perangkat pada protokol HTTP dan XMPP.
Permintaan HTTP POST 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 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
, maka 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" }
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 yang gagal menerima pesan:
{ "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.
Mengirim pesan upstream ke grup perangkat
Untuk mengirim pesan upstream ke grup perangkat di iOS, aplikasi klien iOS perlu mengimplementasikan FIRMessaging.sendMessage:
(void)sendMessage:(nonnull NSDictionary *)message to:(nonnull NSString *)receiver withMessageID:(nonnull NSString *)messageID timeToLive:(int64_t)ttl;