Ao usar os protocolos do SDK Admin do Firebase ou do servidor de apps do FCM, crie solicitações de mensagens e envie-as a estes tipos de destinos:
- Nome do tópico
- Condição
- Token de registro do dispositivo
- Nome do grupo de dispositivos (somente protocolos legados e o SDK Admin do Firebase para Node.js)
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 SDK Admin do Firebase, que é compatível com Node, Java, Python, C# e Go, além do protocolo v1 HTTP. Você também verá orientações para enviar mensagens usando os protocolos HTTP e XMPP legados.
Enviar mensagens a 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 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"
}
Enviar mensagens a vários dispositivos
A API REST e as APIs Admin FCM permitem que você faça o multicast de uma mensagem para uma lista de tokens de registro do 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.SendMulticastAsync(message);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");
REST
Crie uma solicitação HTTP em lote:
--subrequest_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary
POST /v1/projects/myproject-b5ae1/messages:send
Content-Type: application/json
accept: application/json
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"notification":{
"title":"FCM Message",
"body":"This is an FCM notification message!"
}
}
}
...
--subrequest_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary
POST /v1/projects/myproject-b5ae1/messages:send
Content-Type: application/json
accept: application/json
{
"message":{
"token":"cR1rjyj4_Kc:APA91bGusqbypSuMdsh7jSNrW4nzsM...",
"notification":{
"title":"FCM Message",
"body":"This is an FCM notification message!"
}
}
}
--subrequest_boundary--
Salve a solicitação em um arquivo (neste exemplo, batch_request.txt). Em seguida, use o comando cURL:
curl --data-binary @batch_request.txt -H 'Content-Type: multipart/mixed; boundary="subrequest_boundary"' -H 'Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA' https://fcm.googleapis.com/batch
Para SDKs Admin do Firebase, essa operação usa a API sendAll() em segundo plano, conforme mostrado nos exemplos. O valor de retorno
é um BatchResponse em que a lista de respostas 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.SendMulticastAsync(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}");
}
REST
Cada subenvio de envio retorna uma resposta. As respostas são separadas por uma string de limite de resposta começando com --batch_.
--batch_nDhMX4IzFTDLsCJ3kHH7v_44ua-aJT6q
Content-Type: application/http
Content-ID: response-
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Vary: Origin
Vary: X-Origin
Vary: Referer
{
"name": "projects/35006771263/messages/0:1570471792141125%43c11b7043c11b70"
}
...
--batch_nDhMX4IzFTDLsCJ3kHH7v_44ua-aJT6q
Content-Type: application/http
Content-ID: response-
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Vary: Origin
Vary: X-Origin
Vary: Referer
{
"name": "projects/35006771263/messages/0:1570471792141696%43c11b7043c11b70"
}
--batch_nDhMX4IzFTDLsCJ3kHH7v_44ua-aJT6q--
Enviar mensagens a 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 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 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
Enviar um lote de mensagens
A API REST e 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.SendAllAsync(messages);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");
REST
Crie uma solicitação HTTP em lote combinando uma lista de solicitações secundárias:
--subrequest_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary
POST /v1/projects/myproject-b5ae1/messages:send
Content-Type: application/json
accept: application/json
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"notification":{
"title":"FCM Message",
"body":"This is an FCM notification message to device 0!"
}
}
}
--subrequest_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary
POST /v1/projects/myproject-b5ae1/messages:send
Content-Type: application/json
accept: application/json
{
"message":{
"topic":"readers-club",
"notification":{
"title":"Price drop",
"body":"2% off all books"
}
}
}
...
--subrequest_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary
POST /v1/projects/myproject-b5ae1/messages:send
Content-Type: application/json
accept: application/json
{
"message":{
"token":"cR1rjyj4_Kc:APA91bGusqbypSuMdsh7jSNrW4nzsM...",
"notification":{
"title":"FCM Message",
"body":"This is an FCM notification message to device N!"
}
}
}
--subrequest_boundary--
É possível consultar o BatchResponse retornado para verificar quantas mensagens foram entregues ao FCM com êxito. Ele também expõe uma lista de respostas que podem ser usadas para verificar o estado de mensagens individuais.
A ordem das respostas corresponde à ordem das mensagens na lista de entrada.
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. 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. 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 SDK Admin do Firebase e o protocolo HTTP v1 do FCM permitem que as solicitações de
mensagens configurem todos os campos disponíveis no
objeto
message. Incluindo:
- 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 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 não ter sido registrado 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 Firebase ao seu app para ver uma documentação sobre como autenticar os SDKs Admin do Firebase. |
messaging/authentication-error |
O SDK não conseguiu se autenticar com os servidores do FCM. Autentique o SDK Admin do Firebase com uma credencial que tenha as permissões adequadas para enviar mensagens do FCM. Consulte Adicionar Firebase ao seu app para ver uma documentação sobre como autenticar os SDKs Admin do Firebase. |
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ê preferir usar os protocolos legados, crie solicitações de mensagens como as mostradas nesta seção. Tenha em mente que, se você estiver enviando para várias plataformas via HTTP, o protocolo v1 pode simplificar as solicitações de mensagens.
Enviar mensagens a 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.
Enviar mensagens a tópicos
O envio de mensagens a um tópico do Firebase Cloud Messaging é muito semelhante ao envio a um dispositivo individual ou a 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 é similar ao envio
para um dispositivo individual. Defina o parâmetro to
como a chave de notificação exclusiva do grupo. Consulte
Tipos de mensagem para mais detalhes sobre o
suporte ao payload. Os exemplos nesta página 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
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 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 sobre o protocolo do servidor de conexão selecionado, HTTP ou XMPP.
Métodos de envio legados do SDK Admin do Firebase
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 um 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 FCM.
Enviar para um grupo de dispositivos
Com as mensagens para grupos de dispositivos, é possível adicionar vários dispositivos a um único grupo. Esse processo é semelhante ao das mensagens de tópico, mas inclui a autenticação para garantir que a associação ao grupo seja gerenciada apenas pelos seus servidores. Por exemplo, se você quiser enviar mensagens diferentes para diferentes modelos de smartphone, seus servidores poderão adicionar/remover registros dos grupos e enviar a mensagem relevante para cada um deles. A diferença entre as mensagens para grupos de dispositivos e as mensagens de tópico é que, no primeiro caso, o gerenciamento de grupos de dispositivos é feito usando os servidores em vez de diretamente no aplicativo.
É possível usar mensagens para grupos de dispositivos com os protocolos XMPP ou HTTP legados no servidor de apps. As versões mais antigas do SDK Admin do Firebase para Node.js são baseadas em protocolos legados e também fornecem recursos de mensagens para grupos de dispositivos. O número máximo permitido de membros em uma chave de notificação é 20.
Crie grupos de dispositivos e gere chaves de notificação usando um servidor de aplicativos ou um cliente Android. Para mais detalhes, consulte Como gerenciar grupos 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 totalidade
da mensagem não seja processada. Nesses casos, a promessa retornada por sendToDeviceGroup() é rejeitada com um 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 FCM.
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.
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 que expira após 24 horas a um dispositivo:
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.