Basé sur le modèle de publication/abonnement, la messagerie de sujet FCM vous permet d'envoyer un message à plusieurs appareils qui se sont inscrits à un sujet particulier. Vous composez les messages de sujet selon vos besoins, et FCM gère le routage et la livraison du message de manière fiable vers les bons appareils.
Par exemple, les utilisateurs d'une application locale de prévision des marées pourraient s'inscrire à un sujet "alertes de courants de marée" et recevoir des notifications sur les conditions optimales de pêche en eau salée dans des zones spécifiées. Les utilisateurs d'une application sportive pouvaient s'abonner à des mises à jour automatiques des scores des matchs en direct de leurs équipes préférées.
Quelques éléments à garder à l'esprit concernant les sujets :
- La messagerie par sujet convient mieux aux contenus tels que la météo ou d'autres informations accessibles au public.
- Les messages de sujet sont optimisés pour le débit plutôt que pour la latence . Pour une livraison rapide et sécurisée à des appareils uniques ou à de petits groupes d'appareils, ciblez les messages sur des jetons d'inscription , et non sur des sujets.
- Si vous devez envoyer des messages à plusieurs appareils par utilisateur , envisagez la messagerie de groupe d'appareils pour ces cas d'utilisation.
- La messagerie thématique prend en charge les abonnements illimités pour chaque sujet. Cependant, la FCM impose des limites dans ces domaines :
- Une instance d'application ne peut pas être abonnée à plus de 2 000 sujets.
- Si vous utilisez l'importation par lots pour souscrire des instances d'application, chaque demande est limitée à 1 000 instances d'application.
- La fréquence des nouveaux abonnements est limitée par projet. Si vous envoyez trop de demandes d'abonnement dans un court laps de temps, les serveurs FCM répondront avec une réponse
429 RESOURCE_EXHAUSTED
("quota dépassé"). Réessayez avec une temporisation exponentielle.
Abonnez l'application cliente à un sujet
Pour vous abonner à un sujet, appelez ::firebase::messaging::Subscribe
depuis votre application. Cela fait une demande asynchrone au backend FCM et abonne le client au sujet donné.
::firebase::messaging::Subscribe("example");
Si la demande d'abonnement échoue initialement, FCM réessaye jusqu'à ce qu'il puisse s'abonner à la rubrique avec succès. Chaque fois que l'application démarre, FCM s'assure que tous les sujets demandés ont été souscrits.
Pour vous désinscrire, appelez ::firebase::messaging::Unsubscribe
, et FCM se désabonne du sujet en arrière-plan.
Gérer les abonnements aux rubriques sur le serveur
Le SDK Firebase Admin vous permet d'effectuer des tâches de base de gestion des sujets côté serveur. Compte tenu de leur(s) jeton(s) d'enregistrement, vous pouvez vous abonner et vous désabonner en masse des instances d'application cliente à l'aide de la logique du serveur.
Vous pouvez abonner des instances d'application cliente à n'importe quel sujet existant ou vous pouvez créer un nouveau sujet. Lorsque vous utilisez l'API pour abonner une application cliente à un nouveau sujet (qui n'existe pas déjà pour votre projet Firebase), un nouveau sujet portant ce nom est créé dans FCM et n'importe quel client peut ensuite s'y abonner.
Vous pouvez transmettre une liste de jetons d'enregistrement à la méthode d'abonnement au SDK Firebase Admin pour abonner les appareils correspondants à un sujet :
Node.js
// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
'YOUR_REGISTRATION_TOKEN_1',
// ...
'YOUR_REGISTRATION_TOKEN_n'
];
// Subscribe the devices corresponding to the registration tokens to the
// topic.
getMessaging().subscribeToTopic(registrationTokens, topic)
.then((response) => {
// See the MessagingTopicManagementResponse reference documentation
// for the contents of response.
console.log('Successfully subscribed to topic:', response);
})
.catch((error) => {
console.log('Error subscribing to topic:', error);
});
Java
// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n"
);
// Subscribe the devices corresponding to the registration tokens to the
// topic.
TopicManagementResponse response = FirebaseMessaging.getInstance().subscribeToTopic(
registrationTokens, topic);
// See the TopicManagementResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " tokens were subscribed successfully");
Python
# These registration tokens come from the client FCM SDKs.
registration_tokens = [
'YOUR_REGISTRATION_TOKEN_1',
# ...
'YOUR_REGISTRATION_TOKEN_n',
]
# Subscribe the devices corresponding to the registration tokens to the
# topic.
response = messaging.subscribe_to_topic(registration_tokens, topic)
# See the TopicManagementResponse reference documentation
# for the contents of response.
print(response.success_count, 'tokens were subscribed successfully')
Aller
// These registration tokens come from the client FCM SDKs.
registrationTokens := []string{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
}
// Subscribe the devices corresponding to the registration tokens to the
// topic.
response, err := client.SubscribeToTopic(ctx, registrationTokens, topic)
if err != nil {
log.Fatalln(err)
}
// See the TopicManagementResponse reference documentation
// for the contents of response.
fmt.Println(response.SuccessCount, "tokens were subscribed successfully")
C#
// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
};
// Subscribe the devices corresponding to the registration tokens to the
// topic
var response = await FirebaseMessaging.DefaultInstance.SubscribeToTopicAsync(
registrationTokens, topic);
// See the TopicManagementResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} tokens were subscribed successfully");
L'API Admin FCM vous permet également de désabonner des appareils d'un sujet en transmettant des jetons d'enregistrement à la méthode appropriée :
Node.js
// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
'YOUR_REGISTRATION_TOKEN_1',
// ...
'YOUR_REGISTRATION_TOKEN_n'
];
// Unsubscribe the devices corresponding to the registration tokens from
// the topic.
getMessaging().unsubscribeFromTopic(registrationTokens, topic)
.then((response) => {
// See the MessagingTopicManagementResponse reference documentation
// for the contents of response.
console.log('Successfully unsubscribed from topic:', response);
})
.catch((error) => {
console.log('Error unsubscribing from topic:', error);
});
Java
// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n"
);
// Unsubscribe the devices corresponding to the registration tokens from
// the topic.
TopicManagementResponse response = FirebaseMessaging.getInstance().unsubscribeFromTopic(
registrationTokens, topic);
// See the TopicManagementResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " tokens were unsubscribed successfully");
Python
# These registration tokens come from the client FCM SDKs.
registration_tokens = [
'YOUR_REGISTRATION_TOKEN_1',
# ...
'YOUR_REGISTRATION_TOKEN_n',
]
# Unubscribe the devices corresponding to the registration tokens from the
# topic.
response = messaging.unsubscribe_from_topic(registration_tokens, topic)
# See the TopicManagementResponse reference documentation
# for the contents of response.
print(response.success_count, 'tokens were unsubscribed successfully')
Aller
// These registration tokens come from the client FCM SDKs.
registrationTokens := []string{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
}
// Unsubscribe the devices corresponding to the registration tokens from
// the topic.
response, err := client.UnsubscribeFromTopic(ctx, registrationTokens, topic)
if err != nil {
log.Fatalln(err)
}
// See the TopicManagementResponse reference documentation
// for the contents of response.
fmt.Println(response.SuccessCount, "tokens were unsubscribed successfully")
C#
// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
};
// Unsubscribe the devices corresponding to the registration tokens from the
// topic
var response = await FirebaseMessaging.DefaultInstance.UnsubscribeFromTopicAsync(
registrationTokens, topic);
// See the TopicManagementResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} tokens were unsubscribed successfully");
Les méthodes subscribeToTopic()
et unsubscribeFromTopic()
génèrent un objet contenant la réponse de FCM. Le type de retour a le même format quel que soit le nombre de jetons d'enregistrement spécifié dans la demande.
En cas d'erreur (échecs d'authentification, jeton ou sujet invalide, etc.), ces méthodes entraînent une erreur. Pour obtenir la liste complète des codes d'erreur, y compris les descriptions et les étapes de résolution, consultez Admin FCM API Errors .
Recevoir et gérer les messages du sujet
FCM transmet les messages de rubrique de la même manière que les autres messages en aval.
En remplaçant la méthode ::firebase::messaging::Listener::OnMessage
, vous pouvez effectuer des actions basées sur le message reçu et obtenir les données du message :
void OnMessage(const ::firebase::messaging::Message& message) { LogMessage(TAG, "From: %s", message.from.c_str()); LogMessage(TAG, "Message ID: %s", message.message_id.c_str()); }
Créer des demandes d'envoi
Après avoir 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 c'est la première fois que vous créez des demandes d'envoi pour FCM, consultez le guide de votre environnement de 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 du 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)
Aller
// 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);
REPOS
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 rubriques, spécifiez une condition , qui est une expression booléenne qui spécifie les rubriques cibles. Par exemple, la condition suivante enverra des messages aux appareils abonnés à TopicA
et TopicB
ou TopicC
:
"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"
FCM évalue d'abord toutes les conditions entre parenthèses, puis évalue 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 n'est pas abonné à TopicA
ne reçoit pas le message. Ces combinaisons le reçoivent :
-
TopicA
etTopicB
-
TopicA
etTopicC
Vous pouvez inclure jusqu'à cinq rubriques dans votre expression conditionnelle.
Pour envoyer à 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)
Aller
// 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);
REPOS
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
Prochaines étapes
- En savoir plus sur l'autre méthode d'envoi vers plusieurs appareils : la messagerie de groupe d'appareils