Mit den App-Serverprotokollen Firebase Admin SDK oder FCM können Sie Nachrichtenanfragen erstellen und an diese Arten von Zielen senden:
- Name des Themas
- Bedingung
- Geräteregistrierungstoken
- Name der Gerätegruppe (nur Protokoll)
Sie können Nachrichten mit einer Benachrichtigungsnutzlast aus vordefinierten Feldern, einer Datennutzlast mit eigenen benutzerdefinierten Feldern oder einer Nachricht senden, die beide Arten von Nutzlasten enthält. Weitere Informationen finden Sie unter Nachrichtentypen.
Auf dieser Seite finden Sie Beispiele zum Senden von Benachrichtigungsnachrichten mit Firebase Admin SDK (unterstützt Node, Java, Python, C# und Go) und dem HTTP-Protokoll v1. Es gibt auch eine Anleitung zum Senden von Nachrichten über die eingestellten HTTP- und XMPP-Protokolle.
Nachrichten an bestimmte Geräte senden
Wenn du eine Nachricht an ein einzelnes Gerät senden möchtest, gib das Registrierungstoken des Geräts wie gezeigt an. Weitere Informationen zu Registrierungstokens findest du in der Anleitung zur Clienteinrichtung für deine Plattform.
Node.js
// This registration token comes from the client FCM SDKs.
const registrationToken = 'YOUR_REGISTRATION_TOKEN';
const message = {
data: {
score: '850',
time: '2:45'
},
token: registrationToken
};
// Send a message to the device corresponding to the provided
// registration token.
getMessaging().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"
}
}
}
cURL-Befehl:
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
Bei Erfolg gibt jede Sendemethode eine Nachrichten-ID zurück. Firebase Admin SDK gibt den ID-String im Format projects/{project_id}/messages/{message_id} zurück.
Die HTTP-Protokollantwort besteht aus einem einzelnen JSON-Schlüssel:
{
"name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
}
Nachrichten an mehrere Geräte senden
Mit den Admin FCM APIs können Sie eine Nachricht an eine Liste von Geräteregistrierungstokens per Multicast senden. Sie können bis zu 500 Geräteregistrierungstokens pro Aufruf angeben.
Node.js
// Create a list containing up to 500 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,
};
getMessaging().sendMulticast(message)
.then((response) => {
console.log(response.successCount + ' messages were sent successfully');
});
Java
// Create a list containing up to 500 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");
Python
# Create a list containing up to 500 registration tokens.
# These registration tokens come from the client FCM SDKs.
registration_tokens = [
'YOUR_REGISTRATION_TOKEN_1',
# ...
'YOUR_REGISTRATION_TOKEN_N',
]
message = messaging.MulticastMessage(
data={'score': '850', 'time': '2:45'},
tokens=registration_tokens,
)
response = messaging.send_multicast(message)
# See the BatchResponse reference documentation
# for the contents of response.
print('{0} messages were sent successfully'.format(response.success_count))
Go
// Create a list containing up to 500 registration tokens.
// This registration tokens come from the client FCM SDKs.
registrationTokens := []string{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
}
message := &messaging.MulticastMessage{
Data: map[string]string{
"score": "850",
"time": "2:45",
},
Tokens: registrationTokens,
}
br, err := client.SendMulticast(context.Background(), message)
if err != nil {
log.Fatalln(err)
}
// See the BatchResponse reference documentation
// for the contents of response.
fmt.Printf("%d messages were sent successfully\n", br.SuccessCount)
C#
// Create a list containing up to 500 registration tokens.
// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
};
var message = new MulticastMessage()
{
Tokens = registrationTokens,
Data = new Dictionary<string, string>()
{
{ "score", "850" },
{ "time", "2:45" },
},
};
var response = await FirebaseMessaging.DefaultInstance.SendEachForMulticastAsync(message);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");
Der Rückgabewert ist eine Liste von Tokens, die der Reihenfolge der Eingabetokens entsprechen. Dies ist nützlich, wenn Sie prüfen möchten, welche Tokens zu Fehlern geführt haben.
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,
};
getMessaging().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);
}
Python
# These registration tokens come from the client FCM SDKs.
registration_tokens = [
'YOUR_REGISTRATION_TOKEN_1',
# ...
'YOUR_REGISTRATION_TOKEN_N',
]
message = messaging.MulticastMessage(
data={'score': '850', 'time': '2:45'},
tokens=registration_tokens,
)
response = messaging.send_multicast(message)
if response.failure_count > 0:
responses = response.responses
failed_tokens = []
for idx, resp in enumerate(responses):
if not resp.success:
# The order of responses corresponds to the order of the registration tokens.
failed_tokens.append(registration_tokens[idx])
print('List of tokens that caused failures: {0}'.format(failed_tokens))
Go
// Create a list containing up to 500 registration tokens.
// This registration tokens come from the client FCM SDKs.
registrationTokens := []string{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
}
message := &messaging.MulticastMessage{
Data: map[string]string{
"score": "850",
"time": "2:45",
},
Tokens: registrationTokens,
}
br, err := client.SendMulticast(context.Background(), message)
if err != nil {
log.Fatalln(err)
}
if br.FailureCount > 0 {
var failedTokens []string
for idx, resp := range br.Responses {
if !resp.Success {
// The order of responses corresponds to the order of the registration tokens.
failedTokens = append(failedTokens, registrationTokens[idx])
}
}
fmt.Printf("List of tokens that caused failures: %v\n", failedTokens)
}
C#
// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
};
var message = new MulticastMessage()
{
Tokens = registrationTokens,
Data = new Dictionary<string, string>()
{
{ "score", "850" },
{ "time", "2:45" },
},
};
var response = await FirebaseMessaging.DefaultInstance.SendEachForMulticastAsync(message);
if (response.FailureCount > 0)
{
var failedTokens = new List<string>();
for (var i = 0; i < response.Responses.Count; i++)
{
if (!response.Responses[i].IsSuccess)
{
// The order of responses corresponds to the order of the registration tokens.
failedTokens.Add(registrationTokens[i]);
}
}
Console.WriteLine($"List of tokens that caused failures: {failedTokens}");
}
Nachrichten an Themen senden
Nachdem Sie ein Thema erstellt haben, indem Sie Client-App-Instanzen entweder clientseitig für das Thema abonniert oder die Server API verwendet haben, können Sie Nachrichten an das Thema senden. Wenn Sie zum ersten Mal Sendeanfragen für FCM erstellen, finden Sie im Leitfaden zu Ihrer Serverumgebung und FCM wichtige Hintergrundinformationen und Einrichtungsanleitungen.
Geben Sie in Ihrer Versandlogik im Backend den gewünschten Themennamen wie unten gezeigt an:
Node.js
// The topic name can be optionally prefixed with "/topics/".
const topic = 'highScores';
const message = {
data: {
score: '850',
time: '2:45'
},
topic: topic
};
// Send a message to devices subscribed to the provided topic.
getMessaging().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"
}
}
}
cURL-Befehl:
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
Wenn Sie eine Nachricht an eine Kombination von Themen senden möchten, geben Sie eine Bedingung an. Das ist ein boolescher Ausdruck, der die Zielthemen angibt. Mit der folgenden Bedingung werden beispielsweise Nachrichten an Geräte gesendet, die TopicA und entweder TopicB oder TopicC abonniert haben:
"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"
Bei FCM werden zuerst alle Bedingungen in Klammern und dann der Ausdruck von links nach rechts ausgewertet. In der obigen Ausdrucksform erhält ein Nutzer, der ein einzelnes Thema abonniert hat, die Nachricht nicht. Ein Nutzer, der TopicA nicht abonniert hat, erhält die Nachricht ebenfalls nicht. In folgenden Fällen erhalten Sie sie:
TopicAundTopicBTopicAundTopicC
Sie können bis zu fünf Themen in einen bedingten Ausdruck aufnehmen.
So senden Sie eine Anfrage an eine Bedingung:
Node.js
// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
const condition = '\'stock-GOOG\' in topics || \'industry-tech\' in topics';
// See documentation on defining a message payload.
const message = {
notification: {
title: '$FooCorp up 1.43% on the day',
body: '$FooCorp 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.
getMessaging().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(Notification.builder()
.setTitle("$GOOG up 1.43% on the day")
.setBody("$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.")
.build())
.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",
}
}
}
cURL-Befehl:
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
Nachrichten an Gerätegruppen senden
Verwenden Sie die HTTP v1 API, um Nachrichten an Gerätegruppen zu senden. Wenn Sie derzeit mit den veralteten Sende-APIs für HTTP oder XMPP oder mit einer der älteren Versionen der Firebase Admin SDK für Node.js, die auf den alten Protokollen basieren, an Gerätegruppen senden, empfehlen wir Ihnen dringend, so bald wie möglich zur HTTP v1 API zu migrieren. Die bisherigen Send-APIs werden im Juni 2024 deaktiviert und entfernt.
Das Senden von Nachrichten an eine Gerätegruppe ähnelt dem Senden von Nachrichten an ein einzelnes Gerät. Dabei wird dieselbe Methode verwendet, um Sendeanfragen zu autorisieren. Legen Sie für das Feld token den Schlüssel für Gruppenbenachrichtigungen fest:
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":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
"data":{
"hello": "This is a Firebase Cloud Messaging device group message!"
}
}
}
cURL-Befehl
curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
"data":{
"hello": "This is a Firebase Cloud Messaging device group message!"
},
"token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send
Mehrere Nachrichten gleichzeitig senden
Die Admin SDKs unterstützen das Senden von Nachrichten im Batch. Sie können bis zu 500 Nachrichten in einem einzigen Batch gruppieren und alle in einem einzigen API-Aufruf senden. Das führt zu einer deutlichen Leistungssteigerung gegenüber dem Senden separater HTTP-Anfragen für jede Nachricht.
Mit dieser Funktion können Sie benutzerdefinierte Nachrichten erstellen und an verschiedene Empfänger senden, einschließlich Themen oder bestimmter Geräteregistrierungstokens. Verwenden Sie diese Funktion, wenn Sie beispielsweise gleichzeitig Nachrichten an verschiedene Zielgruppen mit leicht unterschiedlichen Details im Nachrichtentext senden möchten.
Node.js
// Create a list containing up to 500 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',
});
getMessaging().sendAll(messages)
.then((response) => {
console.log(response.successCount + ' messages were sent successfully');
});
Java
// Create a list containing up to 500 messages.
List<Message> messages = Arrays.asList(
Message.builder()
.setNotification(Notification.builder()
.setTitle("Price drop")
.setBody("5% off all electronics")
.build())
.setToken(registrationToken)
.build(),
// ...
Message.builder()
.setNotification(Notification.builder()
.setTitle("Price drop")
.setBody("2% off all books")
.build())
.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");
Python
# Create a list containing up to 500 messages.
messages = [
messaging.Message(
notification=messaging.Notification('Price drop', '5% off all electronics'),
token=registration_token,
),
# ...
messaging.Message(
notification=messaging.Notification('Price drop', '2% off all books'),
topic='readers-club',
),
]
response = messaging.send_all(messages)
# See the BatchResponse reference documentation
# for the contents of response.
print('{0} messages were sent successfully'.format(response.success_count))
Go
// Create a list containing up to 500 messages.
messages := []*messaging.Message{
{
Notification: &messaging.Notification{
Title: "Price drop",
Body: "5% off all electronics",
},
Token: registrationToken,
},
{
Notification: &messaging.Notification{
Title: "Price drop",
Body: "2% off all books",
},
Topic: "readers-club",
},
}
br, err := client.SendAll(context.Background(), messages)
if err != nil {
log.Fatalln(err)
}
// See the BatchResponse reference documentation
// for the contents of response.
fmt.Printf("%d messages were sent successfully\n", br.SuccessCount)
C#
// Create a list containing up to 500 messages.
var messages = new List<Message>()
{
new Message()
{
Notification = new Notification()
{
Title = "Price drop",
Body = "5% off all electronics",
},
Token = registrationToken,
},
new Message()
{
Notification = new Notification()
{
Title = "Price drop",
Body = "2% off all books",
},
Topic = "readers-club",
},
};
var response = await FirebaseMessaging.DefaultInstance.SendEachAsync(messages);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");
Nachrichten mit aktiviertem Direct Boot senden (nur Android)
Mit der HTTP v1 API oder den Legacy-HTTP-APIs können Sie Nachrichten an Geräte im direkten Bootmodus senden. Bevor Sie Nachrichten an Geräte im direkten Bootmodus senden, müssen Sie die Schritte zum Empfangen von FCM-Nachrichten im Direct Boot-Modus für Clientgeräte ausgeführt haben.
Mit der FCM v1 HTTP API senden
Die Nachrichtenanfrage muss den Schlüssel "direct_boot_ok" : true in den AndroidConfig-Optionen des Anfragetexts enthalten. Beispiel:
https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send
Content-Type:application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"token" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
"data": {
"score": "5x1",
"time": "15:10"
},
"android": {
"direct_boot_ok": true,
},
}
Über die alte FCM HTTP API senden
Die Nachrichtenanfrage muss den Schlüssel "direct_boot_ok" : true auf der obersten Ebene des Anfragetexts enthalten. Beispiel:
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..."
"direct_boot_ok" : true
}
Nachrichten, die mit diesem Schlüssel im Anfragetext gesendet werden, können von Apps auf Geräten verarbeitet werden, die sich derzeit im Direktstartmodus befinden (und auch, wenn sie sich nicht in diesem Modus befinden).
Mitteilungen plattformübergreifend anpassen
Sowohl das Firebase Admin SDK- als auch das FCM v1-HTTP-Protokoll ermöglichen es, in Ihren Nachrichtenanfragen alle im message-Objekt verfügbaren Felder festzulegen. Dazu zählen:
- eine gemeinsame Gruppe von Feldern, die von allen App-Instanzen interpretiert werden, die die Nachricht empfangen.
- plattformspezifische Felder wie
AndroidConfigundWebpushConfig, die nur von App-Instanzen interpretiert werden, die auf der angegebenen Plattform ausgeführt werden.
Mit plattformspezifischen Blöcken können Sie Nachrichten flexibel für verschiedene Plattformen anpassen, damit sie beim Empfang richtig verarbeitet werden. Das FCM-Back-End berücksichtigt alle angegebenen Parameter und passt die Nachricht für jede Plattform an.
Wann sollten gemeinsame Felder verwendet werden?
Verwenden Sie allgemeine Felder, wenn Sie:
- Targeting auf App-Instanzen auf allen Plattformen – Apple, Android und Web
- Nachrichten an Themen senden
Alle App-Instanzen können unabhängig von der Plattform die folgenden gängigen Felder interpretieren:
Wann plattformspezifische Felder verwendet werden
Plattformspezifische Felder eignen sich für Folgendes:
- Felder nur an bestimmte Plattformen senden
- Plattformspezifische Felder zusätzlich zu den allgemeinen Feldern senden
Wenn Sie Werte nur an bestimmte Plattformen senden möchten, verwenden Sie keine allgemeinen Felder, sondern plattformspezifische Felder. Wenn Sie beispielsweise eine Benachrichtigung nur an Apple-Plattformen und das Web, aber nicht an Android senden möchten, müssen Sie zwei separate Felder verwenden, einen für Apple und einen für das Web.
Wenn Sie Nachrichten mit bestimmten Zustellungsoptionen senden, verwenden Sie platformspezifische Felder, um sie festzulegen. Du kannst pro Plattform unterschiedliche Werte angeben. Auch wenn Sie auf allen Plattformen im Wesentlichen denselben Wert festlegen möchten, müssen Sie plattformspezifische Felder verwenden. Das liegt daran, dass jede Plattform den Wert möglicherweise etwas anders interpretiert. So wird die Gültigkeitsdauer unter Android beispielsweise als Ablaufzeit in Sekunden festgelegt, während sie unter Apple als Ablaufdatum festgelegt wird.
Beispiel: Benachrichtigungsnachricht mit Farb- und Symboloptionen
In dieser Beispiel-Sendeanfrage werden ein gemeinsamer Benachrichtigungstitel und -inhalt an alle Plattformen gesendet, aber auch einige plattformspezifische Überschreibungen an Android-Geräte.
Bei Android wird über die Anfrage ein spezielles Symbol und eine spezielle Farbe für die Anzeige auf Android-Geräten festgelegt. Wie in der Referenz für AndroidNotification angegeben, wird die Farbe im Format #rrggbb angegeben und das Bild muss eine lokale drawable-Symbolressource in der Android-App sein.
Hier eine ungefähre Darstellung des visuellen Effekts auf dem Gerät eines Nutzers:
Node.js
const topicName = 'industry-tech';
const message = {
notification: {
title: '`$FooCorp` up 1.43% on the day',
body: 'FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
},
android: {
notification: {
icon: 'stock_ticker_update',
color: '#7e55c3'
}
},
topic: topicName,
};
getMessaging().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
Message message = Message.builder()
.setNotification(Notification.builder()
.setTitle("$GOOG up 1.43% on the day")
.setBody("$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.")
.build())
.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",
}
C#
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.",
},
Android = new AndroidConfig()
{
TimeToLive = TimeSpan.FromHours(1),
Notification = new AndroidNotification()
{
Icon = "stock_ticker_update",
Color = "#f45342",
},
},
Apns = new ApnsConfig()
{
Aps = new Aps()
{
Badge = 42,
},
},
Topic = "industry-tech",
};
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":"industry-tech",
"notification":{
"title":"`$FooCorp` up 1.43% on the day",
"body":"FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day."
},
"android":{
"notification":{
"icon":"stock_ticker_update",
"color":"#7e55c3"
}
}
}
}
Ausführliche Informationen zu den Schlüsseln, die in plattformspezifischen Blöcken im Nachrichtentext verfügbar sind, finden Sie in der HTTP v1-Referenzdokumentation.
Beispiel: Benachrichtigung mit einem benutzerdefinierten Bild
In der folgenden Beispiel-Sendeanfrage wird ein gemeinsamer Benachrichtigungstitel an alle Plattformen gesendet, aber auch ein Bild. Die visuelle Wirkung auf das Gerät eines Nutzers lässt sich so schätzen:
Node.js
const topicName = 'industry-tech';
const message = {
notification: {
title: 'Sparky says hello!'
},
android: {
notification: {
imageUrl: 'https://foo.bar.pizza-monster.png'
}
},
apns: {
payload: {
aps: {
'mutable-content': 1
}
},
fcm_options: {
image: 'https://foo.bar.pizza-monster.png'
}
},
webpush: {
headers: {
image: 'https://foo.bar.pizza-monster.png'
}
},
topic: topicName,
};
getMessaging().send(message)
.then((response) => {
// Response is a message ID string.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
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":"industry-tech",
"notification":{
"title":"Sparky says hello!",
},
"android":{
"notification":{
"image":"https://foo.bar/pizza-monster.png"
}
},
"apns":{
"payload":{
"aps":{
"mutable-content":1
}
},
"fcm_options": {
"image":"https://foo.bar/pizza-monster.png"
}
},
"webpush":{
"headers":{
"image":"https://foo.bar/pizza-monster.png"
}
}
}
}
Ausführliche Informationen zu den Schlüsseln, die in plattformspezifischen Blöcken im Nachrichtentext verfügbar sind, finden Sie in der Referenzdokumentation für HTTP v1.
Beispiel: Benachrichtigungsnachricht mit einer Klickaktion
In der folgenden Beispiel-Sendeanfrage wird ein gemeinsamer Benachrichtigungstitel an alle Plattformen gesendet. Außerdem wird eine Aktion gesendet, die die App ausführen soll, wenn der Nutzer mit der Benachrichtigung interagiert. Hier eine ungefähre Darstellung des visuellen Effekts auf dem Gerät eines Nutzers:
Node.js
const topicName = 'industry-tech';
const message = {
notification: {
title: 'Breaking News....'
},
android: {
notification: {
clickAction: 'news_intent'
}
},
apns: {
payload: {
aps: {
'category': 'INVITE_CATEGORY'
}
}
},
webpush: {
fcmOptions: {
link: 'breakingnews.html'
}
},
topic: topicName,
};
getMessaging().send(message)
.then((response) => {
// Response is a message ID string.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
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":"industry-tech",
"notification":{
"title":"Breaking News...",
},
"android":{
"notification":{
"click_action":"news_intent"
}
},
"apns":{
"payload":{
"aps":{
"category" : "INVITE_CATEGORY"
}
},
},
"webpush":{
"fcm_options":{
"link":"breakingnews.html"
}
}
}
}
Ausführliche Informationen zu den Schlüsseln, die in plattformspezifischen Blöcken im Nachrichtentext verfügbar sind, finden Sie in der Referenzdokumentation für HTTP v1.
Beispiel: Benachrichtigungsnachricht mit Lokalisierungsoptionen
In der folgenden Beispielanfrage werden dem Client Optionen für die Lokalisierung gesendet, damit er lokalisierte Nachrichten anzeigen kann. Hier eine ungefähre Darstellung des visuellen Effekts auf dem Gerät eines Nutzers:
Node.js
var topicName = 'industry-tech';
var message = {
android: {
ttl: 3600000,
notification: {
bodyLocKey: 'STOCK_NOTIFICATION_BODY',
bodyLocArgs: ['FooCorp', '11.80', '835.67', '1.43']
}
},
apns: {
payload: {
aps: {
alert: {
locKey: 'STOCK_NOTIFICATION_BODY',
locArgs: ['FooCorp', '11.80', '835.67', '1.43']
}
}
}
},
topic: topicName,
};
getMessaging().send(message)
.then((response) => {
// Response is a message ID string.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
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":"Tech",
"android":{
"ttl":"3600s",
"notification":{
"body_loc_key": "STOCK_NOTIFICATION_BODY",
"body_loc_args": ["FooCorp", "11.80", "835.67", "1.43"],
},
},
"apns":{
"payload":{
"aps":{
"alert" : {
"loc-key": "STOCK_NOTIFICATION_BODY",
"loc-args": ["FooCorp", "11.80", "835.67", "1.43"],
},
},
},
},
},
}'
Ausführliche Informationen zu den Schlüsseln, die in plattformspezifischen Blöcken im Nachrichtentext verfügbar sind, finden Sie in der HTTP v1-Referenzdokumentation.
REST-Fehlercodes für die HTTP v1 API
HTTP-Fehlerantworten für die HTTP v1 API enthalten einen Fehlercode, eine Fehlermeldung und einen Fehlerstatus.
Sie können auch ein details-Array mit weiteren Details zum Fehler enthalten.
Hier sind zwei Beispielfehlerantworten:
Beispiel 1: Fehlerantwort von einer HTTP v1-API-Anfrage mit einem ungültigen Wert in einer Datennachricht
{
"error": {
"code": 400,
"message": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [
{
"field": "message.data[0].value",
"description": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12"
}
]
}
]
}
}
Beispiel 2: Fehlerantwort von einer HTTP v1 API-Anfrage mit einem ungültigen Registrierungstoken
{
"error": {
"code": 400,
"message": "The registration token is not a valid FCM registration token",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.firebase.fcm.v1.FcmError",
"errorCode": "INVALID_ARGUMENT"
}
]
}
}
Beide Nachrichten haben denselben Code und Status, das Array „details“ enthält jedoch Werte unterschiedlicher Typen. Das erste Beispiel hat den Typ type.googleapis.com/google.rpc.BadRequest, was auf einen Fehler in den Anfragewerten hinweist. Das zweite Beispiel mit dem Typ type.googleapis.com/google.firebase.fcm.v1.FcmError enthält einen FCM-spezifischen Fehler. Bei vielen Fehlern enthält das Details-Array die Informationen, die Sie zur Fehlerbehebung und Lösung des Problems benötigen.
In der folgenden Tabelle sind die REST API-Fehlercodes für FCM v1 und ihre Beschreibungen aufgeführt.
| Fehlercode | Beschreibung und Lösungsschritte |
|---|---|
UNSPECIFIED_ERROR Weitere Informationen zu diesem Fehler sind nicht verfügbar. |
Keine. |
INVALID_ARGUMENT (HTTP-Fehlercode 400): Die Anfrageparameter waren ungültig. Es wird eine Erweiterung vom Typ google.rpc.BadRequest zurückgegeben, um anzugeben, welches Feld ungültig war. |
Mögliche Ursachen sind eine ungültige Registrierung, ein ungültiger Paketname, eine zu große Nachricht, ein ungültiger Datenschlüssel, eine ungültige TTL oder andere ungültige Parameter. Ungültige Registrierung: Überprüfe das Format des Registrierungstokens, das du an den Server übergibst. Es muss mit dem Registrierungstoken übereinstimmen, das die Clientanwendung bei der Registrierung bei FCM erhält. Kürzen Sie das Token nicht und fügen Sie keine zusätzlichen Zeichen hinzu. Ungültiger Paketname: Prüfen Sie, ob die Nachricht an ein Registrierungstoken adressiert ist, dessen Paketname mit dem in der Anfrage übergebenen Wert übereinstimmt. Nachricht zu groß: Prüfen Sie, ob die Gesamtgröße der Nutzlastdaten in einer Nachricht die FCM-Limits nicht überschreitet: 4.096 Byte für die meisten Nachrichten oder 2.048 Byte für Nachrichten an Themen. Das gilt sowohl für Schlüssel als auch für Werte. Ungültiger Datenschlüssel: Prüfen Sie, ob die Nutzlastdaten keinen Schlüssel (z. B. „from“, „gcm“ oder einen Wert mit dem Präfix „google“) enthalten, der intern von FCM verwendet wird. Einige Begriffe (z. B. „collapse_key“) werden auch von FCM verwendet, sind aber in der Nutzlast zulässig. In diesem Fall wird der Nutzlastwert vom FCM-Wert überschrieben. Ungültige TTL: Der in der TTL verwendete Wert muss eine Ganzzahl sein, die eine Dauer in Sekunden zwischen 0 und 2.419.200 (4 Wochen) darstellt. Ungültige Parameter: Prüfen Sie, ob die angegebenen Parameter den richtigen Namen und Typ haben. |
UNREGISTERED (HTTP-Fehlercode = 404) Die Registrierung der Anwendungsinstanz bei FCM wurde aufgehoben. Das bedeutet in der Regel, dass das verwendete Token nicht mehr gültig ist und ein neues verwendet werden muss. |
Dieser Fehler kann durch fehlende Registrierungstokens oder nicht registrierte Tokens verursacht werden. Fehlende Registrierung: Wenn das Ziel der Nachricht ein token-Wert ist, prüfen Sie, ob die Anfrage ein Registrierungstoken enthält.Nicht registriert: Ein vorhandenes Registrierungstoken kann in verschiedenen Szenarien nicht mehr gültig sein, z. B.: – Wenn sich die Client-App bei FCM abmeldet. – Wenn die Client-App automatisch abgemeldet wird, was passieren kann, wenn der Nutzer die Anwendung deinstalliert. Beispiel: Unter iOS hat der APNs-Feedbackdienst das APNs-Token als ungültig gemeldet. – Wenn das Registrierungstoken abläuft (z. B. wenn Google entscheidet, Registrierungstokens zu aktualisieren, oder das APNs-Token für iOS-Geräte abgelaufen ist). – Wenn die Client-App aktualisiert wurde, aber die neue Version nicht für den Empfang von Nachrichten konfiguriert ist. Entfernen Sie in all diesen Fällen dieses Registrierungstoken vom App-Server und verwenden Sie es nicht mehr, um Nachrichten zu senden. |
SENDER_ID_MISMATCH (HTTP-Fehlercode = 403) Die authentifizierte Absender-ID unterscheidet sich von der Absender-ID für das Registrierungstoken. |
Ein Registrierungstoken ist mit einer bestimmten Gruppe von Absendern verknüpft. Wenn eine Client-App für FCM registriert wird, muss angegeben werden, welche Absender Nachrichten senden dürfen. Sie sollten eine dieser Absender-IDs verwenden, wenn Sie Nachrichten an die Client-App senden. Wenn Sie zu einem anderen Absender wechseln, funktionieren die vorhandenen Registrierungstokens nicht. |
QUOTA_EXCEEDED (HTTP-Fehlercode 429): Das Sendelimit für das Nachrichtenziel wurde überschritten. Es wird eine Erweiterung vom Typ google.rpc.QuotaFailure zurückgegeben, um anzugeben, welches Kontingent überschritten wurde. |
Dieser Fehler kann durch eine Überschreitung des Nachrichtenratenkontingents, des Gerätekontingents für Nachrichtenraten oder das Überschreiten des Kontingents für die Nachrichtenrate für Themen verursacht werden. Nachrichtenrate überschritten: Die Nachrichtenrate ist zu hoch. Sie müssen die Gesamtrate, mit der Sie Nachrichten senden, reduzieren. Verwenden Sie einen exponentiellen Backoff mit einer Mindestverzögerung von 1 Minute, um abgelehnte Nachrichten noch einmal zu senden. Nachrichtenrate auf Gerät überschritten: Die Rate der an ein bestimmtes Gerät gesendete Nachrichten ist zu hoch. Weitere Informationen finden Sie unter Nachrichtenrate für ein einzelnes Gerät begrenzen. Reduzieren Sie die Anzahl der an dieses Gerät gesendeten Nachrichten und verwenden Sie exponentiellen Backoff, um den Sendeversuch zu wiederholen. Nachrichtenrate für Themen überschritten: Die Rate der Nachrichten an Abonnenten eines bestimmten Themas ist zu hoch. Reduzieren Sie die Anzahl der zu diesem Thema gesendeten Nachrichten und verwenden Sie einen exponentiellen Backoff mit einer anfänglichen Mindestverzögerung von 1 Minute, um den Sendeversuch zu wiederholen. |
UNAVAILABLE (HTTP-Fehlercode = 503) Der Server ist überlastet. |
Der Server konnte die Anfrage nicht rechtzeitig verarbeiten. Wiederholen Sie dieselbe Anfrage, aber beachten Sie Folgendes: – Beachten Sie den Header „Retry-After“, wenn er in der Antwort vom FCM-Verbindungsserver enthalten ist. – Implementieren Sie einen exponentiellen Backoff in Ihrem Wiederholungsmechanismus. Wenn Sie beispielsweise eine Sekunde vor dem ersten Wiederholungsversuch gewartet haben, warten Sie mindestens zwei Sekunden vor dem nächsten, dann vier Sekunden usw. Wenn Sie mehrere Nachrichten senden, sollten Sie das Jitter-Bild in Betracht ziehen. Weitere Informationen finden Sie unter Wiederholungsversuche verarbeiten. Absender, die Probleme verursachen, laufen Gefahr, auf die Sperrliste gesetzt zu werden. |
INTERNAL (HTTP-Fehlercode = 500) Ein unbekannter interner Fehler ist aufgetreten. |
Beim Verarbeiten der Anfrage ist ein Fehler aufgetreten. Sie können die Anfrage noch einmal senden. Folgen Sie dazu den Vorschlägen unter Wiederholungen verarbeiten. Wenn der Fehler weiterhin auftritt, wenden Sie sich bitte an den Firebase-Support. |
THIRD_PARTY_AUTH_ERROR (HTTP-Fehlercode = 401) Das APNs-Zertifikat oder der Webpush-Authentifizierungsschlüssel war ungültig oder fehlte. |
Eine Nachricht, die auf ein iOS-Gerät oder eine Web-Push-Registrierung ausgerichtet ist, konnte nicht gesendet werden. Prüfen Sie die Gültigkeit Ihrer Entwicklungs- und Produktionsanmeldedaten. |
Administrator-Fehlercodes
In der folgenden Tabelle sind die Fehlercodes der Firebase Admin FCM API und ihre Beschreibungen aufgeführt, einschließlich empfohlener Schritte zur Fehlerbehebung.
| Fehlercode | Beschreibung und Lösungsschritte |
|---|---|
messaging/invalid-argument |
Für eine FCM-Methode wurde ein ungültiges Argument angegeben. Die Fehlermeldung sollte zusätzliche Informationen enthalten. |
messaging/invalid-recipient |
Der beabsichtigte Empfänger der Nachricht ist ungültig. Die Fehlermeldung sollte zusätzliche Informationen enthalten. |
messaging/invalid-payload |
Ein ungültiges Nachrichtennutzlastobjekt wurde angegeben. Die Fehlermeldung sollte zusätzliche Informationen enthalten. |
messaging/invalid-data-payload-key |
Die Nutzlast der Datennachricht enthält einen ungültigen Schlüssel. Weitere Informationen zu eingeschränkten Schlüsseln finden Sie in der Referenzdokumentation zu DataMessagePayload.
|
messaging/payload-size-limit-exceeded |
Die Nutzlast der bereitgestellten Nachricht überschreitet die Größenbeschränkung von FCM. Für die meisten Nachrichten gilt ein Limit von 4.096 Byte. Für an Themen gesendete Nachrichten gilt ein Limit von 2.048 Byte. Die Gesamtnutzlastgröße umfasst sowohl Schlüssel als auch Werte. |
messaging/invalid-options |
Es wurde ein ungültiges Optionsobjekt für Nachrichten angegeben. Die Fehlermeldung sollte zusätzliche Informationen enthalten. |
messaging/invalid-registration-token |
Ungültiges Registrierungstoken angegeben. Es muss mit dem Registrierungstoken übereinstimmen, das die Clientanwendung bei der Registrierung bei FCM erhält. Kürzen Sie den Code nicht und fügen Sie keine zusätzlichen Zeichen hinzu. |
messaging/registration-token-not-registered |
Das angegebene Registrierungstoken ist nicht registriert. Die Registrierung eines zuvor gültigen Registrierungstokens kann aus verschiedenen Gründen aufgehoben werden. Dazu gehören:
|
messaging/invalid-package-name |
Die Nachricht wurde an ein Registrierungstoken gesendet, dessen Paketname nicht mit der angegebenen Option restrictedPackageName übereinstimmt.
|
messaging/message-rate-exceeded |
Die Anzahl der Nachrichten an ein bestimmtes Ziel ist zu hoch. Reduzieren Sie die Anzahl der an dieses Gerät oder Thema gesendeten Nachrichten und versuchen Sie nicht sofort noch einmal, eine Nachricht an dieses Ziel zu senden. |
messaging/device-message-rate-exceeded |
Die Rate der Nachrichten an ein bestimmtes Gerät ist zu hoch. Senden Sie weniger Nachrichten an dieses Gerät und versuchen Sie nicht sofort noch einmal, eine Nachricht an dieses Gerät zu senden. |
messaging/topics-message-rate-exceeded |
Die Anzahl der Nachrichten an Abonnenten eines bestimmten Themas ist zu hoch. Reduzieren Sie die Anzahl der für dieses Thema gesendeten Nachrichten und versuchen Sie nicht sofort noch einmal, eine Nachricht an dieses Thema zu senden. |
messaging/too-many-topics |
Für ein Registrierungstoken wurde die maximale Anzahl von Themen abonniert und es können keine weiteren Themen abonniert werden. |
messaging/invalid-apns-credentials |
Eine Nachricht, die auf ein Apple-Gerät ausgerichtet ist, konnte nicht gesendet werden, da das erforderliche APNs-SSL-Zertifikat nicht hochgeladen wurde oder abgelaufen ist. Prüfen Sie die Gültigkeit Ihrer Entwicklungs- und Produktionszertifikate. |
messaging/mismatched-credential |
Die Anmeldedaten, die für die Authentifizierung dieses SDK verwendet werden, sind nicht berechtigt, Nachrichten an das Gerät zu senden, das dem angegebenen Registrierungstoken entspricht. Die Anmeldedaten und das Registrierungstoken müssen zum selben Firebase-Projekt gehören. Eine Anleitung zum Authentifizieren der Firebase Admin SDKs findest du unter Firebase zu deiner App hinzufügen. |
messaging/authentication-error |
Das SDK konnte sich bei den FCM-Servern nicht authentifizieren. Authentifiziere das Firebase Admin SDK mit einem Berechtigungsnachweis, der die entsprechenden Berechtigungen zum Senden von FCM-Nachrichten hat. Eine Anleitung zum Authentifizieren der Firebase Admin SDKs findest du unter Firebase zu deiner App hinzufügen. |
messaging/server-unavailable |
Der FCM-Server konnte die Anfrage nicht rechtzeitig verarbeiten. Sie sollten dieselbe Anfrage noch einmal senden. Beachten Sie dabei Folgendes:
|
messaging/internal-error |
Auf dem FCM-Server ist beim Versuch, die Anfrage zu verarbeiten, ein Fehler aufgetreten. Sie können dieselbe Anfrage wiederholen. Beachten Sie dabei die Anforderungen, die oben in der Zeile messaging/server-unavailable aufgeführt sind. Wenn der Fehler weiterhin auftritt, melden Sie das Problem an unseren Supportkanal für Fehlerberichte.
|
messaging/unknown-error |
Es wurde ein unbekannter Serverfehler zurückgegeben. Weitere Informationen finden Sie in der Rohserverantwort in der Fehlermeldung. Wenn du diese Fehlermeldung erhältst, sende bitte die vollständige Fehlermeldung an unseren Supportkanal Bug Report. |
Nachrichten mit den alten Anwendungsserver-Protokollen senden
Wenn Sie derzeit die alten Protokolle verwenden, erstellen Sie Nachrichtenanfragen wie in diesem Abschnitt beschrieben. Wenn Sie über HTTP an mehrere Plattformen senden, kann das v1-Protokoll Ihre Nachrichtenanfragen erheblich vereinfachen.
Nachrichten an bestimmte Geräte senden
Wenn Sie Nachrichten an bestimmte Geräte senden möchten, legen Sie den Schlüssel to auf das Registrierungstoken für die jeweilige App-Instanz fest. Weitere Informationen zu Registrierungstokens findest du in der Anleitung zur Clienteinrichtung für deine Plattform.
HTTP-POST-Anfrage
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..."
}
HTTP-Antwort
{ "multicast_id": 108,
"success": 1,
"failure": 0,
"results": [
{ "message_id": "1:08" }
]
}XMPP-Nachricht
<message id="">
<gcm xmlns="google:mobile:data">
{ "data": {
"score": "5x1",
"time": "15:10"
},
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}
</gcm>
</message>
XMPP-Antwort
<message id=""> <gcm xmlns="google:mobile:data"> { "from":"REGID", "message_id":"m-1366082849205" "message_type":"ack" } </gcm> </message>
Der XMPP-Verbindungsserver bietet einige weitere Antwortoptionen. Siehe Serverantwortformat.
Eine vollständige Liste der Nachrichtenoptionen, die beim Senden von Downstream-Nachrichten an Client-Apps verfügbar sind, finden Sie in den Referenzinformationen für das ausgewählte Verbindungsserverprotokoll, HTTP oder XMPP.
Nachrichten an Themen senden
Das Senden von Nachrichten an ein Firebase Cloud Messaging-Thema ähnelt dem Senden von Nachrichten an ein einzelnes Gerät oder an eine Nutzergruppe. Der App-Server legt den Schlüssel to mit einem Wert wie /topics/yourTopic fest.
Entwickler können einen beliebigen Themennamen auswählen, der mit dem regulären Ausdruck "/topics/[a-zA-Z0-9-_.~%]+" übereinstimmt.
Wenn Nachrichten an Kombinationen mehrerer Themen gesendet werden sollen, muss der App-Server den Schlüssel condition (anstelle des Schlüssels to) auf eine boolesche Bedingung festlegen, die die Zielthemen angibt. So senden Sie beispielsweise Nachrichten an Geräte, die TopicA und entweder TopicB oder TopicC abonniert haben:
'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)Bei FCM werden zuerst alle Bedingungen in Klammern und dann der Ausdruck von links nach rechts ausgewertet. Im obigen Ausdruck erhält ein Nutzer, der ein einzelnes Thema abonniert hat, die Nachricht nicht. Ebenso erhält ein Nutzer, der Topic A nicht abonniert hat, die Nachricht nicht. In folgenden Fällen wird sie jedoch angezeigt:
- ThemaA und ThemaB
- TopicA und TopicC
Sie können bis zu fünf Themen in den bedingten Ausdruck aufnehmen. Klammern sind zulässig.
Unterstützte Operatoren: &&, ||.
HTTP-POST-Anfrage für das Thema
An ein einzelnes Thema senden:
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
An Geräte senden, die die Themen „dogs“ oder „cats“ abonniert haben:
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
HTTP-Antwort für das Thema
// Success example: { "message_id": "1023456" } // failure example: { "error": "TopicsMessageRateExceeded" }
XMPP-Nachricht zum Thema
An ein einzelnes Thema senden:
<message id="">
<gcm xmlns="google:mobile:data">
</gcm>
</message>
An Geräte senden, die die Themen „Hunde“ oder „Katzen“ abonniert haben:
<message id=""> <gcm xmlns="google:mobile:data"> </gcm> </message>
XMPP-Antwort auf das Thema
// Success example: { "message_id": "1023456" } // failure example: { "error": "TopicsMessageRateExceeded" }
Es kann bis zu 30 Sekunden dauern, bis der FCM-Server eine Antwort mit dem Status „Erfolg“ oder „Fehlschlag“ für die gesendeten Themenanfragen zurückgibt. Achten Sie darauf, den Zeitüberschreitungswert des App-Servers in der Anfrage entsprechend festzulegen.
Nachrichten an Gerätegruppen senden
Das Senden von Nachrichten an eine Gerätegruppe mithilfe der veralteten APIs ähnelt dem Senden von Nachrichten an ein einzelnes Gerät. Legen Sie den Parameter to auf den eindeutigen Benachrichtigungsschlüssel für die Gerätegruppe fest.
In den Beispielen in diesem Abschnitt wird gezeigt, wie Sie Datennachrichten an Gerätegruppen in den älteren HTTP- und XMPP-Protokollen senden.
HTTP-POST-Anfrage für Gerätegruppe
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!",
}
}HTTP-Antwort der Gerätegruppe
Hier ist ein Beispiel für „success“: Der notification_key ist mit zwei Registrierungstokens verknüpft und die Nachricht wurde an beide gesendet:
{
"success": 2,
"failure": 0
}
Hier ein Beispiel für einen „teilweisen Erfolg“: Der notification_key ist mit drei Registrierungstokens verknüpft. Die Nachricht wurde nur an eines der Registrierungstokens gesendet. In der Antwortnachricht werden die Registrierungstokens (registration_ids) aufgelistet, über die die Nachricht nicht empfangen wurde:
{ "success":1, "failure":2, "failed_registration_ids":[ "regId1", "regId2" ] }
Wenn eine Nachricht nicht an mindestens eines der Registrierungstokens gesendet werden kann, die mit einer notification_key verknüpft sind, sollte der App-Server mit einer Wartezeit zwischen den Wiederholungen einen neuen Versuch starten.
Wenn der Server versucht, eine Nachricht an eine Gerätegruppe zu senden, die keine Mitglieder hat, sieht die Antwort so aus: 0 Erfolg und 0 Fehler:
{
"success": 0,
"failure": 0
}XMPP-Nachricht für Gerätegruppe
<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>XMPP-Antwort der Gerätegruppe
Wenn die Nachricht an eines der Geräte in der Gruppe gesendet wurde, antwortet der XMPP-Verbindungsserver mit einer Bestätigung. Wenn alle an alle Geräte in der Gruppe gesendeten Nachrichten fehlschlagen, antwortet der XMPP-Verbindungsserver mit einem NACK.
Hier ist ein Beispiel für „success“: Der notification_key ist mit drei Registrierungstokens verknüpft und die Nachricht wurde an alle drei gesendet:
{ "from": "aUniqueKey", "message_type": "ack", "success": 3, "failure": 0, "message_id": "m-1366082849205" }
Hier ein Beispiel für einen „teilweisen Erfolg“: Der notification_key ist mit drei Registrierungstokens verknüpft. Die Nachricht wurde nur an eines der Registrierungstokens gesendet. In der Antwortnachricht sind die Registrierungstokens aufgeführt, für die die Nachricht nicht zugestellt werden konnte:
{ "from": "aUniqueKey", "message_type": "ack", "success":1, "failure":2, "failed_registration_ids":[ "regId1", "regId2" ] }
Wenn der FCM-Verbindungsserver keine Nachrichten an alle Geräte in der Gruppe senden kann. Der App-Server erhält eine NAK-Antwort.
Eine vollständige Liste der Nachrichtenoptionen finden Sie in den Referenzinformationen für das ausgewählte Verbindungsserverprotokoll, HTTP oder XMPP.
Firebase Admin SDK Alte Sendemethoden
Das Firebase Admin Node.js SDK unterstützt Methoden zum Senden von (FCM)-Nachrichten basierend auf der alten FCM-Server API.
Für diese Methoden werden andere Argumente als für die Methode send() verwendet.
Verwenden Sie nach Möglichkeit die Methode send() und verwenden Sie beim Senden von Nachrichten an einzelne Geräte oder Gerätegruppen nur die auf dieser Seite beschriebenen Methoden.
An einzelne Geräte senden
Sie können der Methode sendToDevice() ein Registrierungstoken übergeben, um eine Nachricht an dieses Gerät zu senden:
Node.js
// This registration token comes from the client FCM SDKs.
const registrationToken = 'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...';
// See the "Defining the message payload" section below for details
// on how to define a message payload.
const payload = {
data: {
score: '850',
time: '2:45'
}
};
// Send a message to the device corresponding to the provided
// registration token.
getMessaging().sendToDevice(registrationToken, payload)
.then((response) => {
// See the MessagingDevicesResponse reference documentation for
// the contents of response.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Mit der sendToDevice()-Methode kann auch eine Multicast-Nachricht (d. h. eine Nachricht an mehrere Geräte) gesendet werden, indem anstelle eines einzelnen Registrierungstokens ein Array von Registrierungstokens übergeben wird:
Node.js
// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...',
// ...
'ecupwIfBy1w:APA91bFtuMY7MktgxA3Au_Qx7cKqnf...'
];
// See the "Defining the message payload" section below for details
// on how to define a message payload.
const payload = {
data: {
score: '850',
time: '2:45'
}
};
// Send a message to the devices corresponding to the provided
// registration tokens.
getMessaging().sendToDevice(registrationTokens, payload)
.then((response) => {
// See the MessagingDevicesResponse reference documentation for
// the contents of response.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Die sendToDevice()-Methode gibt ein Versprechen zurück, das mit einem MessagingDevicesResponse-Objekt aufgelöst wird, das die Antwort von FCM enthält. Der Rückgabetyp hat dasselbe Format, wenn ein einzelnes Registrierungstoken oder ein Array von Registrierungstokens übergeben wird.
In einigen Fällen, z. B. bei einem Authentifizierungsfehler oder einer Ratenbegrenzung, kann die gesamte Nachricht nicht verarbeitet werden. In diesen Fällen wird das von sendToDevice() zurückgegebene Promise mit einem Fehler abgelehnt. Eine vollständige Liste der Fehlercodes, einschließlich Beschreibungen und Lösungsschritten, finden Sie unter Admin FCM API-Fehler.
An eine Gerätegruppe senden
Mit der Methode sendToDeviceGroup() können Sie eine Nachricht an eine Gerätegruppe senden, indem Sie den Benachrichtigungsschlüssel für diese Gerätegruppe angeben:
Node.js
// See the "Managing device groups" link above on how to generate a
// notification key.
const notificationKey = 'some-notification-key';
// See the "Defining the message payload" section below for details
// on how to define a message payload.
const payload = {
data: {
score: '850',
time: '2:45'
}
};
// Send a message to the device group corresponding to the provided
// notification key.
getMessaging().sendToDeviceGroup(notificationKey, payload)
.then((response) => {
// See the MessagingDeviceGroupResponse reference documentation for
// the contents of response.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Die sendToDeviceGroup()-Methode gibt ein Versprechen zurück, das mit einem MessagingDevicesResponse-Objekt aufgelöst wird, das die Antwort von FCM enthält.
In einigen Fällen, z. B. bei einem Authentifizierungsfehler oder einer Ratenbegrenzung, kann die gesamte Nachricht nicht verarbeitet werden. In diesen Fällen wird das von sendToDeviceGroup() zurückgegebene Promise mit einem Fehler abgelehnt. Eine vollständige Liste der Fehlercodes, einschließlich Beschreibungen und Schritten zur Fehlerbehebung, finden Sie unter Admin FCM API-Fehler.
Nachrichtennutzlast definieren
Die oben genannten Methoden, die auf den FCM-Legacy-Protokollen basieren, akzeptieren eine Nachrichtennutzlast als zweites Argument und unterstützen sowohl Benachrichtigungs- als auch Datennachrichten.
Sie können einen oder beide Nachrichtentypen angeben, indem Sie ein Objekt mit den Schlüsseln data und/oder notification erstellen. So definieren Sie beispielsweise verschiedene Arten von Nachrichtennutzlasten:
Benachrichtigungsnachricht
const payload = {
notification: {
title: '$FooCorp up 1.43% on the day',
body: '$FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
}
};
Datennachricht
const payload = {
data: {
score: '850',
time: '2:45'
}
};
Kombinierte Nachricht
const payload = {
notification: {
title: '$FooCorp up 1.43% on the day',
body: '$FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
},
data: {
stock: 'GOOG',
open: '829.62',
close: '635.67'
}
};
Die Nutzlasten von Benachrichtigungsnachrichten haben eine vordefinierte Teilmenge gültiger Eigenschaften und unterscheiden sich geringfügig je nach dem mobilen Betriebssystem, auf das Sie abzielen.
Eine vollständige Liste finden Sie in der Referenzdokumentation zu NotificationMessagePayload.
Nutzlasten von Datennachrichten bestehen aus benutzerdefinierten Schlüssel/Wert-Paaren mit einigen Einschränkungen, einschließlich der Tatsache, dass alle Werte Strings sein müssen. Eine vollständige Liste der Einschränkungen finden Sie in der Referenzdokumentation zu DataMessagePayload.
Nachrichtenoptionen definieren
Die oben genannten Methoden basierend auf den FCM-Legacy-Protokollen akzeptieren ein optionales drittes Argument, mit dem einige Optionen für die Nachricht angegeben werden. Im folgenden Beispiel wird beispielsweise eine Nachricht mit hoher Priorität an ein Gerät gesendet, die nach 24 Stunden abläuft:
Node.js
// This registration token comes from the client FCM SDKs.
const registrationToken = 'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...';
// See the "Defining the message payload" section above for details
// on how to define a message payload.
const 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.
const options = {
priority: 'high',
timeToLive: 60 * 60 * 24
};
// Send a message to the device corresponding to the provided
// registration token with the provided options.
getMessaging().sendToDevice(registrationToken, payload, options)
.then((response) => {
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Eine vollständige Liste der verfügbaren Optionen finden Sie in der Referenzdokumentation zu MessagingOptions.