Usando os protocolos do SDK Admin do Firebase ou do servidor de aplicativos FCM, você pode criar solicitações de mensagens e enviá-las para estes tipos de destinos:
- Nome do tópico
- Doença
- Token de registro do dispositivo
- Nome do grupo de dispositivos (somente protocolo)
Você pode enviar mensagens com uma carga útil de notificação composta de campos predefinidos, uma carga útil de dados de seus próprios campos definidos pelo usuário ou uma mensagem contendo ambos os tipos de carga útil. Consulte Tipos de mensagens para obter mais informações.
Os exemplos nesta página mostram como enviar mensagens de notificação usando o Firebase Admin SDK (que é compatível com Node , Java , Python , C# e Go ) e o protocolo HTTP v1 . Há também orientações para o envio de mensagens por meio dos obsoletos protocolos legados HTTP e XMPP .
Envie mensagens para dispositivos específicos
Para enviar para um único dispositivo específico, passe o token de registro do dispositivo conforme mostrado. Consulte as informações de configuração do cliente da sua plataforma para saber mais sobre tokens de registro.
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);
Pitão
# 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)
Ir
// 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);
DESCANSAR
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"
}
}
}
Comando 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
Em caso de sucesso, cada método de envio retorna um ID de mensagem. O SDK Admin do Firebase retorna a string de ID no formato projects/{project_id}/messages/{message_id}
. A resposta do protocolo HTTP é uma única chave JSON:
{
"name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
}
Envie mensagens para vários dispositivos
As APIs Admin FCM permitem que você transmita uma mensagem para uma lista de tokens de registro de dispositivos. Você pode especificar até 500 tokens de registro de dispositivos por chamada.
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");
Pitão
# 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))
Ir
// 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");
O valor de retorno é uma lista de tokens que corresponde à ordem dos tokens de entrada. Isto é útil quando você deseja verificar quais tokens resultaram em erros.
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);
}
Pitão
# 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))
Ir
// 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}");
}
Envie mensagens para tópicos
Depois de criar um tópico, seja inscrevendo instâncias do aplicativo cliente no tópico no lado do cliente ou por meio da API do servidor , você poderá enviar mensagens para o tópico. Se esta for a primeira vez que você cria solicitações de envio para o FCM, consulte o guia do ambiente do seu servidor e do FCM para obter informações importantes sobre antecedentes e configuração.
Na sua lógica de envio no backend, especifique o nome do tópico desejado conforme mostrado:
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);
Pitão
# 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)
Ir
// 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);
DESCANSAR
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"
}
}
}
Comando 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
Para enviar uma mensagem para uma combinação de tópicos, especifique uma condição , que é uma expressão booleana que especifica os tópicos de destino. Por exemplo, a condição a seguir enviará mensagens para dispositivos inscritos em TopicA
e TopicB
ou TopicC
:
"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"
O FCM primeiro avalia quaisquer condições entre parênteses e depois avalia a expressão da esquerda para a direita. Na expressão acima, um usuário inscrito em um único tópico não recebe a mensagem. Da mesma forma, um usuário que não assina o TopicA
não recebe a mensagem. Estas combinações recebem:
-
TopicA
eTopicB
-
TopicA
eTopicC
Você pode incluir até cinco tópicos em sua expressão condicional.
Para enviar para uma condição:
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);
Pitão
# 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)
Ir
// 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);
DESCANSAR
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",
}
}
}
Comando 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
Envie mensagens para grupos de dispositivos
Para enviar mensagens para grupos de dispositivos, use a API HTTP v1. Se você estiver enviando para grupos de dispositivos usando as APIs de envio legadas obsoletas para HTTP ou XMPP, ou qualquer uma das versões mais antigas do SDK Admin do Firebase para Node.js com base nos protocolos legados, recomendamos fortemente que você migre para o HTTP v1 API na primeira oportunidade. As APIs de envio herdadas serão desativadas e removidas em junho de 2024.
Enviar mensagens para um grupo de dispositivos é muito semelhante a enviar mensagens para um dispositivo individual, usando o mesmo método para autorizar solicitações de envio . Defina o campo token
como a chave de notificação do grupo:
DESCANSAR
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!"
}
}
}
comando 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
Envie um lote de mensagens
Os Admin SDKs oferecem suporte ao envio de mensagens em lotes. Você pode agrupar até 500 mensagens em um único lote e enviá-las todas em uma única chamada de API, com melhoria significativa de desempenho em relação ao envio de solicitações HTTP separadas para cada mensagem.
Este recurso pode ser usado para construir um conjunto personalizado de mensagens e enviá-las para diferentes destinatários, incluindo tópicos ou tokens de registro de dispositivos específicos. Use esse recurso quando, por exemplo, precisar enviar mensagens simultaneamente para diferentes públicos com detalhes ligeiramente diferentes no corpo da mensagem.
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");
Pitão
# 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))
Ir
// 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");
Envie mensagens habilitadas para inicialização direta (somente Android)
Você pode enviar mensagens para dispositivos no modo de inicialização direta usando HTTP v1 ou APIs HTTP herdadas. Antes de enviar para dispositivos no modo de inicialização direta, certifique-se de ter concluído as etapas para permitir que os dispositivos cliente recebam mensagens FCM no modo de inicialização direta .
Enviar usando a API HTTP FCM v1
A solicitação da mensagem deve incluir a chave "direct_boot_ok" : true
nas opções AndroidConfig
do corpo da solicitação. Por exemplo:
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,
},
}
Enviar usando a API HTTP legada do FCM
A solicitação da mensagem deve incluir a chave "direct_boot_ok" : true
no nível superior do corpo da solicitação. Por exemplo:
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
}
As mensagens enviadas com esta chave no corpo da solicitação podem ser tratadas por aplicativos em dispositivos atualmente no modo de inicialização direta (e também quando não estão nesse modo).
Personalize mensagens entre plataformas
O SDK Admin do Firebase e o protocolo HTTP FCM v1 permitem que suas solicitações de mensagens definam todos os campos disponíveis no objeto message
. Isso inclui:
- um conjunto comum de campos a serem interpretados por todas as instâncias do aplicativo que recebem a mensagem.
- conjuntos de campos específicos da plataforma, como
AndroidConfig
eWebpushConfig
, interpretados apenas por instâncias de aplicativos em execução na plataforma especificada.
Os blocos específicos da plataforma oferecem flexibilidade para personalizar mensagens para diferentes plataformas, garantindo que elas sejam tratadas corretamente quando recebidas. O backend do FCM levará em consideração todos os parâmetros especificados e personalizará a mensagem para cada plataforma.
Quando usar campos comuns
Use campos comuns quando você:
- Direcionando instâncias de aplicativos em todas as plataformas — Apple, Android e web
- Enviando mensagens para tópicos
Todas as instâncias do aplicativo, independentemente da plataforma, podem interpretar os seguintes campos comuns:
Quando usar campos específicos da plataforma
Use campos específicos da plataforma quando quiser:
- Envie campos apenas para plataformas específicas
- Envie campos específicos da plataforma , além dos campos comuns
Sempre que desejar enviar valores apenas para plataformas específicas, não utilize campos comuns; use campos específicos da plataforma. Por exemplo, para enviar uma notificação apenas para plataformas Apple e web, mas não para Android, você deve usar dois conjuntos separados de campos, um para Apple e outro para web.
Ao enviar mensagens com opções de entrega específicas, use campos específicos da plataforma para defini-las. Você pode especificar valores diferentes por plataforma, se desejar. No entanto, mesmo quando quiser definir essencialmente o mesmo valor entre plataformas, você deverá usar campos específicos da plataforma. Isso ocorre porque cada plataforma pode interpretar o valor de maneira um pouco diferente – por exemplo, o tempo de vida é definido no Android como um tempo de expiração em segundos, enquanto na Apple é definido como uma data de expiração.
Exemplo: mensagem de notificação com opções de cores e ícones
Este exemplo de solicitação de envio envia um título e conteúdo de notificação comum para todas as plataformas, mas também envia algumas substituições específicas da plataforma para dispositivos Android.
Para Android, a solicitação define um ícone e uma cor especiais para exibição em dispositivos Android. Conforme observado na referência para AndroidNotification , a cor é especificada no formato #rrggbb e a imagem deve ser um recurso de ícone desenhável local para o aplicativo Android.
Aqui está uma aproximação do efeito visual no dispositivo de um usuário:
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();
Pitão
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',
)
Ir
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",
};
DESCANSAR
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"
}
}
}
}
Consulte a documentação de referência do HTTP v1 para obter detalhes completos sobre as chaves disponíveis em blocos específicos da plataforma no corpo da mensagem.
Exemplo: mensagem de notificação com imagem personalizada
O exemplo de solicitação de envio a seguir envia um título de notificação comum para todas as plataformas, mas também envia uma imagem. Aqui está uma aproximação do efeito visual no dispositivo de um usuário:
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);
});
DESCANSAR
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"
}
}
}
}
Consulte a documentação de referência do HTTP v1 para obter detalhes completos sobre as chaves disponíveis em blocos específicos da plataforma no corpo da mensagem.
Exemplo: mensagem de notificação com uma ação de clique associada
O exemplo de solicitação de envio a seguir envia um título de notificação comum para todas as plataformas, mas também envia uma ação para o aplicativo executar em resposta à interação do usuário com a notificação. Aqui está uma aproximação do efeito visual no dispositivo de um usuário:
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);
});
DESCANSAR
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"
}
}
}
}
Consulte a documentação de referência do HTTP v1 para obter detalhes completos sobre as chaves disponíveis em blocos específicos da plataforma no corpo da mensagem.
Exemplo: mensagem de notificação com opções de localização
O exemplo de solicitação de envio a seguir envia opções de localização para o cliente exibir mensagens localizadas. Aqui está uma aproximação do efeito visual no dispositivo de um usuário:
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);
});
DESCANSAR
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"],
},
},
},
},
},
}'
Consulte a documentação de referência do HTTP v1 para obter detalhes completos sobre as chaves disponíveis em blocos específicos da plataforma no corpo da mensagem.
Códigos de erro REST para a API HTTP v1
As respostas de erro HTTP para a API HTTP v1 contêm um código de erro, uma mensagem de erro e um status de erro. Eles também podem conter uma matriz details
com mais detalhes sobre o erro.
Aqui estão dois exemplos de respostas de erro:
Exemplo 1: Resposta de erro de uma solicitação de API HTTP v1 com um valor inválido em uma mensagem de dados
{
"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"
}
]
}
]
}
}
Exemplo 2: Resposta de erro de uma solicitação de API HTTP v1 com um token de registro inválido
{
"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"
}
]
}
}
Observe que ambas as mensagens têm o mesmo código e status, mas a matriz de detalhes contém valores em tipos diferentes. O primeiro exemplo possui o tipo type.googleapis.com/google.rpc.BadRequest
indicando um erro nos valores da solicitação. O segundo exemplo com tipo type.googleapis.com/google.firebase.fcm.v1.FcmError
possui um erro específico do FCM. Para muitos erros, a matriz de detalhes contém as informações necessárias para depurar e encontrar uma solução.
A tabela a seguir lista os códigos de erro da API REST do FCM v1 e suas descrições.
Erro de código | Descrição e etapas de resolução |
---|---|
UNSPECIFIED_ERROR Não há mais informações disponíveis sobre esse erro. | Nenhum. |
INVALID_ARGUMENT (código de erro HTTP = 400) Os parâmetros da solicitação eram inválidos. Uma extensão do tipo google.rpc.BadRequest é retornada para especificar qual campo era inválido. | As possíveis causas incluem registro inválido, nome de pacote inválido, mensagem muito grande, chave de dados inválida, TTL inválido ou outros parâmetros inválidos. Registro inválido : Verifique o formato do token de registro que você passa para o servidor. Certifique-se de que ele corresponda ao token de registro que o aplicativo cliente recebe ao se registrar no FCM. Não trunque o token nem adicione caracteres adicionais. Nome de pacote inválido : certifique-se de que a mensagem foi endereçada a um token de registro cujo nome de pacote corresponda ao valor passado na solicitação. Mensagem muito grande : verifique se o tamanho total dos dados de carga incluídos em uma mensagem não excede os limites do FCM: 4.096 bytes para a maioria das mensagens ou 2.048 bytes no caso de mensagens para tópicos. Isso inclui as chaves e os valores. Chave de dados inválida : verifique se os dados da carga útil não contêm uma chave (como from, ou gcm, ou qualquer valor prefixado pelo google) que seja usada internamente pelo FCM. Observe que algumas palavras (como colapso_key) também são usadas pelo FCM, mas são permitidas na carga útil; nesse caso, o valor da carga útil será substituído pelo valor do FCM. TTL inválido : verifique se o valor usado em ttl é um número inteiro que representa uma duração em segundos entre 0 e 2.419.200 (4 semanas). Parâmetros inválidos : verifique se os parâmetros fornecidos têm o nome e o tipo corretos. |
UNREGISTERED (código de erro HTTP = 404) O registro da instância do aplicativo foi cancelado no FCM. Isso geralmente significa que o token usado não é mais válido e um novo deve ser usado. | Este erro pode ser causado pela falta de tokens de registro ou por tokens não registrados. Registro ausente : se o destino da mensagem for um valor token , verifique se a solicitação contém um token de registro.Não registrado : um token de registro existente pode deixar de ser válido em vários cenários, incluindo: - Se o aplicativo cliente cancelar o registro no FCM. - Se o registro do aplicativo cliente for automaticamente cancelado, o que pode acontecer se o usuário desinstalar o aplicativo. Por exemplo, no iOS, se o Serviço de Feedback de APNs reportar o token de APNs como inválido. - Se o token de registro expirar (por exemplo, o Google pode decidir atualizar os tokens de registro ou o token de APNs expirou para dispositivos iOS). - Se o aplicativo cliente estiver atualizado, mas a nova versão não estiver configurada para receber mensagens. Para todos esses casos, remova esse token de registro do servidor do aplicativo e pare de usá-lo para enviar mensagens. |
SENDER_ID_MISMATCH (código de erro HTTP = 403) O ID do remetente autenticado é diferente do ID do remetente do token de registro. | Um token de registro está vinculado a um determinado grupo de remetentes. Quando um aplicativo cliente se registra no FCM, ele precisa especificar quais remetentes têm permissão para enviar mensagens. Você deve usar um desses IDs de remetente ao enviar mensagens para o aplicativo cliente. Se você mudar para um remetente diferente, os tokens de registro existentes não funcionarão. |
QUOTA_EXCEEDED (código de erro HTTP = 429) Limite de envio excedido para o destino da mensagem. Uma extensão do tipo google.rpc.QuotaFailure é retornada para especificar qual cota foi excedida. | Este erro pode ser causado por cota de taxa de mensagens excedida, cota de taxa de mensagens do dispositivo excedida ou cota de taxa de mensagens de tópico excedida. Taxa de mensagens excedida : A taxa de envio de mensagens é muito alta. Você deve reduzir a taxa geral de envio de mensagens. Use espera exponencial com atraso inicial mínimo de 1 minuto para tentar novamente mensagens rejeitadas. Taxa de mensagens do dispositivo excedida : A taxa de mensagens para um dispositivo específico é muito alta. Consulte limite de taxa de mensagens para um único dispositivo . Reduza o número de mensagens enviadas para este dispositivo e use a espera exponencial para tentar enviar novamente. Taxa de mensagens do tópico excedida : a taxa de mensagens para assinantes de um determinado tópico é muito alta. Reduza o número de mensagens enviadas para este tópico e use espera exponencial com atraso inicial mínimo de 1 minuto para tentar enviar novamente. |
UNAVAILABLE (código de erro HTTP = 503) O servidor está sobrecarregado. | O servidor não conseguiu processar a solicitação a tempo. Tente novamente a mesma solicitação, mas você deve: - Respeite o cabeçalho Retry-After se ele estiver incluído na resposta do FCM Connection Server. - Implemente a retirada exponencial em seu mecanismo de nova tentativa. (por exemplo, se você esperou um segundo antes da primeira tentativa, espere pelo menos dois segundos antes da próxima, depois 4 segundos e assim por diante). Se você estiver enviando várias mensagens, considere aplicar tremulação. Para obter mais informações, consulte Tratamento de novas tentativas . Remetentes que causam problemas correm o risco de serem colocados na lista negra. |
INTERNAL (código de erro HTTP = 500) Ocorreu um erro interno desconhecido. | O servidor encontrou um erro ao tentar processar a solicitação. Você pode tentar novamente a mesma solicitação seguindo as sugestões em Tratamento de novas tentativas . Se o erro persistir, entre em contato com o suporte do Firebase. |
THIRD_PARTY_AUTH_ERROR (código de erro HTTP = 401) O certificado de APNs ou a chave de autenticação web push eram inválidos ou ausentes. | Não foi possível enviar uma mensagem direcionada a um dispositivo iOS ou um registro web push. Verifique a validade de suas credenciais de desenvolvimento e produção. |
Códigos de erro de administrador
A tabela a seguir lista os códigos de erro da API Firebase Admin FCM e suas descrições, incluindo as etapas de resolução recomendadas.
Erro de código | Descrição e etapas de resolução |
---|---|
messaging/invalid-argument | Um argumento inválido foi fornecido a um método FCM. A mensagem de erro deve conter informações adicionais. |
messaging/invalid-recipient | O destinatário da mensagem pretendido é inválido. A mensagem de erro deve conter informações adicionais. |
messaging/invalid-payload | Um objeto de carga útil de mensagem inválido foi fornecido. A mensagem de erro deve conter informações adicionais. |
messaging/invalid-data-payload-key | A carga útil da mensagem de dados contém uma chave inválida. Consulte a documentação de referência do DataMessagePayload para obter chaves restritas. |
messaging/payload-size-limit-exceeded | A carga da mensagem fornecida excede os limites de tamanho do FCM. O limite é de 4.096 bytes para a maioria das mensagens. Para mensagens enviadas para tópicos, o limite é de 2.048 bytes. O tamanho total da carga inclui chaves e valores. |
messaging/invalid-options | Um objeto de opções de mensagem inválido foi fornecido. A mensagem de erro deve conter informações adicionais. |
messaging/invalid-registration-token | Token de registro inválido fornecido. Certifique-se de que ele corresponda ao token de registro que o aplicativo cliente recebe ao se registrar no FCM. Não trunque ou adicione caracteres adicionais a ele. |
messaging/registration-token-not-registered | O token de registro fornecido não está registrado. Um token de registro anteriormente válido pode ser cancelado por vários motivos, incluindo:
|
messaging/invalid-package-name | A mensagem foi endereçada a um token de registro cujo nome de pacote não corresponde à opção restrictedPackageName fornecida. |
messaging/message-rate-exceeded | A taxa de mensagens para um determinado alvo é muito alta. Reduza o número de mensagens enviadas para este dispositivo ou tópico e não tente enviar novamente para este destino imediatamente. |
messaging/device-message-rate-exceeded | A taxa de mensagens para um determinado dispositivo é muito alta. Reduza o número de mensagens enviadas para este dispositivo e não tente enviar novamente para este dispositivo imediatamente. |
messaging/topics-message-rate-exceeded | A taxa de mensagens para assinantes de um determinado tópico é muito alta. Reduza o número de mensagens enviadas para este tópico e não tente enviar novamente para este tópico imediatamente. |
messaging/too-many-topics | Um token de registro foi inscrito no número máximo de tópicos e não pode mais ser inscrito. |
messaging/invalid-apns-credentials | Não foi possível enviar uma mensagem direcionada a um dispositivo Apple porque o certificado SSL de APNs necessário não foi carregado ou expirou. Verifique a validade dos seus certificados de desenvolvimento e produção. |
messaging/mismatched-credential | A credencial usada para autenticar este SDK não tem permissão para enviar mensagens ao dispositivo correspondente ao token de registro fornecido. Certifique-se de que a credencial e o token de registro pertençam ao mesmo projeto do Firebase. Consulte Adicionar o Firebase ao seu aplicativo para obter documentação sobre como autenticar os SDKs Admin do Firebase. |
messaging/authentication-error | O SDK não conseguiu autenticar nos servidores FCM. Certifique-se de autenticar o SDK Admin do Firebase com uma credencial que tenha as permissões adequadas para enviar mensagens do FCM. Consulte Adicionar o Firebase ao seu aplicativo para obter documentação sobre como autenticar os SDKs Admin do Firebase. |
messaging/server-unavailable | O servidor FCM não conseguiu processar a solicitação a tempo. Você deve tentar novamente a mesma solicitação, mas deve:
|
messaging/internal-error | O servidor FCM encontrou um erro ao tentar processar a solicitação. Você pode tentar novamente a mesma solicitação seguindo os requisitos listados na linha messaging/server-unavailable acima. Se o erro persistir, relate o problema ao nosso canal de suporte Bug Report . |
messaging/unknown-error | Um erro de servidor desconhecido foi retornado. Consulte a resposta bruta do servidor na mensagem de erro para obter mais detalhes. Se você receber esse erro, informe a mensagem de erro completa ao nosso canal de suporte de relatórios de bugs . |
Envie mensagens usando os protocolos legados do servidor de aplicativos
Se você estiver usando protocolos legados, crie solicitações de mensagens conforme mostrado nesta seção. Tenha em mente que, se você estiver enviando para múltiplas plataformas via HTTP, o protocolo v1 pode simplificar bastante suas solicitações de mensagens.
Envie mensagens para dispositivos específicos
Para enviar mensagens para dispositivos específicos, defina a chave to
como o token de registro da instância específica do aplicativo. Consulte as informações de configuração do cliente da sua plataforma para saber mais sobre tokens de registro.
Solicitação HTTP POST
https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{ "data": {
"score": "5x1",
"time": "15:10"
},
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}
Resposta HTTP
{ "multicast_id": 108, "success": 1, "failure": 0, "results": [ { "message_id": "1:08" } ] }
Mensagem XMPP
<message id="">
<gcm xmlns="google:mobile:data">
{ "data": {
"score": "5x1",
"time": "15:10"
},
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}
</gcm>
</message>
Resposta XMPP
<message id=""> <gcm xmlns="google:mobile:data"> { "from":"REGID", "message_id":"m-1366082849205" "message_type":"ack" } </gcm> </message>
O servidor de conexão XMPP oferece algumas outras opções de respostas. Consulte Formato de resposta do servidor .
Para obter a lista completa de opções de mensagens disponíveis ao enviar mensagens downstream para aplicativos cliente, consulte as informações de referência do protocolo do servidor de conexão escolhido, HTTP ou XMPP .
Envie mensagens para tópicos
Enviar mensagens para um tópico do Firebase Cloud Messaging é muito semelhante a enviar mensagens para um dispositivo individual ou para um grupo de usuários. O servidor de aplicativos define a chave to
com um valor como /topics/yourTopic
. Os desenvolvedores podem escolher qualquer nome de tópico que corresponda à expressão regular: "/topics/[a-zA-Z0-9-_.~%]+"
.
Para enviar combinações de vários tópicos, o servidor de aplicativos deve definir a chave condition
(em vez da chave to
) como uma condição booleana que especifica os tópicos de destino. Por exemplo, para enviar mensagens para dispositivos que assinaram TopicA
e TopicB
ou TopicC
:
'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)
O FCM primeiro avalia quaisquer condições entre parênteses e depois avalia a expressão da esquerda para a direita. Na expressão acima, um usuário inscrito em um único tópico não recebe a mensagem. Da mesma forma, um usuário que não assina o TopicA não recebe a mensagem. Estas combinações recebem:
- TópicoA e TópicoB
- TópicoA e TópicoC
Você pode incluir até cinco tópicos em sua expressão condicional, e há suporte para parênteses. Operadores suportados: &&
, ||
.
Solicitação HTTP POST do tópico
Envie para um único tópico:
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
Envie para dispositivos inscritos nos tópicos “cachorros” ou “gatos”:
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
Resposta HTTP do tópico
// Success example: { "message_id": "1023456" } // failure example: { "error": "TopicsMessageRateExceeded" }
Mensagem XMPP do tópico
Envie para um único tópico:
<message id="">
<gcm xmlns="google:mobile:data">
</gcm>
</message>
Envie para dispositivos inscritos nos tópicos “cachorros” ou “gatos”:
<message id=""> <gcm xmlns="google:mobile:data"> </gcm> </message>
Resposta do tópico XMPP
// Success example: { "message_id": "1023456" } // failure example: { "error": "TopicsMessageRateExceeded" }
Espere até 30 segundos de atraso antes que o servidor FCM retorne uma resposta de sucesso ou falha às solicitações de envio do tópico. Certifique-se de definir o valor de tempo limite do servidor de aplicativos na solicitação de acordo.
Envie mensagens para grupos de dispositivos
Enviar mensagens para um grupo de dispositivos usando APIs legadas obsoletas é muito semelhante a enviar mensagens para um dispositivo individual. Defina o parâmetro to
como a chave de notificação exclusiva para o grupo de dispositivos. Os exemplos nesta seção mostram como enviar mensagens de dados para grupos de dispositivos nos protocolos HTTP e XMPP legados.
Solicitação HTTP POST de grupo de dispositivos
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!", } }
Resposta HTTP do grupo de dispositivos
Aqui está um exemplo de "sucesso" - o notification_key
possui 2 tokens de registro associados a ele e a mensagem foi enviada com sucesso para ambos:
{ "success": 2, "failure": 0 }
Aqui está um exemplo de “sucesso parcial” — o notification_key
possui 3 tokens de registro associados a ele. A mensagem foi enviada com sucesso apenas para 1 dos tokens de registro. A mensagem de resposta lista os tokens de registro ( registration_ids
) que não receberam a mensagem:
{ "success":1, "failure":2, "failed_registration_ids":[ "regId1", "regId2" ] }
Quando uma mensagem não é entregue a um ou mais tokens de registro associados a um notification_key
, o servidor do aplicativo deve tentar novamente com espera entre as tentativas.
Se o servidor tentar enviar uma mensagem para um grupo de dispositivos que não possui membros, a resposta será semelhante a esta, com 0 sucesso e 0 falha:
{ "success": 0, "failure": 0 }
Mensagem XMPP do grupo de dispositivos
<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>
Resposta XMPP do grupo de dispositivos
Quando a mensagem é enviada com sucesso para qualquer um dos dispositivos do grupo, o servidor de conexão XMPP responde com um ACK. Se todas as mensagens enviadas para todos os dispositivos do grupo falharem, o servidor de conexão XMPP responderá com um NACK.
Aqui está um exemplo de “sucesso” — o notification_key
possui 3 tokens de registro associados a ele e a mensagem foi enviada com sucesso para todos eles:
{ "from": "aUniqueKey", "message_type": "ack", "success": 3, "failure": 0, "message_id": "m-1366082849205" }
Aqui está um exemplo de “sucesso parcial” — o notification_key
possui 3 tokens de registro associados a ele. A mensagem foi enviada com sucesso apenas para 1 dos tokens de registro. A mensagem de resposta lista os tokens de registro que não receberam a mensagem:
{ "from": "aUniqueKey", "message_type": "ack", "success":1, "failure":2, "failed_registration_ids":[ "regId1", "regId2" ] }
Quando o servidor de conexão FCM não consegue entregar a todos os dispositivos do grupo. O servidor de aplicativos receberá uma resposta nack.
Para obter a lista completa de opções de mensagens, consulte as informações de referência do protocolo do servidor de conexão escolhido, HTTP ou XMPP .
Métodos de envio legados do SDK Admin do Firebase
O SDK Admin Node.js do Firebase oferece suporte a métodos de envio de mensagens (FCM) com base na API do servidor FCM legado . Esses métodos aceitam argumentos diferentes em comparação com o método send()
. Você deve usar o método send()
sempre que possível e usar apenas os métodos descritos nesta página ao enviar mensagens para dispositivos individuais ou grupos de dispositivos.
Envie para dispositivos individuais
Você pode passar um token de registro para o método sendToDevice()
para enviar uma mensagem para esse dispositivo:
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);
});
O método sendToDevice()
também pode enviar uma mensagem multicast (ou seja, uma mensagem para vários dispositivos) passando uma matriz de tokens de registro em vez de apenas um único token de registro:
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);
});
O método sendToDevice()
retorna uma promessa que é resolvida com um objeto MessagingDevicesResponse
contendo a resposta do FCM. O tipo de retorno tem o mesmo formato ao passar um único token de registro ou uma matriz de tokens de registro.
Alguns casos, como erro de autenticação ou limitação de taxa, fazem com que a mensagem inteira não seja processada. Nestes casos, a promessa retornada por sendToDevice()
é rejeitada com erro. Para obter uma lista completa de códigos de erro, incluindo descrições e etapas de resolução, consulte Erros da API Admin FCM .
Enviar para um grupo de dispositivos
O método sendToDeviceGroup()
permite enviar uma mensagem para um grupo de dispositivos especificando a chave de notificação para esse grupo de dispositivos:
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);
});
O método sendToDeviceGroup()
retorna uma promessa que é resolvida com um objeto MessagingDevicesResponse
contendo a resposta do FCM.
Alguns casos, como erro de autenticação ou limitação de taxa, fazem com que a mensagem inteira não seja processada. Nestes casos, a promessa retornada por sendToDeviceGroup()
é rejeitada com erro. Para obter uma lista completa de códigos de erro, incluindo descrições e etapas de resolução, consulte Erros da API Admin FCM .
Definindo a carga útil da mensagem
Os métodos acima, baseados nos protocolos legados do FCM, aceitam uma carga útil de mensagem como segundo argumento e suportam mensagens de notificação e de dados . Você pode especificar um ou ambos os tipos de mensagem criando um objeto com os data
e/ou chaves notification
. Por exemplo, veja como definir diferentes tipos de cargas de mensagens:
Mensagem de notificação
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.'
}
};
Mensagem de dados
const payload = {
data: {
score: '850',
time: '2:45'
}
};
Mensagem combinada
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'
}
};
As cargas úteis das mensagens de notificação têm um subconjunto predefinido de propriedades válidas e diferem ligeiramente dependendo de qual sistema operacional móvel você está direcionando. Consulte os documentos de referência para NotificationMessagePayload
para obter uma lista completa.
As cargas úteis das mensagens de dados são compostas por pares de valores-chave personalizados com algumas restrições, incluindo o fato de que todos os valores devem ser strings. Consulte a documentação de referência do DataMessagePayload
para obter uma lista completa de restrições.
Definindo as opções de mensagem
Os métodos acima baseados nos protocolos legados do FCM aceitam um terceiro argumento opcional especificando algumas opções para a mensagem. Por exemplo, o exemplo a seguir envia uma mensagem de alta prioridade para um dispositivo que expira após 24 horas:
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);
});
Consulte a documentação de referência de MessagingOptions
para obter uma lista completa das opções disponíveis.