Produk Kasus Penggunaan Harga Dokumen Bantuan
Buka konsol

Mengirim pesan ke grup perangkat di Android

Dengan messaging grup perangkat, Anda dapat menambahkan beberapa perangkat ke satu grup. Metode ini serupa dengan messaging 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. Messaging grup perangkat berbeda dengan messaging topik karena di dalamnya terdapat pengelolaan grup perangkat dari server Anda, bukan langsung di aplikasi Anda.

Anda dapat menggunakan messaging grup perangkat melalui protokol XMPP atau HTTP lama di server aplikasi Anda. 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 mengirimkan pesan ke grup perangkat, Anda harus:

  1. Memperoleh token pendaftaran untuk setiap perangkat yang ingin Anda tambahkan ke grup.

  2. 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. Nama 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"
}

Mengelola grup perangkat di aplikasi klien Android

Mengelola grup perangkat pada klien dapat bermanfaat jika server tidak tersedia. Untuk membuat grup perangkat pada klien, perangkat harus memiliki minimal satu akun Google. Perlu diperhatikan bahwa proses pembuatan kunci notifikasi pada klien sangat berbeda dari proses sisi server seperti yang dijelaskan di atas.

Untuk membuat grup perangkat pada klien:

Mendapatkan ID Klien

  1. Buka project Anda di Google Developers Console.
  2. Dari menu di kiri atas, pilih API & Layanan, lalu Kredensial.
  3. Klik Kredensial baru, lalu pilih ID Klien OAuth.
  4. Pada dialog Buat ID Klien, pilih Aplikasi Web sebagai jenis aplikasi, lalu klik Buat.
  5. Salin nilai yang ditampilkan di ID Klien. ID Klien ini mewakili "lingkup" akun Google yang akan Anda gunakan untuk membuat idToken.

Validasi akun Google pada perangkat

Setelah Anda memperoleh ID klien dari Google Developers Console, periksa keberadaan akun Google pada perangkat.

Java

// This snippet takes the simple approach of using the first returned Google account,
// but you can pick any Google account on the device.
public String getAccount() {
    // This call requires the Android GET_ACCOUNTS permission
    Account[] accounts = AccountManager.get(this /* activity */).
            getAccountsByType("com.google");
    if (accounts.length == 0) {
        return null;
    }
    return accounts[0].name;
}
MainActivity.java

Kotlin

// This snippet takes the simple approach of using the first returned Google account,
// but you can pick any Google account on the device.
@SuppressLint("MissingPermission")
fun getAccount(): String {
    // This call requires the Android GET_ACCOUNTS permission
    val accounts = AccountManager.get(this /* activity */).getAccountsByType("com.google")
    return if (accounts.isEmpty()) {
        ""
    } else accounts[0].name
}
MainActivity.kt

Dapatkan token autentikasi

Berikutnya, dapatkan token autentikasi (idToken) menggunakan class GoogleAuthUtil. Misalnya:

Java

String accountName = getAccount();

// Initialize the scope using the client ID you got from the Console.
final String scope = "audience:server:client_id:"
        + "1262xxx48712-9qs6n32447mcj9dirtnkyrejt82saa52.apps.googleusercontent.com";

String idToken = null;
try {
    idToken = GoogleAuthUtil.getToken(this, accountName, scope);
} catch (Exception e) {
    Log.w(TAG, "Exception while getting idToken: " + e);
}
MainActivity.java

Kotlin

val accountName = getAccount()

// Initialize the scope using the client ID you got from the Console.
val scope = "audience:server:client_id:" +
        "1262xxx48712-9qs6n32447mcj9dirtnkyrejt82saa52.apps.googleusercontent.com"

var idToken: String? = null
try {
    idToken = GoogleAuthUtil.getToken(this, accountName, scope)
} catch (e: Exception) {
    Log.w(TAG, "Exception while getting idToken: $e")
}

MainActivity.kt

Menambahkan atau menghapus perangkat dari grup

Buat permintaan HTTP POST ke https://fcm.googleapis.com/fcm/googlenotification untuk menambahkan/menghapus token pendaftaran ke/dari grup. Header permintaan harus memiliki project_id yang ditetapkan ke ID pengirim dan Content-Type yang ditetapkan ke JSON.

Menambahkan perangkat ke grup

Operasi penambahan membutuhkan kunci berikut: operation yang disetel ke add, id_token yang disetel ke idToken sebagaimana diperoleh di atas, notification_key_name, dan registration_ids. Variabel userEmail, seperti yang ditampilkan di bawah, dapat berasal dari nilai accounts[0].name. Klien diberi wewenang untuk mengelola grup yang dipetakan ke email/akun ini saja.

Java

public String addToGroup(
        String senderId, String userEmail, String registrationId, String idToken)
        throws IOException, JSONException {
    URL url = new URL("https://fcm.googleapis.com/fcm/googlenotification");
    HttpURLConnection con = (HttpURLConnection) url.openConnection();
    con.setDoOutput(true);

    // HTTP request header
    con.setRequestProperty("project_id", senderId);
    con.setRequestProperty("Content-Type", "application/json");
    con.setRequestProperty("Accept", "application/json");
    con.setRequestMethod("POST");
    con.connect();

    // HTTP request
    JSONObject data = new JSONObject();
    data.put("operation", "add");
    data.put("notification_key_name", userEmail);
    data.put("registration_ids", new JSONArray(Arrays.asList(registrationId)));
    data.put("id_token", idToken);

    OutputStream os = con.getOutputStream();
    os.write(data.toString().getBytes("UTF-8"));
    os.close();

    // Read the response into a string
    InputStream is = con.getInputStream();
    String responseString = new Scanner(is, "UTF-8").useDelimiter("\\A").next();
    is.close();

    // Parse the JSON string and return the notification key
    JSONObject response = new JSONObject(responseString);
    return response.getString("notification_key");
}
MainActivity.java

Kotlin

@Throws(IOException::class, JSONException::class)
fun addToGroup(
    senderId: String,
    userEmail: String,
    registrationId: String,
    idToken: String
): String {
    val url = URL("https://fcm.googleapis.com/fcm/googlenotification")
    val con = url.openConnection() as HttpURLConnection
    con.doOutput = true

    // HTTP request header
    con.setRequestProperty("project_id", senderId)
    con.setRequestProperty("Content-Type", "application/json")
    con.setRequestProperty("Accept", "application/json")
    con.requestMethod = "POST"
    con.connect()

    // HTTP request
    val data = JSONObject()
    data.put("operation", "add")
    data.put("notification_key_name", userEmail)
    data.put("registration_ids", JSONArray(arrayListOf(registrationId)))
    data.put("id_token", idToken)

    val os = con.outputStream
    os.write(data.toString().toByteArray(charset("UTF-8")))
    os.close()

    // Read the response into a string
    val `is` = con.inputStream
    val responseString = Scanner(`is`, "UTF-8").useDelimiter("\\A").next()
    `is`.close()

    // Parse the JSON string and return the notification key
    val response = JSONObject(responseString)
    return response.getString("notification_key")
}
MainActivity.kt

Operasi yang berhasil akan menampilkan notification_key. Simpan notification_key dan notification_key_name yang sesuai untuk digunakan pada operasi berikutnya.

Menghapus dari grup

Operasi penghapusan membutuhkan kunci berikut: operation yang ditetapkan ke remove, id_token yang ditetapkan ke idToken sebagaimana diperoleh di atas, notification_key_name, dan registration_ids.

Java

// HTTP request
JSONObject data = new JSONObject();
data.put("operation", "remove");
data.put("notification_key_name", userEmail);
data.put("registration_ids", new JSONArray(Arrays.asList(registrationId)));
data.put("id_token", idToken);
MainActivity.java

Kotlin

// HTTP request
val data = JSONObject()
data.put("operation", "remove")
data.put("notification_key_name", userEmail)
data.put("registration_ids", JSONArray(arrayListOf(registrationId)))
data.put("id_token", idToken)
MainActivity.kt

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, baca informasi referensi untuk protokol server koneksi pilihan Anda, HTTP atau XMPP.

Mengirim pesan upstream ke grup perangkat

Aplikasi klien dapat mengirimkan pesan upstream ke grup perangkat dengan cara menargetkan pesan ke kunci notifikasi yang sesuai di kolom to.

Panggilan berikut ke FCM akan mengirimkan pesan upstream ke kunci notifikasi. Objek tersebut terdiri dari key-value pair.

Java 

String to = "a_unique_key"; // the notification key
AtomicInteger msgId = new AtomicInteger();
FirebaseMessaging.getInstance().send(new RemoteMessage.Builder(to)
        .setMessageId(String.valueOf(msgId.get()))
        .addData("hello", "world")
        .build());
MainActivity.java

Kotlin 

val to = "a_unique_key" // the notification key
val msgId = AtomicInteger()
FirebaseMessaging.getInstance().send(RemoteMessage.Builder(to)
        .setMessageId(msgId.get().toString())
        .addData("hello", "world")
        .build())
MainActivity.kt