Ao usar os protocolos do servidor de apps Firebase Admin SDK ou FCM, é possível criar solicitações de mensagens e enviá-las a aos tipos de destino a seguir:
- Nome do tópico
- Condição
- Token de registro do dispositivo
- Nome do grupo de dispositivos (somente protocolo)
O payload de notificação das mensagens enviadas pode ser composto por campos predefinidos, por um payload de dados com seus próprios campos definidos por usuário ou por ambos. Consulte Tipos de mensagens para mais informações.
Nos exemplos desta página, mostramos como enviar mensagens de notificação com o Firebase Admin SDK (que é compatível com Node, Java, Python, C# e Go) e o protocolo v1 HTTP. Você também verá orientações para enviar mensagens usando os protocolos HTTP e XMPP legados descontinuados.
Como enviar mensagens para dispositivos específicos
Para enviar para um único dispositivo específico, transmita o token de registro do dispositivo, conforme mostrado. Consulte as informações de configuração do cliente da sua plataforma para saber mais sobre esses tokens.
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"
}
}
}
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
Se for bem-sucedido, cada método de envio retorna um ID de mensagem. O Firebase Admin SDK 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"
}
Como enviar mensagens para vários dispositivos
As APIs Admin FCM permitem fazer multicast de uma mensagem para uma lista de tokens de registro de dispositivo. É possível especificar até 500 tokens de registro de dispositivo por invocação.
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");
O valor de retorno é uma lista de tokens que corresponde à ordem dos tokens de entrada. Isso é útil quando se quer 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);
}
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}");
}
Como enviar mensagens para tópicos
Depois de criar um tópico, seja inscrevendo instâncias do app cliente no tópico do lado do cliente ou usando a API do servidor, será possível enviar mensagens ao tópico. Se esta for a primeira vez que você cria solicitações de envio para o FCM, consulte o guia do ambiente do servidor e o FCM para informações gerais importantes e sobre configuração.
Na sua lógica de envio no back-end, especifique o nome do tópico desejado conforme mostrado abaixo:
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"
}
}
}
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 seguinte condição vai enviar mensagens para
dispositivos que estão inscritos em TopicA e TopicB ou TopicC:
"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"
No FCM, todas as condições entre parênteses são avaliadas primeiro e depois
expressão é analisada da esquerda para a direita. Na expressão acima, um usuário que se inscreveu em um
só tópico não receberá a mensagem. Do mesmo modo, um usuário que não
se inscreveu em TopicA também não receberá a mensagem. Somente estas combinações
são válidas:
TopicAeTopicBTopicAeTopicC
Você pode incluir até cinco tópicos na 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);
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",
}
}
}
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
Como enviar mensagens para grupos de dispositivos
Para enviar mensagens a grupos de dispositivos, use a API HTTP v1. Se você estiver enviando para grupos de dispositivos usando as APIs de envio legadas descontinuadas para HTTP ou XMPP, ou qualquer uma das versões mais antigas do Firebase Admin SDK para Node.js com base nos protocolos legados, recomendamos migrar para a API HTTP v1 assim que possível. As APIs de envio legadas serão desativadas e removidas em junho de 2024.
O envio de mensagens para um grupo de dispositivos é muito semelhante ao envio
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:
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!"
}
}
}
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
Enviar um lote de mensagens
Os SDKs Admin são compatíveis com o envio de mensagens em lotes. É possível agrupar até 500 mensagens em um único lote e enviá-las em uma única chamada de API, com uma melhoria de desempenho significativa em relação ao envio de solicitações HTTP separadas para cada mensagem.
Esse recurso pode ser usado para criar 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, for necessário enviar simultaneamente mensagens 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");
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");
Como enviar mensagens ativadas para inicialização direta (somente Android)
É possível enviar mensagens para dispositivos no modo de inicialização direta usando as APIs HTTP v1 ou HTTP legadas. Antes do envio para dispositivos no modo de inicialização direta, conclua as etapas para permitir que os dispositivos clientes recebam mensagens do FCM no modo de inicialização direta.
Enviar usando a API HTTP v1 do FCM
A solicitação de mensagem precisa 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 de mensagem precisa 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 essa chave no corpo da solicitação podem ser processadas por apps em dispositivos que estão atualmente no modo de inicialização direta (e também quando não estão nesse modo).
Personalizar mensagens entre plataformas
O Firebase Admin SDK e o protocolo HTTP v1 do FCM permitem que as solicitações de
mensagens configurem todos os campos disponíveis no
objeto
message. Isso inclui:
- Um conjunto comum de campos a serem interpretados por todas as instâncias do app que recebem a mensagem.
- Conjuntos de campos específicos da plataforma, como
AndroidConfigeWebpushConfig, interpretados apenas pelas instâncias do app em execução na plataforma especificada.
Os blocos específicos da plataforma oferecem flexibilidade para personalizar mensagens em plataformas diferentes, garantindo, assim, que elas sejam gerenciadas corretamente quando recebidas. O back-end do FCM considerará todos os parâmetros especificados e personalizará a mensagem para cada plataforma.
Quando usar campos comuns
Use campos comuns ao:
- segmentar instâncias de aplicativos em todas as plataformas: Apple, Android e Web;
- enviar mensagens para tópicos.
Todas as instâncias do app, independentemente da plataforma, podem interpretar os seguintes campos comuns:
Quando usar campos específicos da plataforma
Use campos específicos da plataforma quando quiser:
- enviar campos apenas para plataformas específicas;
- enviar campos específicos da plataforma, além dos campos comuns.
Sempre que você quiser enviar valores apenas para plataformas específicas, não use campos comuns. Em vez disso, use campos específicos da plataforma. Por exemplo, para enviar uma notificação apenas para as plataformas Apple e Web, mas não para o Android, use dois conjuntos de campos separados, um para a Apple e outro para a Web.
Ao enviar mensagens com opções de entrega específicas, use os campos específicos da plataforma para configurá-las. É possível especificar valores diferentes por plataforma, se você quiser. No entanto, mesmo quando você quiser definir essencialmente o mesmo valor em todas as plataformas, é necessário usar campos específicos da plataforma. Isso ocorre porque o valor pode ser interpretado de maneira ligeiramente diferente dependendo da plataforma. Por exemplo, no Android, a vida útil é definida como um prazo de validade em segundos. Já na Apple, é definida como uma data de validade.
Exemplo: mensagem de notificação com opções de cor e ícone
A solicitação de exemplo a seguir envia o título e o conteúdo de uma notificação comum para todas as plataformas, mas também inclui algumas substituições específicas da plataforma para dispositivos Android.
Para Android, a solicitação define uma cor e um ícone especiais para exibir nos dispositivos. Conforme observado na AndroidNotification, a cor é especificada no formato #rrggbb, e a imagem precisa ser um recurso de ícone drawable local para o app Android.
Esta é 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();
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"
}
}
}
}
Consulte a documentação de referência HTTP v1 para mais detalhes sobre as chaves disponíveis em blocos específicos da plataforma no corpo da mensagem.
Exemplo: mensagem de notificação com uma 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. Esta é 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);
});
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"
}
}
}
}
Consulte a documentação de referência HTTP v1 para mais detalhes 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 realizar em resposta ao usuário que interage com a notificação. Esta é 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);
});
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"
}
}
}
}
Consulte a documentação de referência HTTP v1 para mais detalhes 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. Esta é 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);
});
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"],
},
},
},
},
},
}'
Consulte a documentação de referência HTTP v1 para mais detalhes 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 do erro, uma mensagem de erro e o status do erro.
Eles também podem conter uma matriz details com mais detalhes sobre o erro.
Veja 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 tipos de valores diferentes. O primeiro exemplo tem o tipo type.googleapis.com/google.rpc.BadRequest, indicando um erro nos valores da solicitação. O segundo exemplo com o tipo type.googleapis.com/google.firebase.fcm.v1.FcmError tem 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 resolução.
A tabela a seguir lista os códigos de erro da API REST do FCM v1 e as respectivas descrições.
| Código do erro | Etapas de descrição e resolução |
|---|---|
UNSPECIFIED_ERROR Não há mais informações disponíveis sobre esse erro. |
Nenhuma. |
INVALID_ARGUMENT (código do 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ê transmite ao servidor. Verifique se ele corresponde ao token de registro que o app cliente recebe ao se registrar no FCM. Não faça truncamento nem adicione caracteres. Nome de pacote inválido: verifique se a mensagem foi endereçada a um token de registro cujo nome do pacote corresponde ao valor transmitido na solicitação. Mensagem muito grande: verifique se o tamanho total dos dados de payload 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. Inclui as chaves e os valores. Chave de dados inválida: verifique se os dados de payload não contêm uma chave (como "from", "gcm" ou qualquer valor com prefixo "google") usada internamente pelo FCM. Algumas palavras (como collapse_key) também são usadas pelo FCM, mas são permitidas no payload. Nesse caso, o valor do payload 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 do erro HTTP = 404) A instância do app teve a inscrição cancelada do FCM. Isso geralmente significa que o token usado não é mais válido e deve ser usado um novo. |
Esse erro pode ser causado por tokens de registro ausentes ou tokens com inscrição cancelada. 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 atual pode deixar de ser válido em diversos cenários, incluindo: - se o app cliente cancelar a inscrição com o FCM. - se o app cliente tiver a inscrição cancelada automaticamente, algo que pode ocorrer se o usuário desinstalar o aplicativo. Por exemplo, no iOS, se o serviço de feedback de APNs informou o token de APNs como inválido. - se o token de registro expirar, por exemplo, se o Google atualizar os tokens de registro, ou o token de APNs expirou para dispositivos iOS. - Quando o app cliente está atualizado, mas a nova versão não está configurada para receber mensagens. Para todos esses casos, remova o token de registro do servidor do app e pare de usá-lo para enviar mensagens. |
SENDER_ID_MISMATCH (código do 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 app cliente se registra no FCM, os remetentes autorizados a enviar mensagens precisam ser especificados. Use um desses IDs de remetente ao enviar mensagens ao app cliente. Quando você muda para outro remetente, os tokens de registro existentes não funcionam. |
QUOTA_EXCEEDED (código do erro HTTP = 429) O limite de envio foi excedido para o destino da mensagem. Uma extensão do tipo google.rpc.QuotaFailure é retornada para especificar qual cota foi excedida. |
Esse erro pode ser causado por ter excedido a cota de taxa de mensagens, a cota de taxa de mensagens do dispositivo ou a cota de taxa de mensagens de tópico. Taxa de mensagens excedida: a taxa de envio de mensagens está muito alta. Reduza a taxa geral de envio de mensagens. Use a espera exponencial com um delay inicial mínimo de um minuto para tentar enviar novamente as mensagens rejeitadas. Taxa de mensagens do dispositivo excedida: a taxa de mensagens para um determinado dispositivo está muito alta. Consulte Limite de taxa de mensagens para um único dispositivo. Reduza o número de mensagens enviadas a esse dispositivo e use espera exponencial para tentar novamente o envio. Taxa de mensagens de tópico excedida: a taxa de mensagens para assinantes de um determinado tópico está muito alta. Reduza o número de mensagens enviadas a esse tópico e use a espera exponencial com um delay inicial mínimo de 1 minuto para tentar novamente o envio. |
UNAVAILABLE (código do erro HTTP = 503) O servidor está sobrecarregado. |
A solicitação não foi processada a tempo no servidor. Tente enviar a mesma solicitação novamente. Para isso, é necessário: - Respeitar o cabeçalho Retry-After se ele estiver incluído na resposta do servidor de conexão do FCM. - implementar uma retirada exponencial no mecanismo de nova tentativa. Por exemplo, se você esperou um segundo antes da primeira nova tentativa, aguarde pelo menos dois segundos antes da próxima, depois quatro segundos e assim por diante. Se você estiver enviando várias mensagens, considere aplicar a instabilidade. Para mais informações, consulte Como lidar com novas tentativas Os remetentes que causam problemas podem ser incluídos em listas de proibições. |
INTERNAL (código do erro HTTP = 500) Ocorreu um erro interno desconhecido. |
O servidor encontrou um erro enquanto tentava processar a solicitação. Repita a mesma solicitação seguindo as sugestões em Como lidar com novas tentativas. Se o erro persistir, entre em contato com o suporte do Firebase. |
THIRD_PARTY_AUTH_ERROR (código do erro HTTP = 401) O certificado de APNs ou a chave de autenticação por push na Web era inválido ou estava ausente. |
Não foi possível enviar uma mensagem direcionada a um dispositivo iOS ou um registro de push da Web. Verifique a validade das credenciais de desenvolvimento e produção. |
Códigos de erro do administrador
Confira na tabela a seguir os códigos de erro da API Firebase Admin FCM e a descrição de cada erro, incluindo as etapas de resolução recomendadas.
| Código do erro | Etapas de descrição e resolução |
|---|---|
messaging/invalid-argument |
Um argumento inválido foi fornecido a um método do FCM. A mensagem de erro deve conter informações adicionais. |
messaging/invalid-recipient |
O destinatário da mensagem pretendida é inválido. A mensagem de erro deve conter informações adicionais. |
messaging/invalid-payload |
Um objeto de payload de mensagem inválido foi fornecido. A mensagem de erro deve conter informações adicionais. |
messaging/invalid-data-payload-key |
O payload da mensagem de dados contém uma chave inválida. Consulte a
documentação de referência de
DataMessagePayload para mais detalhes sobre chaves restritas.
|
messaging/payload-size-limit-exceeded |
O payload da mensagem fornecido 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 do payload total 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 |
Um token de registro inválido foi fornecido. Verifique se ele corresponde ao token de registro que o app cliente recebe ao se registrar no FCM. Não faça truncagem nem acrescente caracteres adicionais. |
messaging/registration-token-not-registered |
O token de registro fornecido não está registrado. Um token de registro
anteriormente válido pode ter a inscrição cancelada por várias razões,
incluindo:
|
messaging/invalid-package-name |
A mensagem foi encaminhada a um token de registro e o nome do pacote dele
não corresponde à opção
restrictedPackageName fornecida.
|
messaging/message-rate-exceeded |
A taxa de mensagens para um determinado destino é muito alta. Reduza o número de mensagens enviadas a esse dispositivo e não tente reenviar mensagens ao mesmo dispositivo imediatamente. |
messaging/device-message-rate-exceeded |
A taxa de mensagens para um determinado dispositivo é muito alta. Reduza o número de mensagens enviadas a esse dispositivo e não tente reenviar mensagens a esse dispositivo imediatamente. |
messaging/topics-message-rate-exceeded |
A taxa de mensagens para assinantes de um determinado tópico está muito alta. Reduza o número de mensagens enviadas a esse tópico e não tente reenviar mensagens a esse 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 ser inscrito em mais. |
messaging/invalid-apns-credentials |
Uma mensagem direcionada a um dispositivo Apple não conseguiu ser enviada porque o certificado obrigatório de SSL de APNs não foi enviado ou expirou. Verifique a validade de seus certificados de desenvolvimento e produção. |
messaging/mismatched-credential |
A credencial utilizada para autenticar esse SDK não tem permissão para enviar mensagens ao dispositivo correspondente ao token de registro fornecido. Verifique se o token de registro e a credencial pertencem ao mesmo projeto do Firebase. Consulte Adicionar o Firebase ao seu app para conferir a documentação sobre como autenticar os Firebase Admin SDKs. |
messaging/authentication-error |
O SDK não conseguiu se autenticar com os servidores do FCM. Certifique-se de autenticar o Firebase Admin SDK com uma credencial que tenha as adequadas permissões para enviar mensagens FCM. Consulte Adicionar o Firebase ao seu app para conferir a documentação sobre como autenticar os Firebase Admin SDKs. |
messaging/server-unavailable |
O servidor do FCM não conseguiu processar a solicitação a tempo. Repita
o mesmo pedido, mas é necessário:
|
messaging/internal-error |
O servidor do FCM encontrou um erro enquanto tentava processar a
solicitação. Repita a mesma solicitação seguindo os requisitos
listados na linha messaging/server-unavailable acima. Se o
erro persistir, informe o problema para nosso
canal de suporte Relatório de bugs.
|
messaging/unknown-error |
Um erro de servidor desconhecido foi retornado. Veja a resposta do servidor bruto na mensagem de erro para saber mais. Se você receber esse erro, informe a mensagem completa no nosso canal de suporte Relatório de bugs. |
Enviar mensagens usando os protocolos do servidor de apps legados
Se você estiver usando os protocolos legados, crie solicitações de mensagens conforme mostrado nesta seção. Tenha em mente que, se você estiver enviando para várias plataformas via HTTP, o protocolo v1 pode simplificar bastante as solicitações de mensagens.
Como enviar mensagens para dispositivos específicos
Para enviar mensagens a dispositivos específicos, defina a chave to como o token de registro da instância de app. Consulte as informações de configuração do cliente da sua plataforma para saber mais sobre esses tokens.
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>
No servidor de conexão XMPP, há outras opções de resposta. Consulte Formato de resposta do servidor.
Para ver a lista completa de opções de mensagens disponíveis ao enviar mensagens downstream a apps clientes, consulte as informações de referência do protocolo do servidor de conexão selecionado, HTTP ou XMPP.
Como enviar mensagens para tópicos
O envio de mensagens para um tópico Firebase Cloud Messaging é muito semelhante ao
envio de mensagens para um dispositivo individual ou um grupo de usuários. O servidor
do app define a chave to com um valor como /topics/yourTopic.
Os desenvolvedores
podem escolher um nome de tópico que corresponda à seguinte expressão regular:
"/topics/[a-zA-Z0-9-_.~%]+".
Para enviar a combinações de vários tópicos, o servidor de apps precisa 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 estão inscritos
em TopicA e TopicB ou
TopicC:
'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)
No FCM, todas as condições entre parênteses são avaliadas primeiro e depois a expressão é analisada da esquerda para a direita. Na expressão acima, um usuário que se inscreveu em um só tópico não receberá a mensagem. Do mesmo modo, um usuário que não se inscreveu no TopicA também não receberá a mensagem. As seguintes combinações receberão a mensagem:
- TopicA e TopicB
- TopicA e TopicC
Inclua até cinco tópicos em sua expressão condicional, e parênteses são aceitos.
Operadores compatíveis: &&, ||.
Solicitação HTTP POST de tópico
Enviar para um único tópico:
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
Enviar para dispositivos inscritos nos tópicos "dogs" ou "cats":
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
Resposta HTTP de tópico
// Success example:
{
"message_id": "1023456"
}
// failure example:
{
"error": "TopicsMessageRateExceeded"
}
Mensagem XMPP de tópico
Enviar para um único tópico:
<message id="">
<gcm xmlns="google:mobile:data">
</gcm>
</message>
Enviar para dispositivos inscritos nos tópicos "dogs" ou "cats":
<message id=""> <gcm xmlns="google:mobile:data"> </gcm> </message>
Resposta XMPP de tópico
// Success example:
{
"message_id": "1023456"
}
// failure example:
{
"error": "TopicsMessageRateExceeded"
}
Aguarde até 30 segundos para que o servidor de conexão do FCM retorne uma resposta de êxito ou falha para as solicitações de envio de tópico. Defina corretamente o valor de tempo limite do servidor do app na solicitação.
Como enviar mensagens para grupos de dispositivos
O envio de mensagens para um grupo de dispositivos usando as APIs legadas e descontinuadas
é muito semelhante ao envio de
mensagens para um dispositivo individual.
Defina o parâmetro to
como a chave de notificação exclusiva do grupo.
Os exemplos nesta seção mostram como enviar mensagens
de dados para esses grupos de dispositivos nos protocolos HTTP e XMPP legados.
Solicitação HTTP POST para 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
Este é um exemplo de êxito na operação: a notification_key
tem dois tokens de registro associados a ela e a mensagem foi
enviada a ambos:
{
"success": 2,
"failure": 0
}
Este é um exemplo de "êxito parcial" na operação: a
notification_key tem três tokens de registro associados
a ela. A mensagem foi enviada apenas para um dos
tokens de registro. A mensagem da resposta lista os tokens
(registration_ids) onde houve falha ao receber 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 uma notification_key,
o servidor do app faz uma nova tentativa com um intervalo de espera entre elas.
Se o servidor tenta enviar uma mensagem para um grupo de dispositivos que não tem membros, a resposta é parecida com esta, com 0 sucesso e 0 falha:
{
"success": 0,
"failure": 0
}
Mensagem XMPP para 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ões XMPP responde com um ACK. Quando ocorre falha no envio de todas as mensagens a todos os dispositivos do grupo, o servidor responde com um NACK.
Este é um exemplo de "êxito" na operação: a notification_key
tem três tokens de registro associados a ela e a mensagem foi
enviada a todos:
{
"from": "aUniqueKey",
"message_type": "ack",
"success": 3,
"failure": 0,
"message_id": "m-1366082849205"
}
Este é um exemplo de "êxito parcial" na operação: a
notification_key tem três tokens de registro associados
a ela. A mensagem foi enviada apenas para um 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 um servidor de conexão do FCM não entrega para todos os dispositivos no grupo. o servidor do app receberá uma resposta NACK.
Para ver a lista completa de opções de mensagens, consulte as informações de referência do protocolo do servidor de conexão selecionado, HTTP ou XMPP.
Métodos de envio legados do Firebase Admin SDK
O SDK Admin para Node.js do Firebase oferece suporte a métodos de envio
de mensagens (FCM) baseados na
API legada do servidor do FCM.
Esses métodos aceitam argumentos diferentes em comparação com o método send().
Use o método send() sempre que possível e utilize os
métodos descritos nesta página apenas ao enviar mensagens para dispositivos individuais ou
grupos de dispositivos.
Enviar para dispositivos individuais
É possível transmitir um token de registro ao método
sendToDevice()
para enviar uma mensagem a 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, para vários dispositivos) ao transmitir 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, seja para transmitir um único token de registro ou uma matriz de
tokens.
Alguns casos, como um erro de autenticação ou limitação de taxa, fazem com que a totalidade
da mensagem não seja processada. Nesses casos, a promessa retornada por
sendToDevice() é rejeitada com erro. Para ver uma lista completa de códigos de erro,
incluindo descrições e etapas de solução de problemas, consulte
Erros da API Admin do FCM.
Como enviar para um grupo de dispositivos
Com o método
sendToDeviceGroup(),
é possível enviar uma mensagem para um grupo de dispositivos ao especificar a
chave de notificação para ele:
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 um erro de autenticação ou limitação de taxa, fazem com que a mensagem
inteira não seja processada. Nesses casos, a promessa retornada por
sendToDeviceGroup() é rejeitada com erro. Para ver uma lista completa de códigos de erro,
incluindo descrições e etapas de solução de problemas, consulte
Erros da API Admin do FCM.
Como definir o payload da mensagem
Os métodos acima baseados nos protocolos legados do FCM
aceitam um payload da mensagem como segundo argumento e oferecem suporte
a
mensagens de notificação e de dados.
Especifique um ou ambos os tipos de mensagens criando um objeto com as chaves de data
e/ou notification. Por exemplo, veja como definir diferentes tipos
de payloads 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'
}
};
Os payloads das mensagens de notificação têm um subconjunto predefinido de propriedades válidas e
diferem ligeiramente, dependendo de qual sistema operacional móvel é o objeto das suas atividades.
Consulte a documentação de referência de
NotificationMessagePayload
para ver uma lista completa.
Os payloads das mensagens de dados são compostos por pares de chave-valor personalizados com algumas
restrições, incluindo o fato de que todos os valores precisam ser strings. Para ver uma lista completa de restrições, consulte a documentação de referência de DataMessagePayload.
Como definir as opções de mensagem
Os métodos acima baseados nos protocolos legados do FCM aceitam um terceiro argumento opcional que especifica algumas opções para a mensagem. Veja no exemplo a seguir o envio de uma mensagem de alta prioridade a 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);
});
Para ver uma lista completa das opções disponíveis,
consulte a documentação de referência de
MessagingOptions.