À l'aide des protocoles de serveur d'application Firebase Admin SDK ou FCM, vous pouvez créer des requêtes de message et les envoyer à ces types de cibles:
- Nom du sujet
- Condition
- Jeton d'enregistrement de l'appareil
- Nom du groupe d'appareils (protocole uniquement)
Vous pouvez envoyer des messages avec une charge utile de notification composée de champs prédéfinis, une charge utile de données composée de vos propres champs définis par l'utilisateur ou un message contenant les deux types de charge utile. Pour en savoir plus, consultez la section Types de messages.
Les exemples de cette page montrent comment envoyer des messages de notification à l'aide de Firebase Admin SDK (compatible avec Node, Java, Python, C# et Go) et du protocole HTTP v1. Vous trouverez également des conseils pour envoyer des messages via les anciens protocoles HTTP et XMPP obsolètes.
Envoyer des messages à des appareils spécifiques
Pour envoyer un message à un seul appareil spécifique, transmettez le jeton d'enregistrement de l'appareil comme indiqué. Pour en savoir plus sur les jetons d'enregistrement, consultez les informations de configuration du client pour votre plate-forme.
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"
}
}
}
Commande cURL:
curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
"notification":{
"title":"FCM Message",
"body":"This is an FCM Message"
},
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send
En cas de réussite, chaque méthode d'envoi renvoie un ID de message. Firebase Admin SDK renvoie la chaîne d'ID au format projects/{project_id}/messages/{message_id}.
La réponse du protocole HTTP est une seule clé JSON:
{
"name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
}
Envoyer des messages à plusieurs appareils
Les API FCM de l'administrateur vous permettent de diffuser un message à une liste de jetons d'enregistrement d'appareils. Vous pouvez spécifier jusqu'à 500 jetons d'enregistrement d'appareil par appel.
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");
La valeur renvoyée est une liste de jetons correspondant à l'ordre des jetons d'entrée. Cela est utile lorsque vous souhaitez vérifier quels jetons ont généré des erreurs.
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}");
}
Envoyer des messages aux sujets
Une fois que vous avez créé un sujet, soit en abonnant des instances d'application cliente au sujet côté client, soit via l'API du serveur, vous pouvez envoyer des messages au sujet. Si vous créez des requêtes d'envoi pour FCM pour la première fois, consultez le guide sur votre environnement serveur et FCM pour obtenir des informations importantes sur le contexte et la configuration.
Dans votre logique d'envoi sur le backend, spécifiez le nom de sujet souhaité comme indiqué:
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"
}
}
}
Commande cURL:
curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message": {
"topic" : "foo-bar",
"notification": {
"body": "This is a Firebase Cloud Messaging Topic Message!",
"title": "FCM Message"
}
}
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Pour envoyer un message à une combinaison de sujets, spécifiez une condition, qui est une expression booléenne qui spécifie les sujets cibles. Par exemple, la condition suivante envoie des messages aux appareils abonnés à TopicA et à TopicB ou TopicC:
"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"
FCM évalue d'abord les conditions entre parenthèses, puis l'expression de gauche à droite. Dans l'expression ci-dessus, un utilisateur abonné à un seul sujet ne reçoit pas le message. De même, un utilisateur qui ne s'abonne pas à TopicA ne reçoit pas le message. Ces combinaisons le reçoivent:
TopicAetTopicBTopicAetTopicC
Vous pouvez inclure jusqu'à cinq thèmes dans votre expression conditionnelle.
Pour envoyer un message à une condition:
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",
}
}
}
Commande cURL:
curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"notification": {
"title": "FCM Message",
"body": "This is a Firebase Cloud Messaging Topic Message!",
},
"condition": "'dogs' in topics || 'cats' in topics"
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Envoyer des messages à des groupes d'appareils
Pour envoyer des messages à des groupes d'appareils, utilisez l'API HTTP v1. Si vous envoyez actuellement des messages à des groupes d'appareils à l'aide des anciennes API d'envoi obsolètes pour HTTP ou XMPP, ou de l'une des anciennes versions de Firebase Admin SDK pour Node.js basées sur les anciens protocoles, nous vous recommandons vivement de migrer vers l'API HTTP v1 dès que possible. Les anciennes API d'envoi seront désactivées et supprimées en juin 2024.
L'envoi de messages à un groupe d'appareils est très semblable à l'envoi de messages à un appareil individuel. La même méthode est utilisée pour autoriser les requêtes d'envoi. Définissez le champ token sur la clé de notification de groupe:
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!"
}
}
}
Commande cURL
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
Envoyer un lot de messages
Les SDK Admin permettent d'envoyer des messages par lot. Vous pouvez regrouper jusqu'à 500 messages dans un seul lot et les envoyer tous dans un seul appel d'API, ce qui améliore considérablement les performances par rapport à l'envoi de requêtes HTTP distinctes pour chaque message.
Cette fonctionnalité permet de créer un ensemble de messages personnalisés et de les envoyer à différents destinataires, y compris des sujets ou des jetons d'enregistrement d'appareil spécifiques. Utilisez cette fonctionnalité lorsque, par exemple, vous devez envoyer simultanément des messages à différentes audiences avec des détails légèrement différents dans le corps du message.
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");
Envoyer des messages directs compatibles avec le démarrage (Android uniquement)
Vous pouvez envoyer des messages aux appareils en mode démarrage direct à l'aide des API HTTP v1 ou des anciennes API HTTP. Avant d'envoyer des messages aux appareils en mode démarrage direct, assurez-vous d'avoir suivi la procédure permettant aux appareils clients de recevoir des messages FCM en mode démarrage direct.
Envoyer des notifications à l'aide de l'API HTTP FCM v1
La requête de message doit inclure la clé "direct_boot_ok" : true dans les options AndroidConfig du corps de la requête. Exemple :
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,
},
}
Envoyer à l'aide de l'ancienne API HTTP FCM
La requête de message doit inclure la clé "direct_boot_ok" : true au niveau supérieur du corps de la requête. Exemple :
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
}
Les messages envoyés avec cette clé dans le corps de la requête peuvent être gérés par les applications sur les appareils actuellement en mode Démarrage direct (et aussi lorsqu'ils ne sont pas dans ce mode).
Personnaliser les messages sur plusieurs plates-formes
Le protocole HTTP Firebase Admin SDK et le protocole HTTP FCM v1 permettent tous deux à vos requêtes de messages de définir tous les champs disponibles dans l'objet message. Par exemple :
- un ensemble commun de champs à interpréter par toutes les instances d'application qui reçoivent le message.
- Ensembles de champs spécifiques à la plate-forme, tels que
AndroidConfigetWebpushConfig, interprétés uniquement par les instances d'application exécutées sur la plate-forme spécifiée.
Les blocs spécifiques à la plate-forme vous permettent de personnaliser les messages pour différentes plates-formes afin de vous assurer qu'ils sont correctement gérés lorsqu'ils sont reçus. Le backend FCM tiendra compte de tous les paramètres spécifiés et personnalisera le message pour chaque plate-forme.
Quand utiliser des champs courants ?
Utilisez des champs courants lorsque vous:
- Cibler les instances d'application sur toutes les plates-formes (Apple, Android et Web)
- Envoyer des messages aux sujets
Toutes les instances d'application, quelle que soit la plate-forme, peuvent interpréter les champs courants suivants:
Quand utiliser des champs spécifiques à la plate-forme ?
Utilisez des champs spécifiques à la plate-forme lorsque vous souhaitez:
- Envoyer des champs uniquement à des plates-formes spécifiques
- Envoyer des champs spécifiques à la plate-forme en plus des champs communs
Lorsque vous souhaitez envoyer des valeurs uniquement à des plates-formes spécifiques, n'utilisez pas de champs communs, mais des champs spécifiques à la plate-forme. Par exemple, pour envoyer une notification uniquement aux plates-formes Apple et au Web, mais pas à Android, vous devez utiliser deux ensembles de champs distincts, l'un pour Apple et l'autre pour le Web.
Lorsque vous envoyez des messages avec des options de distribution spécifiques, utilisez des champs spécifiques à la plate-forme pour les définir. Si vous le souhaitez, vous pouvez spécifier des valeurs différentes par plate-forme. Toutefois, même si vous souhaitez définir essentiellement la même valeur sur toutes les plates-formes, vous devez utiliser des champs spécifiques à la plate-forme. En effet, chaque plate-forme peut interpréter la valeur légèrement différemment. Par exemple, la valeur de la durée de vie est définie sur Android comme une heure d'expiration en secondes, tandis qu'elle est définie sur Apple comme une date d'expiration.
Exemple: message de notification avec des options de couleur et d'icône
Cet exemple de requête d'envoi envoie un titre et un contenu de notification communs à toutes les plates-formes, mais il envoie également des forçages spécifiques à la plate-forme aux appareils Android.
Pour Android, la demande définit une icône et une couleur spéciales à afficher sur les appareils Android. Comme indiqué dans la documentation de AndroidNotification, la couleur est spécifiée au format #rrggbb, et l'image doit être une ressource d'icône drawable locale pour l'application Android.
Voici une approximation de l'effet visuel sur l'appareil d'un utilisateur:
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"
}
}
}
}
Pour en savoir plus sur les clés disponibles dans les blocs spécifiques à la plate-forme dans le corps du message, consultez la documentation de référence HTTP v1.
Exemple: message de notification avec une image personnalisée
L'exemple de requête d'envoi suivant envoie un titre de notification commun à toutes les plates-formes, mais également une image. Voici une approximation de l'effet visuel sur l'appareil d'un utilisateur:
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"
}
}
}
}
Pour en savoir plus sur les clés disponibles dans les blocs spécifiques à la plate-forme dans le corps du message, consultez la documentation de référence HTTP v1.
Exemple: message de notification avec une action de clic associée
L'exemple de requête d'envoi suivant envoie un titre de notification commun à toutes les plates-formes, mais envoie également une action à effectuer par l'application en réponse à l'interaction de l'utilisateur avec la notification. Voici une approximation de l'effet visuel sur l'appareil d'un utilisateur:
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"
}
}
}
}
Pour en savoir plus sur les clés disponibles dans les blocs spécifiques à la plate-forme dans le corps du message, consultez la documentation de référence HTTP v1.
Exemple: message de notification avec options de localisation
L'exemple de requête d'envoi suivant envoie des options de localisation pour que le client affiche des messages localisés. Voici une approximation de l'effet visuel sur l'appareil d'un utilisateur:
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"],
},
},
},
},
},
}'
Pour en savoir plus sur les clés disponibles dans les blocs spécifiques à la plate-forme dans le corps du message, consultez la documentation de référence HTTP v1.
Codes d'erreur REST pour l'API HTTP v1
Les réponses d'erreur HTTP de l'API HTTP v1 contiennent un code d'erreur, un message d'erreur et un état d'erreur.
Ils peuvent également contenir un tableau details contenant plus de détails sur l'erreur.
Voici deux exemples de réponses d'erreur:
Exemple 1: Réponse d'erreur d'une requête API HTTP v1 avec une valeur non valide dans un message de données
{
"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"
}
]
}
]
}
}
Exemple 2: Réponse d'erreur d'une requête API HTTP v1 avec un jeton d'enregistrement non valide
{
"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"
}
]
}
}
Notez que les deux messages ont le même code et le même état, mais que le tableau des détails contient des valeurs de différents types. Le premier exemple a le type type.googleapis.com/google.rpc.BadRequest, ce qui indique une erreur dans les valeurs de la requête. Le deuxième exemple avec le type type.googleapis.com/google.firebase.fcm.v1.FcmError présente une erreur spécifique à FCM. Pour de nombreuses erreurs, le tableau "details" contient les informations dont vous avez besoin pour déboguer et trouver une solution.
Le tableau suivant répertorie les codes d'erreur de l'API REST FCM v1 et leurs descriptions.
| Code d'erreur | Description et étapes de résolution |
|---|---|
UNSPECIFIED_ERROR Aucune autre information n'est disponible sur cette erreur. |
Aucune. |
INVALID_ARGUMENT (code d'erreur HTTP = 400) Les paramètres de requête n'étaient pas valides. Une extension de type google.rpc.BadRequest est renvoyée pour spécifier quel champ n'était pas valide. |
Les causes potentielles incluent un enregistrement non valide, un nom de package non valide, un message trop volumineux, une clé de données non valide, une valeur TTL non valide ou d'autres paramètres non valides. Enregistrement non valide: vérifiez le format du jeton d'enregistrement que vous transmettez au serveur. Assurez-vous qu'il correspond au jeton d'enregistrement que l'application cliente reçoit lors de son enregistrement auprès de FCM. Ne le coupez pas ni n'ajoutez de caractères supplémentaires. Nom de package non valide: assurez-vous que le message a été adressé à un jeton d'enregistrement dont le nom de package correspond à la valeur transmise dans la requête. Message trop volumineux: vérifiez que la taille totale des données de charge utile incluses dans un message ne dépasse pas les limites FCM: 4 096 octets pour la plupart des messages ou 2 048 octets dans le cas des messages destinés à des sujets. Cela inclut les clés et les valeurs. Clé de données non valide: vérifiez que les données de la charge utile ne contiennent pas de clé (par exemple, "from", "gcm" ou toute valeur précédée du préfixe "google") utilisée en interne par FCM. Notez que certains mots (tels que collapse_key) sont également utilisés par FCM, mais sont autorisés dans la charge utile. Dans ce cas, la valeur de la charge utile sera remplacée par la valeur FCM. Valeur TTL incorrecte: vérifiez que la valeur utilisée dans ttl est un entier représentant une durée en secondes comprise entre 0 et 2 419 200 (4 semaines). Paramètres non valides: vérifiez que les paramètres fournis ont le bon nom et le bon type. |
UNREGISTERED (code d'erreur HTTP = 404) L'instance de l'application n'a pas été enregistrée auprès de FCM. Cela signifie généralement que le jeton utilisé n'est plus valide et qu'un nouveau doit être utilisé. |
Cette erreur peut être due à des jetons d'enregistrement manquants ou non enregistrés. Enregistrement manquant: si la cible du message est une valeur token, vérifiez que la requête contient un jeton d'enregistrement.Non enregistré: un jeton d'enregistrement existant peut cesser d'être valide dans un certain nombre de scénarios, par exemple: - Si l'application cliente se désinscrit de FCM. - Si l'application cliente est automatiquement désinscrite, ce qui peut se produire si l'utilisateur désinstalle l'application. Par exemple, sur iOS, si le service de commentaires APNs a signalé que le jeton APNs était non valide. - Si le jeton d'enregistrement expire (par exemple, Google peut décider d'actualiser les jetons d'enregistrement ou le jeton APN a expiré pour les appareils iOS). - Si l'application cliente est mise à jour, mais que la nouvelle version n'est pas configurée pour recevoir des messages. Dans tous ces cas, supprimez ce jeton d'enregistrement du serveur de l'application et cessez de l'utiliser pour envoyer des messages. |
SENDER_ID_MISMATCH (code d'erreur HTTP = 403) L'ID d'expéditeur authentifié est différent de l'ID d'expéditeur du jeton d'enregistrement. |
Un jeton d'enregistrement est associé à un certain groupe d'expéditeurs. Lorsqu'une application cliente s'inscrit à FCM, elle doit spécifier les expéditeurs autorisés à envoyer des messages. Vous devez utiliser l'un de ces ID d'expéditeur lorsque vous envoyez des messages à l'application cliente. Si vous passez à un autre expéditeur, les jetons d'enregistrement existants ne fonctionneront pas. |
QUOTA_EXCEEDED (code d'erreur HTTP = 429) La limite d'envoi a été dépassée pour la cible du message. Une extension de type google.rpc.QuotaFailure est renvoyée pour spécifier le quota dépassé. |
Cette erreur peut être due à un dépassement du quota de débit de messages, du quota de débit de messages par appareil ou du quota de débit de messages par sujet. Taux de messages dépassé: le taux d'envoi des messages est trop élevé. Vous devez réduire le taux global d'envoi de messages. Utilisez un intervalle exponentiel entre les tentatives avec un délai initial minimal d'une minute pour relancer les messages rejetés. Taux de messages de l'appareil dépassé: le taux de messages envoyés à un appareil particulier est trop élevé. Consultez la section Limite de débit des messages sur un seul appareil. Réduisez le nombre de messages envoyés à cet appareil et utilisez un intervalle exponentiel entre les tentatives pour renvoyer l'envoi. Taux de messages par sujet dépassé: le taux de messages envoyés aux abonnés d'un sujet particulier est trop élevé. Réduisez le nombre de messages envoyés pour ce sujet et utilisez un délai exponentiel entre les tentatives avec un délai initial minimal d'une minute. |
UNAVAILABLE (code d'erreur HTTP = 503) Le serveur est surchargé. |
Le serveur n'a pas pu traiter la requête à temps. Réessayez la même requête, mais vous devez: - Respecter l'en-tête Retry-After s'il est inclus dans la réponse du serveur de connexion FCM. - Implémentez un intervalle exponentiel entre les tentatives dans votre mécanisme de nouvelle tentative. (par exemple, si vous avez attendu une seconde avant la première nouvelle tentative, attendez au moins deux secondes avant la suivante, puis quatre secondes, et ainsi de suite). Si vous envoyez plusieurs messages, envisagez d'appliquer un jitter. Pour en savoir plus, consultez la section Gérer les nouvelles tentatives. Les expéditeurs qui causent des problèmes risquent d'être ajoutés à la liste de blocage. |
INTERNAL (code d'erreur HTTP = 500) Une erreur interne inconnue s'est produite. |
Le serveur a rencontré une erreur lors du traitement de la requête. Vous pouvez relancer la même requête en suivant les suggestions de la section Gérer les nouvelles tentatives. Si l'erreur persiste, veuillez contacter l'assistance Firebase. |
THIRD_PARTY_AUTH_ERROR (code d'erreur HTTP = 401) Le certificat APN ou la clé d'authentification Web Push n'étaient pas valides ou manquaient. |
Il n'a pas été possible d'envoyer un message ciblé sur un appareil iOS ni d'enregistrer un push Web. Vérifiez la validité de vos identifiants de développement et de production. |
Codes d'erreur pour les administrateurs
Le tableau suivant répertorie les codes d'erreur de l'API FCM Firebase Admin et leurs descriptions, y compris les étapes de résolution recommandées.
| Code d'erreur | Description et étapes de résolution |
|---|---|
messaging/invalid-argument |
Vous avez fourni un argument incorrect à une méthode FCM. Le message d'erreur doit contenir des informations supplémentaires. |
messaging/invalid-recipient |
Le destinataire du message prévu n'est pas valide. Le message d'erreur doit contenir des informations supplémentaires. |
messaging/invalid-payload |
Un objet de charge utile de message non valide a été fourni. Le message d'erreur doit contenir des informations supplémentaires. |
messaging/invalid-data-payload-key |
La charge utile du message de données contient une clé non valide. Pour en savoir plus sur les clés limitées, consultez la documentation de référence sur
DataMessagePayload.
|
messaging/payload-size-limit-exceeded |
La charge utile du message fournie dépasse les limites de taille FCM. La limite est de 4 096 octets pour la plupart des messages. Pour les messages envoyés à des sujets, la limite est de 2 048 octets. La taille totale de la charge utile inclut à la fois les clés et les valeurs. |
messaging/invalid-options |
Un objet d'options de message non valide a été fourni. Le message d'erreur doit contenir des informations supplémentaires. |
messaging/invalid-registration-token |
Le jeton d'enregistrement fourni n'est pas valide. Assurez-vous qu'il correspond au jeton d'enregistrement que l'application cliente reçoit lors de son enregistrement auprès de FCM. Ne le coupez pas ni n'ajoutez-y de caractères supplémentaires. |
messaging/registration-token-not-registered |
Le jeton d'enregistrement fourni n'est pas enregistré. Un jeton d'enregistrement précédemment valide peut être désenregistré pour diverses raisons, par exemple :
|
messaging/invalid-package-name |
Le message était adressé à un jeton d'enregistrement dont le nom de package ne correspond pas à l'option
restrictedPackageName fournie.
|
messaging/message-rate-exceeded |
Le taux de messages envoyés à une cible spécifique est trop élevé. Réduisez le nombre de messages envoyés à cet appareil ou à ce sujet, et ne réessayez pas immédiatement d'envoyer à cette cible. |
messaging/device-message-rate-exceeded |
Le nombre de messages envoyés à un appareil spécifique est trop élevé. Réduisez le nombre de messages envoyés à cet appareil et n'essayez pas immédiatement de renvoyer un message à cet appareil. |
messaging/topics-message-rate-exceeded |
Le nombre de messages envoyés aux abonnés d'un sujet particulier est trop élevé. Réduisez le nombre de messages envoyés pour ce sujet et n'essayez pas immédiatement de renvoyer le message. |
messaging/too-many-topics |
Un jeton d'enregistrement a été abonné au nombre maximal de sujets et ne peut plus être abonné à d'autres. |
messaging/invalid-apns-credentials |
Impossible d'envoyer un message ciblé sur un appareil Apple, car le certificat SSL des APN requis n'a pas été importé ou est arrivé à expiration. Vérifiez la validité de vos certificats de développement et de production. |
messaging/mismatched-credential |
Les identifiants utilisés pour authentifier ce SDK ne sont pas autorisés à envoyer des messages à l'appareil correspondant au jeton d'enregistrement fourni. Assurez-vous que les identifiants et le jeton d'enregistrement appartiennent au même projet Firebase. Consultez la documentation Ajouter Firebase à votre application pour savoir comment authentifier les Firebase Admin SDK. |
messaging/authentication-error |
Le SDK n'a pas pu s'authentifier auprès des serveurs FCM. Assurez-vous d'authentifier le Firebase Admin SDK avec des identifiants disposant des autorisations appropriées pour envoyer des messages FCM. Consultez la documentation Ajouter Firebase à votre application pour savoir comment authentifier les Firebase Admin SDK. |
messaging/server-unavailable |
Le serveur FCM n'a pas pu traiter la requête à temps. Vous devez relancer la même requête, mais vous devez :
|
messaging/internal-error |
Le serveur FCM a rencontré une erreur lors du traitement de la requête. Vous pouvez réessayer la même requête en suivant les exigences indiquées dans la ligne messaging/server-unavailable ci-dessus. Si l'erreur persiste, veuillez signaler le problème à notre canal d'assistance Signaler un bug.
|
messaging/unknown-error |
Une erreur serveur inconnue a été renvoyée. Pour en savoir plus, consultez la réponse brute du serveur dans le message d'erreur. Si vous recevez cette erreur, veuillez signaler le message d'erreur complet à notre canal d'assistance Signaler un bug. |
Envoyer des messages à l'aide des anciens protocoles de serveur d'application
Si vous utilisez actuellement les anciens protocoles, créez des requêtes de message comme indiqué dans cette section. N'oubliez pas que si vous envoyez des messages à plusieurs plates-formes via HTTP, le protocole v1 peut grandement simplifier vos requêtes de messages.
Envoyer des messages à des appareils spécifiques
Pour envoyer des messages à des appareils spécifiques, définissez la clé to sur le jeton d'enregistrement de l'instance d'application spécifique. Pour en savoir plus sur les jetons d'enregistrement, consultez les informations de configuration du client pour votre plate-forme.
Requête POST HTTP
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..."
}
Réponse HTTP
{ "multicast_id": 108,
"success": 1,
"failure": 0,
"results": [
{ "message_id": "1:08" }
]
}
Message XMPP
<message id="">
<gcm xmlns="google:mobile:data">
{ "data": {
"score": "5x1",
"time": "15:10"
},
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}
</gcm>
</message>
Réponse XMPP
<message id="">
<gcm xmlns="google:mobile:data">
{
"from":"REGID",
"message_id":"m-1366082849205"
"message_type":"ack"
}
</gcm>
</message>
Le serveur de connexion XMPP propose d'autres options de réponse. Consultez la section Format de réponse du serveur.
Pour obtenir la liste complète des options de message disponibles lors de l'envoi de messages en aval aux applications clientes, consultez les informations de référence du protocole de serveur de connexion que vous avez choisi, HTTP ou XMPP.
Envoyer des messages aux sujets
L'envoi de messages à un sujet Firebase Cloud Messaging est très semblable à l'envoi de messages à un appareil individuel ou à un groupe d'utilisateurs. Le serveur d'application définit la clé to avec une valeur telle que /topics/yourTopic.
Les développeurs peuvent choisir n'importe quel nom de sujet correspondant à l'expression régulière : "/topics/[a-zA-Z0-9-_.~%]+".
Pour envoyer des messages à des combinaisons de plusieurs sujets, le serveur d'application doit définir la clé condition (au lieu de la clé to) sur une condition booléenne qui spécifie les sujets cibles. Par exemple, pour envoyer des messages aux appareils abonnés à TopicA et à TopicB ou TopicC:
'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)
FCM évalue d'abord les conditions entre parenthèses, puis l'expression de gauche à droite. Dans l'expression ci-dessus, un utilisateur abonné à un seul sujet ne reçoit pas le message. De même, un utilisateur qui ne s'abonne pas à TopicA ne reçoit pas le message. Ces combinaisons le reçoivent:
- TopicA et TopicB
- TopicA et TopicC
Vous pouvez inclure jusqu'à cinq sujets dans votre expression conditionnelle. Les parenthèses sont acceptées.
Opérateurs acceptés: &&, ||.
Requête POST HTTP de sujet
Envoyer à un seul sujet:
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
Envoyer aux appareils abonnés aux sujets "chiens" ou "chats":
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
Réponse HTTP du sujet
// Success example:
{
"message_id": "1023456"
}
// failure example:
{
"error": "TopicsMessageRateExceeded"
}
Message XMPP du sujet
Envoyer à un seul sujet:
<message id="">
<gcm xmlns="google:mobile:data">
</gcm>
</message>
Envoyer aux appareils abonnés aux sujets "chiens" ou "chats":
<message id=""> <gcm xmlns="google:mobile:data"> </gcm> </message>
Réponse XMPP du sujet
// Success example:
{
"message_id": "1023456"
}
// failure example:
{
"error": "TopicsMessageRateExceeded"
}
Attendez jusqu'à 30 secondes avant que le serveur FCM ne renvoie une réponse de réussite ou d'échec aux requêtes d'envoi de sujets. Veillez à définir la valeur du délai avant expiration du serveur d'application dans la requête en conséquence.
Envoyer des messages à des groupes d'appareils
L'envoi de messages à un groupe d'appareils à l'aide des anciennes API obsolètes est très semblable à l'envoi de messages à un appareil individuel. Définissez le paramètre to sur la clé de notification unique du groupe d'appareils.
Les exemples de cette section montrent comment envoyer des messages de données à des groupes d'appareils dans les anciens protocoles HTTP et XMPP.
Requête POST HTTP du groupe d'appareils
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!",
}
}
Réponse HTTP du groupe d'appareils
Voici un exemple de "succès" : notification_key est associé à deux jetons d'enregistrement, et le message a bien été envoyé aux deux :
{
"success": 2,
"failure": 0
}
Voici un exemple de "succès partiel" : notification_key comporte trois jetons d'enregistrement associés. Le message a bien été envoyé à un seul des jetons d'enregistrement. Le message de réponse liste les jetons d'enregistrement (registration_ids) qui n'ont pas reçu le message:
{
"success":1,
"failure":2,
"failed_registration_ids":[
"regId1",
"regId2"
]
}
Lorsqu'un message ne parvient pas à être distribué à un ou plusieurs des jetons d'enregistrement associés à un notification_key, le serveur d'application doit effectuer une nouvelle tentative avec un délai d'attente entre les tentatives.
Si le serveur tente d'envoyer un message à un groupe d'appareils qui ne compte aucun membre, la réponse se présente comme suit, avec 0 succès et 0 échec:
{
"success": 0,
"failure": 0
}
Message XMPP du groupe d'appareils
<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>
Réponse XMPP du groupe d'appareils
Lorsque le message est envoyé à l'un des appareils du groupe, le serveur de connexion XMPP répond avec un ACK. Si tous les messages envoyés à tous les appareils du groupe échouent, le serveur de connexion XMPP répond avec un NACK.
Voici un exemple de "succès" : notification_key est associé à trois jetons d'enregistrement, et le message a bien été envoyé à tous :
{
"from": "aUniqueKey",
"message_type": "ack",
"success": 3,
"failure": 0,
"message_id": "m-1366082849205"
}
Voici un exemple de "succès partiel" : notification_key comporte trois jetons d'enregistrement associés. Le message a bien été envoyé à un seul des jetons d'enregistrement. Le message de réponse liste les jetons d'enregistrement qui n'ont pas reçu le message:
{
"from": "aUniqueKey",
"message_type": "ack",
"success":1,
"failure":2,
"failed_registration_ids":[
"regId1",
"regId2"
]
}
Lorsque le serveur de connexion FCM ne parvient pas à diffuser le message auprès de tous les appareils du groupe. Le serveur d'application recevra une réponse nack.
Pour obtenir la liste complète des options de message, consultez les informations de référence pour le protocole de serveur de connexion que vous avez choisi, HTTP ou XMPP.
Firebase Admin SDK anciennes méthodes d'envoi
Le SDK Firebase Admin Node.js prend en charge les méthodes d'envoi de messages (FCM) basées sur l'ancienne API de serveur FCM.
Ces méthodes acceptent des arguments différents de ceux de la méthode send().
Dans la mesure du possible, vous devez utiliser la méthode send() et n'utiliser les méthodes décrites sur cette page que lorsque vous envoyez des messages à des appareils individuels ou à des groupes d'appareils.
Envoyer à des appareils individuels
Vous pouvez transmettre un jeton d'enregistrement à la méthode sendToDevice() pour envoyer un message à cet appareil:
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);
});
La méthode sendToDevice() peut également envoyer un message multicast (c'est-à-dire un message à plusieurs appareils) en transmettant un tableau de jetons d'enregistrement au lieu d'un seul jeton d'enregistrement:
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);
});
La méthode sendToDevice() renvoie une promesse résolue avec un objet MessagingDevicesResponse contenant la réponse de FCM. Le type de retour a le même format lorsque vous transmettez un seul jeton d'enregistrement ou un tableau de jetons d'enregistrement.
Dans certains cas, comme une erreur d'authentification ou une limitation de débit, le traitement de l'intégralité du message échoue. Dans ces cas, la promesse renvoyée par sendToDevice() est rejetée avec une erreur. Pour obtenir la liste complète des codes d'erreur, y compris les descriptions et les étapes de résolution, consultez la section Erreurs de l'API FCM pour les administrateurs.
Envoyer à un groupe d'appareils
La méthode sendToDeviceGroup() vous permet d'envoyer un message à un groupe d'appareils en spécifiant la clé de notification de ce groupe d'appareils:
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);
});
La méthode sendToDeviceGroup() renvoie une promesse résolue avec un objet MessagingDevicesResponse contenant la réponse de FCM.
Dans certains cas, comme une erreur d'authentification ou une limitation de débit, le traitement de l'intégralité du message échoue. Dans ces cas, la promesse renvoyée par sendToDeviceGroup() est rejetée avec une erreur. Pour obtenir la liste complète des codes d'erreur, y compris les descriptions et les étapes de résolution, consultez la section Erreurs de l'API FCM pour les administrateurs.
Définir la charge utile du message
Les méthodes ci-dessus basées sur les anciens protocoles FCM acceptent une charge utile de message comme deuxième argument et prennent en charge à la fois les messages de notification et de données.
Vous pouvez spécifier un ou les deux types de messages en créant un objet avec les clés data et / ou notification. Par exemple, voici comment définir différents types de charges utiles de messages:
Message de notification
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.'
}
};
Message data
const payload = {
data: {
score: '850',
time: '2:45'
}
};
Message combiné
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'
}
};
Les charges utiles des messages de notification comportent un sous-ensemble prédéfini de propriétés valides et diffèrent légèrement selon le système d'exploitation mobile que vous ciblez.
Pour obtenir la liste complète, consultez la documentation de référence sur NotificationMessagePayload.
Les charges utiles de messages de données sont composées de paires clé-valeur personnalisées avec quelques restrictions, y compris le fait que toutes les valeurs doivent être des chaînes. Pour obtenir la liste complète des restrictions, consultez la documentation de référence sur DataMessagePayload.
Définir les options de message
Les méthodes ci-dessus basées sur les anciens protocoles FCM acceptent un troisième argument facultatif spécifiant certaines options pour le message. Par exemple, l'exemple suivant envoie un message de priorité élevée à un appareil qui expire au bout de 24 heures:
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);
});
Pour obtenir la liste complète des options disponibles, consultez la documentation de référence sur MessagingOptions.