Erstellen Sie Sendeanforderungen für App-Server

Mit den Firebase Admin SDK- oder FCM-App-Serverprotokollen können Sie Nachrichtenanfragen erstellen und diese an folgende Zieltypen senden:

  • Themenname
  • Zustand
  • Geräteregistrierungstoken
  • Gerätegruppenname (nur Protokoll)

Sie können Nachrichten mit einer Benachrichtigungsnutzlast senden, die aus vordefinierten Feldern besteht, einer Datennutzlast aus Ihren eigenen benutzerdefinierten Feldern oder einer Nachricht, die beide Nutzlasttypen enthält. Weitere Informationen finden Sie unter Nachrichtentypen .

Beispiele auf dieser Seite zeigen, wie Sie Benachrichtigungen mit dem Firebase Admin SDK (das Node , Java , Python , C# und Go unterstützt) und dem HTTP-Protokoll v1 senden. Es gibt auch Anleitungen zum Senden von Nachrichten über die veralteten alten HTTP- und XMPP-Protokolle .

Senden Sie Nachrichten an bestimmte Geräte

Um an ein einzelnes, bestimmtes Gerät zu senden, übergeben Sie das Registrierungstoken des Geräts wie gezeigt. Weitere Informationen zu Registrierungstokens finden Sie in den Client-Setup-Informationen für Ihre 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)

Gehen

// 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);

AUSRUHEN

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. Das Firebase Admin SDK gibt die ID-Zeichenfolge im Format projects/{project_id}/messages/{message_id} zurück. Die HTTP-Protokollantwort ist ein einzelner JSON-Schlüssel:

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

Senden Sie Nachrichten an mehrere Geräte

Mit den Admin-FCM-APIs können Sie eine Nachricht per Multicast an eine Liste von Geräteregistrierungstokens senden. Sie können bis zu 500 Geräteregistrierungstoken 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))

Gehen

// 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 Eingabe-Tokens entspricht. Dies ist nützlich, wenn Sie überprüfen möchten, welche Token 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))

Gehen

// 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}");
}

Senden Sie Nachrichten an Themen

Nachdem Sie ein Thema erstellt haben, entweder durch Abonnieren von Client-App-Instanzen für das Thema auf der Clientseite oder über die Server-API , können Sie Nachrichten an das Thema senden. Wenn Sie zum ersten Mal Sendeanforderungen für FCM erstellen, finden Sie im Handbuch zu Ihrer Serverumgebung und FCM wichtige Hintergrund- und Einrichtungsinformationen.

Geben Sie in Ihrer Sendelogik im Backend den gewünschten Themennamen wie 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)

Gehen

// 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);

AUSRUHEN

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

Um eine Nachricht an eine Kombination von Themen zu senden, geben Sie eine Bedingung an, bei der es sich um einen booleschen Ausdruck handelt, der die Zielthemen angibt. Die folgende Bedingung sendet beispielsweise Nachrichten an Geräte, die TopicA und entweder TopicB oder TopicC abonniert haben:

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

FCM wertet zunächst alle Bedingungen in Klammern aus und wertet dann den Ausdruck von links nach rechts aus. Im obigen Ausdruck erhält ein Benutzer, der ein einzelnes Thema abonniert hat, die Nachricht nicht. Ebenso erhält ein Benutzer, der TopicA nicht abonniert, die Nachricht nicht. Diese Kombinationen erhalten es:

  • TopicA und TopicB
  • TopicA und TopicC

Sie können bis zu fünf Themen in Ihren bedingten Ausdruck aufnehmen.

So senden Sie 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)

Gehen

// 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);

AUSRUHEN

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

Senden Sie Nachrichten an Gerätegruppen

Um Nachrichten an Gerätegruppen zu senden, verwenden Sie die HTTP v1-API. Wenn Sie derzeit mit den veralteten Legacy-Sende-APIs für HTTP oder XMPP oder einer der älteren Versionen des Firebase Admin SDK für Node.js, die auf den Legacy-Protokollen basieren, an Gerätegruppen senden, empfehlen wir Ihnen dringend, auf HTTP v1 zu migrieren API zum frühestmöglichen Zeitpunkt. Die alten Sende-APIs werden im Juni 2024 deaktiviert und entfernt.

Das Senden von Nachrichten an eine Gerätegruppe ist dem Senden von Nachrichten an ein einzelnes Gerät sehr ähnlich und verwendet dieselbe Methode zum Autorisieren von Sendeanfragen . Legen Sie das token auf den Gruppenbenachrichtigungsschlüssel fest:

AUSRUHEN

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

Senden Sie eine Reihe von Nachrichten

Die Admin-SDKs unterstützen das Senden von Nachrichten in Stapeln. Sie können bis zu 500 Nachrichten in einem einzigen Batch gruppieren und sie alle in einem einzigen API-Aufruf senden, was zu einer deutlichen Leistungsverbesserung gegenüber dem Senden separater HTTP-Anfragen für jede Nachricht führt.

Mit dieser Funktion können Sie einen benutzerdefinierten Satz von Nachrichten erstellen und diese an verschiedene Empfänger senden, einschließlich Themen oder spezifischer Geräteregistrierungstokens. Verwenden Sie diese Funktion, wenn Sie beispielsweise gleichzeitig Nachrichten an verschiedene Zielgruppen mit leicht unterschiedlichen Details im Nachrichtentext senden müssen.

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))

Gehen

// 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");

Direkte Boot-Aktivierungsnachrichten senden (nur Android)

Sie können Nachrichten an Geräte im Direktstartmodus senden, indem Sie HTTP v1 oder ältere HTTP-APIs verwenden. Stellen Sie vor dem Senden an Geräte im Direktstartmodus sicher, dass Sie die Schritte ausgeführt haben, um Clientgeräten den Empfang von FCM-Nachrichten im Direktstartmodus zu ermöglichen.

Senden Sie mit der FCM v1 HTTP-API

Die Nachrichtenanforderung muss den Schlüssel "direct_boot_ok" : true in den AndroidConfig Optionen des Anforderungstexts enthalten. Zum 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,
    },
}

Senden Sie mit der FCM-Legacy-HTTP-API

Die Nachrichtenanforderung muss den Schlüssel "direct_boot_ok" : true auf der obersten Ebene des Anforderungstexts enthalten. Zum 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 Anforderungstext gesendet werden, können von Apps auf Geräten verarbeitet werden, die sich derzeit im Direktstartmodus befinden (und auch dann, wenn dieser Modus nicht aktiviert ist).

Passen Sie Nachrichten plattformübergreifend an

Sowohl das Firebase Admin SDK als auch das HTTP-Protokoll FCM v1 ermöglichen es Ihren Nachrichtenanfragen, alle im message verfügbaren Felder festzulegen. Das beinhaltet:

  • ein gemeinsamer Satz von Feldern, der von allen App-Instanzen interpretiert werden soll, die die Nachricht empfangen.
  • Plattformspezifische Feldsätze wie AndroidConfig und WebpushConfig , die nur von App-Instanzen interpretiert werden, die auf der angegebenen Plattform ausgeführt werden.

Plattformspezifische Blöcke geben Ihnen die Flexibilität, Nachrichten für verschiedene Plattformen anzupassen, um sicherzustellen, dass sie beim Empfang korrekt verarbeitet werden. Das FCM-Backend berücksichtigt alle angegebenen Parameter und passt die Nachricht für jede Plattform an.

Wann sollten gemeinsame Felder verwendet werden?

Verwenden Sie gemeinsame Felder, wenn Sie:

  • Ausrichtung auf App-Instanzen auf allen Plattformen – Apple, Android und Web
  • Senden von Nachrichten an Themen

Alle App-Instanzen können unabhängig von der Plattform die folgenden gemeinsamen Felder interpretieren:

Wann sollten plattformspezifische Felder verwendet werden?

Verwenden Sie plattformspezifische Felder, wenn Sie Folgendes möchten:

  • Senden Sie Felder nur an bestimmte Plattformen
  • Senden Sie zusätzlich zu den allgemeinen Feldern plattformspezifische Felder

Wenn Sie Werte nur an bestimmte Plattformen senden möchten, verwenden Sie keine gemeinsamen Felder. Verwenden Sie plattformspezifische Felder. Um beispielsweise eine Benachrichtigung nur an Apple-Plattformen und das Web, nicht aber an Android zu senden, müssen Sie zwei separate Feldsätze verwenden, einen für Apple und einen für das Web.

Wenn Sie Nachrichten mit bestimmten Zustellungsoptionen senden, verwenden Sie plattformspezifische Felder, um diese festzulegen. Sie können bei Bedarf unterschiedliche Werte pro Plattform angeben. Selbst wenn Sie jedoch plattformübergreifend im Wesentlichen denselben Wert festlegen möchten, müssen Sie plattformspezifische Felder verwenden. Dies liegt daran, dass jede Plattform den Wert möglicherweise etwas anders interpretiert. Beispielsweise wird die Gültigkeitsdauer bei Android als Ablaufzeit in Sekunden festgelegt, während sie bei Apple als Ablaufdatum festgelegt wird.

Beispiel: Benachrichtigungsnachricht mit Farb- und Symboloptionen

Diese Beispiel-Sendeanforderung sendet einen gemeinsamen Benachrichtigungstitel und -inhalt an alle Plattformen, sendet aber auch einige plattformspezifische Überschreibungen an Android-Geräte.

Für Android legt die Anfrage ein spezielles Symbol und eine spezielle Farbe fest, die auf Android-Geräten angezeigt werden sollen. Wie in der Referenz für AndroidNotification erwähnt, wird die Farbe im #rrggbb-Format angegeben und das Bild muss eine zeichnbare Symbolressource lokal für die Android-App sein.

Hier ist eine Annäherung an den visuellen Effekt auf dem Gerät eines Benutzers:

Einfache Zeichnung von zwei Geräten, wobei eines ein benutzerdefiniertes Symbol und eine benutzerdefinierte Farbe anzeigt

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',
)

Gehen

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",
};

AUSRUHEN

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: Benachrichtigungsnachricht mit einem benutzerdefinierten Bild

Die folgende Beispiel-Sendeanforderung sendet einen gemeinsamen Benachrichtigungstitel an alle Plattformen, sendet aber auch ein Bild. Hier ist eine Annäherung an den visuellen Effekt auf dem Gerät eines Benutzers:

Einfaches Zeichnen eines Bildes in einer Anzeigebenachrichtigung

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);
  });

AUSRUHEN

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 HTTP v1-Referenzdokumentation .

Beispiel: Benachrichtigungsnachricht mit zugehöriger Klickaktion

Die folgende Beispiel-Sendeanforderung sendet einen gemeinsamen Benachrichtigungstitel an alle Plattformen, sendet aber auch eine Aktion, die die App als Reaktion auf die Benutzerinteraktion mit der Benachrichtigung ausführen soll. Hier ist eine Annäherung an den visuellen Effekt auf dem Gerät eines Benutzers:

Einfache Zeichnung eines Benutzertipps, der eine Webseite öffnet

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);
  });

AUSRUHEN

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 HTTP v1-Referenzdokumentation .

Beispiel: Benachrichtigungsnachricht mit Lokalisierungsoptionen

Die folgende Beispiel-Sendeanforderung sendet Lokalisierungsoptionen für den Client, um lokalisierte Nachrichten anzuzeigen. Hier ist eine Annäherung an den visuellen Effekt auf dem Gerät eines Benutzers:

Einfache Zeichnung zweier Geräte, die Text in Englisch und Spanisch anzeigen

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);
  });

AUSRUHEN

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 .

Admin-Fehlercodes

In der folgenden Tabelle sind die Fehlercodes der Firebase Admin FCM API und ihre Beschreibungen aufgeführt, einschließlich empfohlener Lösungsschritte.

Fehlercode Beschreibung und Lösungsschritte
messaging/invalid-argument Für eine FCM-Methode wurde ein ungültiges Argument bereitgestellt. Die Fehlermeldung sollte zusätzliche Informationen enthalten.
messaging/invalid-recipient Der beabsichtigte Nachrichtenempfänger ist ungültig. Die Fehlermeldung sollte zusätzliche Informationen enthalten.
messaging/invalid-payload Es wurde ein ungültiges Nachrichtennutzlastobjekt bereitgestellt. Die Fehlermeldung sollte zusätzliche Informationen enthalten.
messaging/invalid-data-payload-key Die Nutzlast der Datennachricht enthält einen ungültigen Schlüssel. Informationen zu eingeschränkten Schlüsseln finden Sie in der Referenzdokumentation für DataMessagePayload .
messaging/payload-size-limit-exceeded Die bereitgestellte Nachrichtennutzlast überschreitet die FCM-Größenbeschränkungen. Für die meisten Nachrichten liegt die Grenze bei 4096 Byte. Für an Themen gesendete Nachrichten beträgt die Grenze 2048 Byte. Die Gesamtnutzlastgröße umfasst sowohl Schlüssel als auch Werte.
messaging/invalid-options Es wurde ein ungültiges Nachrichtenoptionsobjekt bereitgestellt. Die Fehlermeldung sollte zusätzliche Informationen enthalten.
messaging/invalid-registration-token Ungültiges Registrierungstoken bereitgestellt. Stellen Sie sicher, dass es mit dem Registrierungstoken übereinstimmt, das die Client-App durch die Registrierung bei FCM erhält. Schneiden Sie es nicht ab und fügen Sie keine weiteren Zeichen hinzu.
messaging/registration-token-not-registered Das bereitgestellte Registrierungstoken ist nicht registriert. Die Registrierung eines zuvor gültigen Registrierungs-Tokens kann aus verschiedenen Gründen aufgehoben werden, darunter:
  • Die Client-App hat sich selbst bei FCM abgemeldet.
  • Die Client-App wurde automatisch abgemeldet. Dies kann passieren, wenn der Benutzer die Anwendung deinstalliert oder, auf Apple-Plattformen, wenn der APNs-Feedback-Dienst das APNs-Token als ungültig meldet.
  • Das Registrierungstoken ist abgelaufen. Beispielsweise könnte Google beschließen, die Registrierungstokens zu aktualisieren, oder das APNs-Token könnte für Apple-Geräte abgelaufen sein.
  • Die Client-App wurde aktualisiert, aber die neue Version ist nicht für den Empfang von Nachrichten konfiguriert.
Entfernen Sie in all diesen Fällen dieses Registrierungstoken und verwenden Sie es nicht mehr zum Senden von Nachrichten.
messaging/invalid-package-name Die Nachricht war an ein Registrierungstoken gerichtet, dessen Paketname nicht mit der bereitgestellten Option restrictedPackageName übereinstimmt.
messaging/message-rate-exceeded Die Nachrichtenrate 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 erneut, an dieses Ziel zu senden.
messaging/device-message-rate-exceeded Die Nachrichtenrate an ein bestimmtes Gerät ist zu hoch. Reduzieren Sie die Anzahl der an dieses Gerät gesendeten Nachrichten und versuchen Sie nicht sofort erneut, sie an dieses Gerät zu senden.
messaging/topics-message-rate-exceeded Die Nachrichtenrate an Abonnenten zu einem bestimmten Thema ist zu hoch. Reduzieren Sie die Anzahl der für dieses Thema gesendeten Nachrichten und versuchen Sie nicht sofort erneut, an dieses Thema zu senden.
messaging/too-many-topics Ein Registrierungstoken wurde für die maximale Anzahl an Themen abonniert und kann nicht mehr abonniert werden.
messaging/invalid-apns-credentials Eine an ein Apple-Gerät gerichtete Nachricht konnte nicht gesendet werden, da das erforderliche APNs-SSL-Zertifikat nicht hochgeladen wurde oder abgelaufen ist. Überprüfen Sie die Gültigkeit Ihrer Entwicklungs- und Produktionszertifikate.
messaging/mismatched-credential Die zur Authentifizierung dieses SDK verwendeten Anmeldeinformationen verfügen nicht über die Berechtigung, Nachrichten an das Gerät zu senden, das dem bereitgestellten Registrierungstoken entspricht. Stellen Sie sicher, dass die Anmeldeinformationen und das Registrierungstoken beide zum selben Firebase-Projekt gehören. Eine Dokumentation zur Authentifizierung der Firebase Admin SDKs finden Sie unter „Firebase zu Ihrer App hinzufügen“ .
messaging/authentication-error Das SDK konnte sich nicht bei den FCM-Servern authentifizieren. Stellen Sie sicher, dass Sie das Firebase Admin SDK mit Anmeldeinformationen authentifizieren, die über die entsprechenden Berechtigungen zum Senden von FCM-Nachrichten verfügen. Eine Dokumentation zur Authentifizierung der Firebase Admin SDKs finden Sie unter „Firebase zu Ihrer App hinzufügen“ .
messaging/server-unavailable Der FCM-Server konnte die Anfrage nicht rechtzeitig verarbeiten. Sie sollten dieselbe Anfrage erneut versuchen, müssen jedoch Folgendes tun:
  • Berücksichtigen Sie den Retry-After Header, 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 und so weiter. Wenn Sie mehrere Nachrichten senden, verzögern Sie jede einzeln um einen zusätzlichen zufälligen Betrag, um zu vermeiden, dass für alle Nachrichten gleichzeitig eine neue Anfrage gesendet wird.
Absender, die Probleme verursachen, laufen Gefahr, auf die schwarze Liste gesetzt zu werden.
messaging/internal-error Beim Versuch, die Anfrage zu verarbeiten, ist auf dem FCM-Server ein Fehler aufgetreten. Sie können dieselbe Anfrage erneut versuchen, indem Sie die oben in der Zeile messaging/server-unavailable aufgeführten Anforderungen befolgen. Wenn der Fehler weiterhin besteht, melden Sie das Problem bitte unserem Bug Report- Supportkanal.
messaging/unknown-error Es wurde ein unbekannter Serverfehler zurückgegeben. Weitere Einzelheiten finden Sie in der Rohserverantwort in der Fehlermeldung. Wenn Sie diesen Fehler erhalten, melden Sie bitte die vollständige Fehlermeldung an unseren Bug Report- Supportkanal.

Senden Sie Nachrichten mit den alten App-Server-Protokollen

Wenn Sie derzeit die Legacy-Protokolle verwenden, erstellen Sie Nachrichtenanforderungen wie in diesem Abschnitt gezeigt. Beachten Sie, dass das v1-Protokoll Ihre Nachrichtenanfragen erheblich vereinfachen kann, wenn Sie über HTTP an mehrere Plattformen senden.

Senden Sie Nachrichten an bestimmte Geräte

Um Nachrichten an bestimmte Geräte zu senden, legen Sie den to Schlüssel auf das Registrierungstoken für die spezifische App-Instanz fest. Weitere Informationen zu Registrierungstokens finden Sie in den Client-Setup-Informationen für Ihre 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 Optionen für Antworten. Siehe Server-Antwortformat .

Die 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 von Ihnen gewählte Verbindungsserverprotokoll ( HTTP oder XMPP) .

Senden Sie Nachrichten an Themen

Das Senden von Nachrichten an ein Firebase Cloud Messaging-Thema ähnelt dem Senden von Nachrichten an ein einzelnes Gerät oder eine Benutzergruppe. Der App-Server setzt den to auf einen Wert wie /topics/yourTopic . Entwickler können einen beliebigen Themennamen wählen, der dem regulären Ausdruck entspricht: "/topics/[a-zA-Z0-9-_.~%]+" .

Um an Kombinationen mehrerer Themen zu senden, muss der App-Server den condition (anstelle des Schlüssels to ) auf eine boolesche Bedingung setzen, die die Zielthemen angibt. Um beispielsweise Nachrichten an Geräte zu senden, die TopicA und entweder TopicB oder TopicC abonniert haben:

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

FCM wertet zunächst alle Bedingungen in Klammern aus und wertet dann den Ausdruck von links nach rechts aus. Im obigen Ausdruck erhält ein Benutzer, der ein einzelnes Thema abonniert hat, die Nachricht nicht. Ebenso erhält ein Benutzer, der TopicA nicht abonniert, die Nachricht nicht. Diese Kombinationen erhalten es:

  • ThemaA und ThemaB
  • ThemaA und ThemaC

Sie können bis zu fünf Themen in Ihren bedingten Ausdruck aufnehmen und Klammern werden unterstützt. Unterstützte Operatoren: && , || .

Thema HTTP POST-Anfrage

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 „Hunde“ oder „Katzen“ abonniert haben:

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


Thema HTTP-Antwort

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

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

Thema XMPP-Nachricht

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>

Thema XMPP-Antwort

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

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

Es kann mit einer Verzögerung von bis zu 30 Sekunden rechnen, bevor der FCM-Server eine Erfolgs- oder Fehlerantwort auf die Sendeanforderungen des Themas zurückgibt. Stellen Sie sicher, dass Sie den Timeout-Wert des App-Servers in der Anfrage entsprechend festlegen.

Senden Sie Nachrichten an Gerätegruppen

Das Senden von Nachrichten an eine Gerätegruppe mithilfe der veralteten Legacy-APIs ist dem Senden von Nachrichten an ein einzelnes Gerät sehr ähnlich. Legen Sie den to Parameter auf den eindeutigen Benachrichtigungsschlüssel für die Gerätegruppe fest. Beispiele in diesem Abschnitt zeigen, wie Datennachrichten an Gerätegruppen in den alten HTTP- und XMPP-Protokollen gesendet werden.

HTTP-POST-Anfrage der 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 „Erfolg“ – dem notification_key sind zwei Registrierungstoken zugeordnet und die Nachricht wurde erfolgreich an beide gesendet:

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

Hier ist ein Beispiel für einen „Teilerfolg“ – mit dem notification_key sind drei Registrierungstoken verknüpft. Die Nachricht wurde nur an eines der Registrierungstokens erfolgreich gesendet. Die Antwortnachricht listet die Registrierungstoken ( registration_ids ) auf, die die Nachricht nicht empfangen konnten:

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

Wenn eine Nachricht nicht an eines oder mehrere der mit einem notification_key verknüpften Registrierungstokens übermittelt werden kann, sollte der App-Server es mit Backoff zwischen den Wiederholungsversuchen erneut versuchen.

Wenn der Server versucht, eine Nachricht an eine Gerätegruppe zu senden, die keine Mitglieder hat, sieht die Antwort wie folgt aus, mit 0 Erfolg und 0 Fehler:

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

XMPP-Nachricht der 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 erfolgreich 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 „Erfolg“ – dem notification_key sind drei Registrierungstoken zugeordnet und die Nachricht wurde erfolgreich an alle gesendet:

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

Hier ist ein Beispiel für einen „Teilerfolg“ – mit dem notification_key sind drei Registrierungstoken verknüpft. Die Nachricht wurde nur an eines der Registrierungstokens erfolgreich gesendet. Die Antwortnachricht listet die Registrierungstoken auf, die die Nachricht nicht empfangen konnten:

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

Wenn der FCM-Verbindungsserver nicht alle Geräte in der Gruppe beliefern kann. Der App-Server erhält eine Nack-Antwort.

Die vollständige Liste der Nachrichtenoptionen finden Sie in den Referenzinformationen für das von Ihnen gewählte Verbindungsserverprotokoll ( HTTP oder XMPP) .

Ältere Sendemethoden des Firebase Admin SDK

Das Firebase Admin Node.js SDK unterstützt Methoden zum Senden von (FCM-)Nachrichten basierend auf der Legacy-FCM-Server-API . Diese Methoden akzeptieren andere Argumente als die send() Methode. Sie sollten nach Möglichkeit die Methode send() verwenden und beim Senden von Nachrichten an einzelne Geräte oder Gerätegruppen nur die auf dieser Seite beschriebenen Methoden verwenden.

An einzelne Geräte senden

Sie können ein Registrierungstoken an die sendToDevice() Methode ü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);
  });

Die sendToDevice() Methode kann auch eine Multicast- Nachricht (d. h. eine Nachricht an mehrere Geräte) senden, indem sie ein Array von Registrierungstokens anstelle nur eines einzelnen Registrierungstokens übergibt:

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 Registrierungstoken übergeben wird.

B. ein Authentifizierungsfehler oder eine Ratenbegrenzung, führen dazu, dass die gesamte Nachricht nicht verarbeitet werden kann. In diesen Fällen wird das von sendToDevice() zurückgegebene Versprechen mit einem Fehler abgelehnt. Eine vollständige Liste der Fehlercodes, einschließlich Beschreibungen und Lösungsschritte, 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 Methode sendToDeviceGroup() gibt ein Versprechen zurück, das mit einem MessagingDevicesResponse Objekt aufgelöst wird, das die Antwort von FCM enthält.

B. ein Authentifizierungsfehler oder eine Ratenbegrenzung, führen dazu, dass die gesamte Nachricht nicht verarbeitet werden kann. In diesen Fällen wird das von sendToDeviceGroup() zurückgegebene Versprechen mit einem Fehler abgelehnt. Eine vollständige Liste der Fehlercodes, einschließlich Beschreibungen und Lösungsschritte, finden Sie unter Admin-FCM-API-Fehler .

Definieren der Nachrichtennutzlast

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 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'
  }
};

Nutzlasten für Benachrichtigungsnachrichten verfügen über eine vordefinierte Teilmenge gültiger Eigenschaften und unterscheiden sich geringfügig, je nachdem, auf welches mobile Betriebssystem Sie abzielen. Eine vollständige Liste finden Sie in den Referenzdokumenten für NotificationMessagePayload .

Nutzdaten von Datennachrichten bestehen aus benutzerdefinierten Schlüssel-Wert-Paaren mit einigen Einschränkungen, einschließlich der Tatsache, dass alle Werte Zeichenfolgen sein müssen. Eine vollständige Liste der Einschränkungen finden Sie in den Referenzdokumenten für DataMessagePayload .

Definieren der Nachrichtenoptionen

Die oben genannten Methoden, die auf den FCM-Legacy-Protokollen basieren, akzeptieren ein optionales drittes Argument, das einige Optionen für die Nachricht angibt. 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 den Referenzdokumenten für MessagingOptions .