Membuat permintaan kirim server aplikasi

Dengan protokol server aplikasi Firebase Admin SDK atau FCM, Anda dapat membuat permintaan pesan dan mengirimkannya ke jenis target berikut:

  • Nama topik
  • Condition
  • Token pendaftaran perangkat
  • Nama grup perangkat (protokol lama dan Firebase Admin SDK hanya untuk Node.js)

Anda dapat mengirim pesan dengan payload notifikasi yang terdiri atas kolom bawaan, payload data untuk kolom yang ditentukan sendiri oleh pengguna, atau pesan yang berisi kedua jenis payload. Lihat Jenis pesan untuk informasi selengkapnya.

Contoh di halaman ini menunjukkan cara mengirim pesan notifikasi menggunakan Firebase Admin SDK (yang memiliki dukungan untuk Node, Java, Python, C #, dan Go) dan protokol HTTP v1. Ada juga panduan untuk mengirim pesan melalui protokol HTTP dan XMPP versi lama.

Mengirim pesan ke perangkat tertentu

Untuk mengirim ke satu perangkat tertentu, berikan token pendaftaran perangkat seperti yang ditunjukkan. Lihat informasi penyiapan klien untuk platform Anda guna mempelajari lebih jauh tentang token pendaftaran.

Node.js

// This registration token comes from the client FCM SDKs.
var registrationToken = 'YOUR_REGISTRATION_TOKEN';

var message = {
  data: {
    score: '850',
    time: '2:45'
  },
  token: registrationToken
};

// Send a message to the device corresponding to the provided
// registration token.
admin.messaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

// This registration token comes from the client FCM SDKs.
String registrationToken = "YOUR_REGISTRATION_TOKEN";

// See documentation on defining a message payload.
Message message = Message.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .setToken(registrationToken)
    .build();

// Send a message to the device corresponding to the provided
// registration token.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);

Python

# This registration token comes from the client FCM SDKs.
registration_token = 'YOUR_REGISTRATION_TOKEN'

# See documentation on defining a message payload.
message = messaging.Message(
    data={
        'score': '850',
        'time': '2:45',
    },
    token=registration_token,
)

# Send a message to the device corresponding to the provided
# registration token.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)

Go

// Obtain a messaging.Client from the App.
ctx := context.Background()
client, err := app.Messaging(ctx)
if err != nil {
	log.Fatalf("error getting Messaging client: %v\n", err)
}

// This registration token comes from the client FCM SDKs.
registrationToken := "YOUR_REGISTRATION_TOKEN"

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Token: registrationToken,
}

// Send a message to the device corresponding to the provided
// registration token.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)

C#

// This registration token comes from the client FCM SDKs.
var registrationToken = "YOUR_REGISTRATION_TOKEN";

// See documentation on defining a message payload.
var message = new Message()
{
    Data = new Dictionary<string, string>()
    {
        { "score", "850" },
        { "time", "2:45" },
    },
    Token = registrationToken,
};

// Send a message to the device corresponding to the provided
// registration token.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{
  "message":{
    "token" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification" : {
      "body" : "This is an FCM notification message!",
      "title" : "FCM Message",
      }
   }
}

Perintah cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
  "notification": {
    "title": "FCM Message",
    "body": "This is an FCM Message",
  },
  "token": "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  }
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

Jika berhasil, setiap metode pengiriman mengembalikan ID pesan. Firebase Admin SDK mengembalikan string ID dalam format projects/{project_id}/messages/{message_id}. Respons protokol HTTP adalah kunci JSON tunggal:

    {
      "name": "projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
    }

Mengirim pesan ke beberapa perangkat

Admin FCM API untuk Node dan Java memungkinkan Anda untuk mengirim pesan multicast ke daftar token pendaftaran perangkat. Anda dapat menentukan hingga 100 token pendaftaran perangkat per pemanggilan.

Node.js

// Create a list containing up to 100 registration tokens.
// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
  'YOUR_REGISTRATION_TOKEN_1',
  // …
  'YOUR_REGISTRATION_TOKEN_N',
];

const message = {
  data: {score: '850', time: '2:45'},
  tokens: registrationTokens,
}

admin.messaging().sendMulticast(message)
  .then((response) => {
    console.log(response.successCount + ' messages were sent successfully');

Java

// Create a list containing up to 100 registration tokens.
// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n"
);

MulticastMessage message = MulticastMessage.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .addAllTokens(registrationTokens)
    .build();
BatchResponse response = FirebaseMessaging.getInstance().sendMulticast(message);
// See the BatchResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " messages were sent successfully");

Pada prinsipnya, operasi ini menggunakan API sendAll(), seperti yang ditunjukkan pada contoh di bawah ini. Nilai yang ditampilkan adalah BatchResponse yang daftar tanggapannya sesuai dengan urutan token input. Ini berguna ketika Anda ingin memeriksa token mana yang menghasilkan error.

Node.js

// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
  'YOUR_REGISTRATION_TOKEN_1',
  // …
  'YOUR_REGISTRATION_TOKEN_N',
];

const message = {
  data: {score: '850', time: '2:45'},
  tokens: registrationTokens,
}

admin.messaging().sendMulticast(message)
  .then((response) => {
    if (response.failureCount > 0) {
      const failedTokens = [];
      response.responses.forEach((resp, idx) => {
        if (!resp.success) {
          failedTokens.push(registrationTokens[idx]);
        }
      });
      console.log('List of tokens that caused failures: ' + failedTokens);
    }
  });

Java

// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n"
);

MulticastMessage message = MulticastMessage.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .addAllTokens(registrationTokens)
    .build();
BatchResponse response = FirebaseMessaging.getInstance().sendMulticast(message);
if (response.getFailureCount() > 0) {
  List<SendResponse> responses = response.getResponses();
  List<String> failedTokens = new ArrayList<>();
  for (int i = 0; i < responses.size(); i++) {
    if (!responses.get(i).isSuccessful()) {
      // The order of responses corresponds to the order of the registration tokens.
      failedTokens.add(registrationTokens.get(i));
    }
  }

  System.out.println("List of tokens that caused failures: " + failedTokens);
}

Mengirim pesan ke topik

Untuk mengirim pesan ke topik, tentukan nama topik yang diinginkan dalam permintaan kirim:

Node.js

// The topic name can be optionally prefixed with "/topics/".
var topic = 'highScores';

var message = {
  data: {
    score: '850',
    time: '2:45'
  },
  topic: topic
};

// Send a message to devices subscribed to the provided topic.
admin.messaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

// The topic name can be optionally prefixed with "/topics/".
String topic = "highScores";

// See documentation on defining a message payload.
Message message = Message.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .setTopic(topic)
    .build();

// Send a message to the devices subscribed to the provided topic.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);

Python

# The topic name can be optionally prefixed with "/topics/".
topic = 'highScores'

# See documentation on defining a message payload.
message = messaging.Message(
    data={
        'score': '850',
        'time': '2:45',
    },
    topic=topic,
)

# Send a message to the devices subscribed to the provided topic.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)

Go

// The topic name can be optionally prefixed with "/topics/".
topic := "highScores"

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Topic: topic,
}

// Send a message to the devices subscribed to the provided topic.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)

C#

// The topic name can be optionally prefixed with "/topics/".
var topic = "highScores";

// See documentation on defining a message payload.
var message = new Message()
{
    Data = new Dictionary<string, string>()
    {
        { "score", "850" },
        { "time", "2:45" },
    },
    Topic = topic,
};

// Send a message to the devices subscribed to the provided topic.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
    "topic" : "foo-bar",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message"
      }
   }
}

Perintah cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "message": {
    "topic" : "foo-bar",
    "notification": {
      "body": "This is a Firebase Cloud Messaging Topic Message!",
      "title": "FCM Message"
    }
  }
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Untuk mengirim pesan ke kombinasi topik, tentukan kondisi, yang merupakan ekspresi boolean yang menentukan topik target. Misalnya, kondisi berikut akan mengirim pesan ke perangkat yang berlangganan TopicA dan TopicB atau TopicC:

"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"

FCM terlebih dahulu mengevaluasi setiap kondisiyang berada di antara tanda kurung, lalu mengevaluasi ekspresi tersebut dari kiri ke kanan. Pada ekspresi di atas, pengguna yang berlangganan satu topik apa pun tidak akan menerima pesan. Demikian pula pengguna yang tidak berlangganan TopicA tidak akan menerima pesan. Namun, kombinasi berikut menerimanya:

  • TopicA dan TopicB
  • TopicA dan TopicC

Anda dapat menyertakan hingga lima topik dalam ekspresi bersyarat.

Untuk mengirim ke sebuah kondisi:

Node.js

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
var condition = "'stock-GOOG' in topics || 'industry-tech' in topics";

// See documentation on defining a message payload.
var message = {
  notification: {
    title: '$GOOG up 1.43% on the day',
    body: '$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.'
  },
  condition: condition
};

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
admin.messaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
String condition = "'stock-GOOG' in topics || 'industry-tech' in topics";

// See documentation on defining a message payload.
Message message = Message.builder()
    .setNotification(new Notification(
        "$GOOG up 1.43% on the day",
        "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day."))
    .setCondition(condition)
    .build();

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);

Python

# Define a condition which will send to devices which are subscribed
# to either the Google stock or the tech industry topics.
condition = "'stock-GOOG' in topics || 'industry-tech' in topics"

# See documentation on defining a message payload.
message = messaging.Message(
    notification=messaging.Notification(
        title='$GOOG up 1.43% on the day',
        body='$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
    ),
    condition=condition,
)

# Send a message to devices subscribed to the combination of topics
# specified by the provided condition.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)

Go

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
condition := "'stock-GOOG' in topics || 'industry-tech' in topics"

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Condition: condition,
}

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)

C#

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
var condition = "'stock-GOOG' in topics || 'industry-tech' in topics";

// See documentation on defining a message payload.
var message = new Message()
{
    Notification = new Notification()
    {
        Title = "$GOOG up 1.43% on the day",
        Body = "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
    },
    Condition = condition,
};

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
   "message":{
    "condition": "'dogs' in topics || 'cats' in topics",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message",
    }
  }
}

Perintah cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "notification": {
    "title": "FCM Message",
    "body": "This is a Firebase Cloud Messaging Topic Message!",
  },
  "condition": "'dogs' in topics || 'cats' in topics"
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Mengirim banyak pesan

Admin SDK untuk Node dan Java mendukung pengiriman banyak pesan sekaligus. Anda dapat mengelompokkan hingga 100 pesan ke dalam satu batch dan mengirim semuanya dalam satu panggilan API dengan peningkatan performa yang signifikan atas pengiriman permintaan HTTP terpisah untuk setiap pesan.

Fitur ini dapat digunakan untuk membangun satu set pesan yang disesuaikan dan mengirimkannya ke penerima yang berbeda, termasuk topik atau token pendaftaran perangkat tertentu. Gunakan fitur ini ketika, misalnya, Anda perlu mengirim pesan secara bersamaan ke audiens yang berbeda dengan detail yang sedikit berbeda di badan pesan.

Node.js

// Create a list containing up to 100 messages.
const messages = [];
messages.push({
  notification: {title: 'Price drop', body: '5% off all electronics'},
  token: registrationToken,
});
messages.push({
  notification: {title: 'Price drop', body: '2% off all books'},
  topic: 'readers-club',
});

admin.messaging().sendAll(messages)
  .then((response) => {
    console.log(response.successCount + ' messages were sent successfully');
  });

Java

// Create a list containing up to 100 messages.
List<Message> messages = Arrays.asList(
    Message.builder()
        .setNotification(new Notification("Price drop", "5% off all electronics"))
        .setToken(registrationToken)
        .build(),
    // ...
    Message.builder()
        .setNotification(new Notification("Price drop", "2% off all books"))
        .setTopic("readers-club")
        .build()
);

BatchResponse response = FirebaseMessaging.getInstance().sendAll(messages);
// See the BatchResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " messages were sent successfully");

Anda dapat meminta BatchResponse dikembalikan untuk memeriksa berapa banyak pesan yang berhasil dikirim ke FCM. Ini juga memaparkan daftar tanggapan yang dapat digunakan untuk memeriksa status pesan individual. Urutan tanggapan sesuai dengan urutan pesan dalam daftar input.

Menyesuaikan pesan di seluruh platform

Firebase Admin SDK dan protokol HTTP FCM v1 memungkinkan permintaan pesan Anda untuk menyetel semua kolom yang tersedia di objek message. Hal ini mencakup:

  • sekumpulan kolom umum untuk ditafsirkan oleh semua instance aplikasi yang menerima pesan tersebut.
  • kumpulan kolom khusus platform, seperti AndroidConfig dan WebpushConfig, hanya ditafsirkan oleh instance aplikasi yang berjalan pada platform tertentu.

Blok khusus platform memberikan Anda fleksibilitas dalam menyesuaikan pesan untuk berbagai platform, guna memastikan pesan ditangani dengan benar saat diterima. Backend FCM akan mempertimbangkan semua parameter yang telah ditentukan dan menyesuaikan pesan untuk setiap platform.

Kapan kolom umum digunakan

Gunakan kolom umum saat Anda:

  • Menargetkan instance aplikasi di semua platform — iOS, Android, dan web
  • Mengirim pesan ke topik

Semua instance aplikasi, dari platform apa saja, dapat menafsirkan kolom umum berikut:

Kapan harus menggunakan kolom khusus platform

Gunakan kolom khusus platform ketika Anda ingin:

  • Mengirim kolom hanya ke platform tertentu
  • Mengirim kolom khusus platform selain kolom umum

Kapan pun Anda ingin mengirim nilai ke platform tertentu saja, jangan gunakan kolom umum; gunakan kolom khusus platform. Misalnya, untuk mengirim notifikasi ke iOS dan web saja, namun tidak ke Android, Anda harus menggunakan dua kumpulan kolom terpisah, yaitu satu untuk iOS dan satu lagi untuk web.

Saat Anda mengirim pesan dengan opsi pengiriman tertentu, gunakan kolom khusus platform untuk menetapkannya. Anda dapat menentukan nilai yang berbeda per platform jika mau. Namun, meskipun Anda ingin menetapkan nilai yang sama pada platform, Anda harus menggunakan kolom khusus platform. Hal ini disebabkan karena setiap platform mungkin menafsirkan nilai sedikit berbeda. Misalnya, waktu aktif ditetapkan di Android sebagai waktu berakhir dalam hitungan detik, sedangkan pada iOS ditetapkan sebagai tanggal habis masa berlaku.

Contoh: pesan notifikasi dengan opsi pengiriman khusus platform

Permintaan kirim berikut mengirimkan judul notifikasi umum dan konten ke semua platform, tetapi juga mengirimkan beberapa penggantian khusus platform. Secara khusus, permintaan ini:

  • Menetapkan waktu aktif yang lama untuk platform Android dengan ikon dan warna khusus untuk ditampilkan di perangkat Android.
  • Menetapkan kolom badge iOS saja di payload APN untuk dikirimkan ke perangkat iOS.

Node.js

var message = {
  notification: {
    title: '$GOOG up 1.43% on the day',
    body: '$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
  },
  android: {
    ttl: 3600 * 1000,
    notification: {
      icon: 'stock_ticker_update',
      color: '#f45342',
    },
  },
  apns: {
    payload: {
      aps: {
        badge: 42,
      },
    },
  },
  topic: 'industry-tech'
};

Java

Message message = Message.builder()
    .setNotification(new Notification(
        "$GOOG up 1.43% on the day",
        "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day."))
    .setAndroidConfig(AndroidConfig.builder()
        .setTtl(3600 * 1000)
        .setNotification(AndroidNotification.builder()
            .setIcon("stock_ticker_update")
            .setColor("#f45342")
            .build())
        .build())
    .setApnsConfig(ApnsConfig.builder()
        .setAps(Aps.builder()
            .setBadge(42)
            .build())
        .build())
    .setTopic("industry-tech")
    .build();

Python

message = messaging.Message(
    notification=messaging.Notification(
        title='$GOOG up 1.43% on the day',
        body='$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
    ),
    android=messaging.AndroidConfig(
        ttl=datetime.timedelta(seconds=3600),
        priority='normal',
        notification=messaging.AndroidNotification(
            icon='stock_ticker_update',
            color='#f45342'
        ),
    ),
    apns=messaging.APNSConfig(
        payload=messaging.APNSPayload(
            aps=messaging.Aps(badge=42),
        ),
    ),
    topic='industry-tech',
)

Go

oneHour := time.Duration(1) * time.Hour
badge := 42
message := &messaging.Message{
	Notification: &messaging.Notification{
		Title: "$GOOG up 1.43% on the day",
		Body:  "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
	},
	Android: &messaging.AndroidConfig{
		TTL: &oneHour,
		Notification: &messaging.AndroidNotification{
			Icon:  "stock_ticker_update",
			Color: "#f45342",
		},
	},
	APNS: &messaging.APNSConfig{
		Payload: &messaging.APNSPayload{
			Aps: &messaging.Aps{
				Badge: &badge,
			},
		},
	},
	Topic: "industry-tech",
}

REST

{
  "message":{
     "topic":"industry-tech",
     "notification":{
       "title": "$GOOG" up 1.43% on the day",
       "body":"GOOG gained 11.80 points to close at 835.67, up 1.43% on the day."
     },
     "android":{
       "ttl":"3600s",
       "notification"{
         "icon:stock_ticker_update"
         "color:#f45342"
       }
     },
     "apns": {
       "payload": {
         "aps": {
           "badge": "42"
         }
       }
     },
     "webpush":{
       "headers":{
         "TTL":"86400"
       }
     }
   }
 }

Lihat dokumentasi referensi HTTP v1 untuk mengetahui detail lengkap tentang kunci yang tersedia di blok khusus platform dalam isi pesan.

Referensi error Admin FCM SDK

Tabel berikut berisi kode error API Firebase Admin FCM dan deskripsinya, termasuk langkah penyelesaian yang direkomendasikan.

Kode Error Deskripsi dan Langkah Penyelesaian
messaging/invalid-argument Argumen yang tidak valid dimasukkan ke metode FCM. Pesan error ini semestinya memuat informasi tambahan.
messaging/invalid-recipient Penerima pesan yang dimaksud tidak valid. Pesan error ini semestinya berisi informasi tambahan.
messaging/invalid-payload Objek payload pesan yang tidak valid dimasukkan. Pesan error ini semestinya berisi informasi tambahan.
messaging/invalid-data-payload-key Payload pesan data berisi kunci yang tidak valid. Baca dokumentasi referensi DataMessagePayload untuk mengetahui kunci yang dibatasi.
messaging/payload-size-limit-exceeded Payload pesan yang dimasukkan melebihi batas ukuran FCM. Batasnya adalah 4.096 byte untuk sebagian besar pesan. Untuk pesan yang dikirim ke topik, batasnya adalah 2.048 byte. Ukuran total payload mencakup kunci sekaligus nilai.
messaging/invalid-options Objek opsi pesan yang tidak valid dimasukkan. Pesan error ini semestinya berisi informasi tambahan.
messaging/invalid-registration-token Token pendaftaran yang tidak valid dimasukkan. Pastikan formatnya cocok dengan token pendaftaran yang diterima aplikasi klien ketika mendaftar ke FCM. Jangan menyingkat atau menambahkan karakter ekstra ke token.
messaging/registration-token-not-registered Token pendaftaran yang dimasukkan tidak terdaftar. Token pendaftaran valid yang sebelumnya dapat dibatalkan pendaftarannya karena berbagai alasan, termasuk:
  • Aplikasi klien membatalkan pendaftarannya dari FCM.
  • Aplikasi klien membatalkan pendaftaran secara otomatis. Ini dapat terjadi ketika pengguna meng-uninstal aplikasi atau, di iOS, saat APNS Feedback Service melaporkan bahwa token APNS tidak valid.
  • Masa pakai token pendaftaran habis. Misalnya, Google mungkin memutuskan untuk memperbarui token pendaftaran, atau token APNS untuk perangkat iOS mungkin telah habis masa berlakunya.
  • Aplikasi klien sudah diupdate tetapi versi yang baru belum dikonfigurasi untuk menerima pesan.
Untuk semua kasus tersebut, hapus token pendaftaran ini dan jangan gunakan lagi untuk mengirim pesan.
messaging/invalid-package-name Pesan ini ditujukan ke token pendaftaran yang nama paketnya tidak cocok dengan opsi restrictedPackageName yang diberikan.
messaging/message-rate-exceeded Jumlah pesan untuk target tertentu terlalu tinggi. Kurangi jumlah pesan yang dikirim ke perangkat atau topik ini, dan jangan langsung mencoba mengirimkan pesan lagi ke target ini.
messaging/device-message-rate-exceeded Jumlah pesan untuk perangkat tertentu terlalu tinggi. Kurangi jumlah pesan yang dikirim ke perangkat ini dan jangan langsung mencoba mengirimkan pesan lagi ke perangkat ini.
messaging/topics-message-rate-exceeded Jumlah pesan untuk pelanggan pada topik tertentu terlalu banyak. Kurangi jumlah pesan yang dikirim ke topik ini dan jangan langsung mencoba mengirimkan pesan lagi ke topik ini.
messaging/too-many-topics Token pendaftaran telah berlangganan ke jumlah maksimum topik dan tidak dapat lagi berlangganan topik lainnya.
messaging/invalid-apns-credentials Pesan yang ditargetkan ke perangkat iOS tidak bisa dikirim karena sertifikat SSL APN yang diperlukan tidak diupload atau tidak berlaku lagi. Periksa validitas sertifikat pengembangan dan produksi Anda.
messaging/mismatched-credential Kredensial yang digunakan untuk mengautentikasi SDK ini tidak memiliki izin untuk mengirim pesan ke perangkat yang berhubungan dengan token pendaftaran yang dimasukkan. Pastikan bahwa baik kredensial maupun token pendaftaran termasuk dalam project Firebase yang sama. Lihat Menambahkan Firebase ke aplikasi Anda untuk dokumentasi tentang cara mengautentikasi Firebase Admin SDK.
messaging/authentication-error SDK tidak dapat melakukan autentikasi ke server FCM. Pastikan Anda mengautentikasi Firebase Admin SDK dengan kredensial yang memiliki izin yang tepat untuk mengirim pesan FCM. Lihat Menambahkan Firebase ke aplikasi Anda untuk dokumentasi tentang cara mengautentikasi Firebase Admin SDK.
messaging/server-unavailable Server FCM tidak dapat memproses permintaan secara tepat waktu. Coba lagi permintaan yang sama, tetapi Anda harus:
  • Mematuhi header Retry-After jika dimasukkan dalam respons dari Server Koneksi FCM.
  • Menerapkan back-off eksponensial dalam mekanisme percobaan ulang. Misalnya, jika Anda menunggu satu detik sebelum percobaan ulang pertama, tunggulah setidaknya dua detik sebelum percobaan ulang berikutnya, lalu empat detik dan seterusnya. Jika Anda mengirim beberapa pesan, tunda setiap pesan secara independen dengan jumlah acak tambahan agar tidak mengeluarkan permintaan baru untuk semua pesan secara bersamaan.
Pengirim yang menyebabkan masalah berisiko dimasukkan ke daftar hitam.
messaging/internal-error Server FCM mengalami error ketika mencoba memproses permintaan. Anda bisa mencoba lagi permintaan yang sama dengan mengikuti persyaratan yang tercantum pada baris messaging/server-unavailable di atas. Jika error tetap berlanjut, laporkan masalah ke saluran dukungan Laporan Bug kami.
messaging/unknown-error Muncul error server yang tidak diketahui. Lihat respons mentah server pada pesan error untuk lebih jelasnya. Jika Anda menerima error ini, harap laporkan pesan error lengkap ke saluran dukungan Laporan Bug kami.

Mengirim pesan menggunakan protokol server aplikasi versi lama

Jika Anda lebih suka menggunakan protokol lama, buatlah permintaan pesan seperti ditunjukkan dalam bagian ini. Perlu diingat bahwa, jika Anda mengirim ke beberapa platform melalui HTTP, protokol v1 dapat menyederhanakan permintaan pesan Anda.

Mengirim pesan ke perangkat tertentu

Untuk mengirim pesan ke perangkat tertentu, tentukan kunci to ke token pendaftaran untuk instance aplikasi tertentu. Lihat informasi penyiapan klien untuk platform Anda untuk mempelajari lebih jauh tentang token pendaftaran.

Permintaan HTTP POST

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

{ "data": {
    "score": "5x1",
    "time": "15:10"
  },
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}

Respons HTTP

{ "multicast_id": 108,
  "success": 1,
  "failure": 0,
  "results": [
    { "message_id": "1:08" }
  ]
}

Pesan XMPP

<message id="">
  <gcm xmlns="google:mobile:data">
    { "data": {
      "score": "5x1",
      "time": "15:10"
    },
    "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  }
  </gcm>
</message>

Respons XMPP

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

Server koneksi XMPP menyediakan beberapa opsi lain untuk respons. Lihat Format respons server.

Untuk mengetahui daftar lengkap opsi pesan yang tersedia saat mengirim pesan downstream ke aplikasi klien, lihat informasi referensi untuk protokol server koneksi pilihan Anda, HTTP atau XMPP.

Mengirim pesan ke topik

Mengirim pesan ke topik Firebase Cloud Messaging serupa dengan mengirim pesan ke perangkat individual atau ke grup pengguna. Server aplikasi menetapkan kunci to dengan nilai seperti /topics/yourTopic. Developer bisa memilih nama topik apa pun yang cocok dengan ekspresi reguler: "/topics/[a-zA-Z0-9-_.~%]+".

Untuk mengirim ke kombinasi beberapa topik, server aplikasi harus menetapkan kunci condition (bukan kunci to) ke condition boolean yang menentukan topik target. Misalnya, untuk mengirimkan pesan ke perangkat yang berlangganan TopicA dan salah satu dari TopicB atau TopicC:

'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)

FCM mengevaluasi terlebih dahulu setiap kondisi di dalam tanda kurung, lalu mengevaluasi ekspresi tersebut dari kiri ke kanan. Pada ekspresi di atas, pengguna yang berlangganan satu topik apa pun tidak akan menerima pesan. Demikian pula, pengguna yang tidak berlangganan TopicA tidak akan menerima pesan. Namun, kombinasi berikut akan menerima pesan:

  • TopicA dan TopicB
  • TopicA dan TopicC

Anda dapat menyertakan hingga lima topik dalam ekspresi bersyarat. Penggunaan tanda kurung didukung. Operator yang didukung: &&, ||, !. Perhatikan penggunaan untuk !:

!('TopicA' in topics)

Dengan menggunakan ekspresi ini, setiap instance aplikasi yang tidak berlangganan TopicA, termasuk instance aplikasi yang tidak berlangganan topik mana pun, akan menerima pesan.

Untuk mengetahui detail lebih lanjut mengenai kunci server aplikasi, lihat informasi referensi untuk protokol server koneksi pilihan Anda, HTTP atau XMPP. Contoh di halaman ini menunjukkan cara mengirim pesan ke topik, baik pada HTTP maupun XMPP.

Permintaan HTTP POST topik

Mengirim ke satu topik:

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

Mengirim ke perangkat yang berlangganan topik "dogs" atau "cats":

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

Respons HTTP topik

//Success example:
{
  "message_id": "1023456"
}

//failure example:
{
  "error": "TopicsMessageRateExceeded"
}

Pesan XMPP topik

Mengirim ke satu topik:

<message id="">
  <gcm xmlns="google:mobile:data">

  </gcm>
</message>

Mengirim ke perangkat yang berlangganan topik "dogs" atau "cats":

<message id="">
  <gcm xmlns="google:mobile:data">

  </gcm>
</message>

Respons XMPP topik

//Success example:
{
  "message_id": "1023456"
}

//failure example:
{
  "error": "TopicsMessageRateExceeded"
}

Perkirakan penundaan hingga 30 detik sebelum Server FCM menampilkan respons berhasil atau gagal untuk permintaan pengiriman topik. Karena itu, pastikan menyetel nilai waktu tunggu server aplikasi pada permintaan.

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

Mengirim pesan ke grup perangkat

Mengirim pesan ke grup perangkat sangat mirip dengan pengiriman pesan ke perangkat satu per satu. Tetapkan parameter to ke kunci notifikasi unik untuk grup perangkat tersebut. Lihat 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.

Metode pengiriman lama Firebase Admin SDK

Firebase Admin Node.js SDK mendukung metode untuk mengirim pesan (FCM) berdasarkan API server FCM Lama. Metode ini menerima argumen yang berbeda dibandingkan dengan metode send(). Anda harus menggunakan metode send() jika memungkinkan dan hanya menggunakan metode yang dijelaskan dalam halaman ini saat mengirimkan pesan ke 1 perangkat atau grup perangkat.

Mengirim Pesan ke 1 perangkat

Anda dapat meneruskan token pendaftaran ke metode sendToDevice() untuk mengirim pesan ke perangkat tersebut:

Node.js

// This registration token comes from the client FCM SDKs.
var registrationToken = 'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...';

// See the "Defining the message payload" section below for details
// on how to define a message payload.
var payload = {
  data: {
    score: '850',
    time: '2:45'
  }
};

// Send a message to the device corresponding to the provided
// registration token.
admin.messaging().sendToDevice(registrationToken, payload)
  .then(function(response) {
    // See the MessagingDevicesResponse reference documentation for
    // the contents of response.
    console.log('Successfully sent message:', response);
  })
  .catch(function(error) {
    console.log('Error sending message:', error);
  });

Metode sendToDevice() juga dapat mengirim pesan multicast (pesan ke beberapa perangkat) dengan meneruskan serangkaian token pendaftaran, bukan hanya satu token pendaftaran:

Node.js

// These registration tokens come from the client FCM SDKs.
var registrationTokens = [
  'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...',
  // ...
  'ecupwIfBy1w:APA91bFtuMY7MktgxA3Au_Qx7cKqnf...'
];

// See the "Defining the message payload" section below for details
// on how to define a message payload.
var payload = {
  data: {
    score: '850',
    time: '2:45'
  }
};

// Send a message to the devices corresponding to the provided
// registration tokens.
admin.messaging().sendToDevice(registrationTokens, payload)
  .then(function(response) {
    // See the MessagingDevicesResponse reference documentation for
    // the contents of response.
    console.log('Successfully sent message:', response);
  })
  .catch(function(error) {
    console.log('Error sending message:', error);
  });

Metode sendToDevice() menampilkan promise yang diselesaikan dengan objek MessagingDevicesResponse yang berisi respons dari FCM. Jenis promise yang ditampilkan memiliki format yang sama, baik ketika meneruskan satu token pendaftaran maupun serangkaian token pendaftaran.

Beberapa kasus seperti error autentikasi atau pembatasan jumlah menyebabkan seluruh pesan gagal diproses. Dalam kasus ini, promise yang ditampilkan oleh sendToDevice() ditolak dengan error. Untuk daftar lengkap kode error, termasuk deskripsi dan langkah penyelesaian, lihat Error Admin FCM API.

Mengirim ke grup perangkat

Dengan pengiriman pesan 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 melalui XMPP lama atau protokol HTTP pada 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.

Anda dapat membuat grup perangkat dan memunculkan kunci notifikasi lewat server aplikasi atau klien Android. Lihat Mengelola grup perangkat untuk detailnya.

Dengan metode sendToDeviceGroup(), Anda dapat mengirim pesan ke grup perangkat dengan menentukan kunci notifikasi untuk grup perangkat tersebut:

Node.js

// See the "Managing device groups" link above on how to generate a
// notification key.
var notificationKey = 'some-notification-key';

// See the "Defining the message payload" section below for details
// on how to define a message payload.
var payload = {
  data: {
    score: '850',
    time: '2:45'
  }
};

// Send a message to the device group corresponding to the provided
// notification key.
admin.messaging().sendToDeviceGroup(notificationKey, payload)
  .then(function(response) {
    // See the MessagingDeviceGroupResponse reference documentation for
    // the contents of response.
    console.log('Successfully sent message:', response);
  })
  .catch(function(error) {
    console.log('Error sending message:', error);
  });

Metode sendToDeviceGroup() menampilkan promise yang diselesaikan dengan objek MessagingDeviceGroupResponse yang berisi respons dari FCM.

Beberapa kasus seperti error autentikasi atau pembatasan jumlah menyebabkan seluruh pesan gagal diproses. Dalam kasus ini, promise yang ditampilkan oleh sendToDeviceGroup() ditolak dengan error. Untuk mengetahui daftar lengkap kode error, termasuk deskripsi dan langkah penyelesaian, baca bagian Error Admin FCM API.

Menetapkan payload pesan

Metode berdasarkan protokol lama FCM di atas menerima payload pesan sebagai argumen kedua dan mendukung pesan notifikasi dan juga pesan data. Anda dapat menentukan salah satu atau kedua jenis pesan dengan membuat objek dengan kunci data dan/atau notification. Sebagai contoh, berikut adalah cara menetapkan berbagai jenis payload pesan:

Pesan notifikasi

var payload = {
  notification: {
    title: '$GOOG up 1.43% on the day',
    body: '$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.'
  }
};

Pesan data

var payload = {
  data: {
    score: '850',
    time: '2:45'
  }
};

Pesan gabungan

var payload = {
  notification: {
    title: '$GOOG up 1.43% on the day',
    body: '$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.'
  },
  data: {
    stock: 'GOOG',
    open: '829.62',
    close: '635.67'
  }
};

Payload pesan notifikasi memiliki subset standar properti yang valid dan sedikit berbeda, tergantung sistem operasi seluler yang Anda targetkan. Baca dokumen referensi NotificationMessagePayload untuk mengetahui daftar lengkapnya.

Payload pesan data terdiri dari key-value pair kustom dengan beberapa pembatasan, termasuk fakta bahwa semua nilai harus berupa string. Baca dokumen referensi DataMessagePayload untuk mengetahui daftar lengkap pembatasan.

Menetapkan pilihan pesan

Metode berdasarkan protokol lama FCM di atas menerima argumen ke-3 opsional yang menentukan beberapa opsi untuk pesan tersebut. Misalnya, contoh berikut mengirim pesan berprioritas tinggi ke perangkat yang akan habis masa berlakunya setelah 24 jam:

Node.js

// This registration token comes from the client FCM SDKs.
var registrationToken = 'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...';

// See the "Defining the message payload" section above for details
// on how to define a message payload.
var payload = {
  notification: {
    title: 'Urgent action needed!',
    body: 'Urgent action is needed to prevent your account from being disabled!'
  }
};

// Set the message as high priority and have it expire after 24 hours.
var options = {
  priority: 'high',
  timeToLive: 60 * 60 * 24
};

// Send a message to the device corresponding to the provided
// registration token with the provided options.
admin.messaging().sendToDevice(registrationToken, payload, options)
  .then(function(response) {
    console.log('Successfully sent message:', response);
  })
  .catch(function(error) {
    console.log('Error sending message:', error);
  });

Baca dokumen referensi MessagingOptions untuk mengetahui daftar lengkap opsi yang tersedia.

Kirim masukan tentang...

Butuh bantuan? Kunjungi halaman dukungan kami.