Acompanhe tudo o que foi anunciado no Firebase Summit e saiba como usar o Firebase para acelerar o desenvolvimento de apps e executá-los com confiança. Saiba mais

Criar solicitações de envio do servidor de aplicativos

Usando o SDK Admin do Firebase ou os protocolos do servidor de aplicativos do FCM, você pode criar solicitações de mensagens e enviá-las para estes tipos de destino:

  • Nome do tópico
  • Doença
  • Token de registro do dispositivo
  • Nome do grupo de dispositivos (protocolos legados e SDK Admin do Firebase apenas para Node.js)

Você pode enviar mensagens com uma carga de notificação composta de campos predefinidos, uma carga de dados de seus próprios campos definidos pelo usuário ou uma mensagem contendo os dois tipos de carga. Consulte Tipos de mensagem para obter mais informações.

Os exemplos nesta página mostram como enviar mensagens de notificação usando o SDK Admin do Firebase (que tem suporte para Node , Java , Python , C# e Go ) e o protocolo HTTP v1 . Também há orientação para o envio de mensagens por meio dos protocolos HTTP e XMPP herdados .

Envie mensagens para dispositivos específicos

Para enviar para um único dispositivo específico, passe o token de registro do dispositivo conforme mostrado. Consulte as informações de configuração do cliente para sua plataforma para saber mais sobre tokens de registro.

Node.js

// This registration token comes from the client FCM SDKs.
const registrationToken = 'YOUR_REGISTRATION_TOKEN';

const message = {
  data: {
    score: '850',
    time: '2:45'
  },
  token: registrationToken
};

// Send a message to the device corresponding to the provided
// registration token.
getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

// This registration token comes from the client FCM SDKs.
String registrationToken = "YOUR_REGISTRATION_TOKEN";

// See documentation on defining a message payload.
Message message = Message.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .setToken(registrationToken)
    .build();

// Send a message to the device corresponding to the provided
// registration token.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);

Pitão

# This registration token comes from the client FCM SDKs.
registration_token = 'YOUR_REGISTRATION_TOKEN'

# See documentation on defining a message payload.
message = messaging.Message(
    data={
        'score': '850',
        'time': '2:45',
    },
    token=registration_token,
)

# Send a message to the device corresponding to the provided
# registration token.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)

Vai

// 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);

DESCANSO

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{
   "message":{
      "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
      "notification":{
        "body":"This is an FCM notification message!",
        "title":"FCM Message"
      }
   }
}

Comando cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
   "notification":{
     "title":"FCM Message",
     "body":"This is an FCM Message"
   },
   "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

Em caso de sucesso, cada método de envio retorna um ID de mensagem. O SDK Admin do Firebase retorna a string de ID no formato projects/{project_id}/messages/{message_id} . A resposta do protocolo HTTP é uma única chave JSON:

    {
      "name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
    }

Envie mensagens para vários dispositivos

A API REST e as APIs Admin FCM permitem que você multicast uma mensagem para uma lista de tokens de registro de dispositivo. Você pode 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");

Pitão

# Create a list containing up to 500 registration tokens.
# These registration tokens come from the client FCM SDKs.
registration_tokens = [
    'YOUR_REGISTRATION_TOKEN_1',
    # ...
    'YOUR_REGISTRATION_TOKEN_N',
]

message = messaging.MulticastMessage(
    data={'score': '850', 'time': '2:45'},
    tokens=registration_tokens,
)
response = messaging.send_multicast(message)
# See the BatchResponse reference documentation
# for the contents of response.
print('{0} messages were sent successfully'.format(response.success_count))

Vai

// 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");

DESCANSO

Construa uma solicitação em lote HTTP:

--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() nos bastidores, conforme mostrado nos exemplos. O valor de retorno é um BatchResponse cuja lista de respostas corresponde à ordem dos tokens de entrada. Isso é útil quando você deseja verificar quais tokens resultaram em erros.

Node.js

// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
  'YOUR_REGISTRATION_TOKEN_1',
  // …
  'YOUR_REGISTRATION_TOKEN_N',
];

const message = {
  data: {score: '850', time: '2:45'},
  tokens: registrationTokens,
};

getMessaging().sendMulticast(message)
  .then((response) => {
    if (response.failureCount > 0) {
      const failedTokens = [];
      response.responses.forEach((resp, idx) => {
        if (!resp.success) {
          failedTokens.push(registrationTokens[idx]);
        }
      });
      console.log('List of tokens that caused failures: ' + failedTokens);
    }
  });

Java

// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n"
);

MulticastMessage message = MulticastMessage.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .addAllTokens(registrationTokens)
    .build();
BatchResponse response = FirebaseMessaging.getInstance().sendMulticast(message);
if (response.getFailureCount() > 0) {
  List<SendResponse> responses = response.getResponses();
  List<String> failedTokens = new ArrayList<>();
  for (int i = 0; i < responses.size(); i++) {
    if (!responses.get(i).isSuccessful()) {
      // The order of responses corresponds to the order of the registration tokens.
      failedTokens.add(registrationTokens.get(i));
    }
  }

  System.out.println("List of tokens that caused failures: " + failedTokens);
}

Pitão

# These registration tokens come from the client FCM SDKs.
registration_tokens = [
    'YOUR_REGISTRATION_TOKEN_1',
    # ...
    'YOUR_REGISTRATION_TOKEN_N',
]

message = messaging.MulticastMessage(
    data={'score': '850', 'time': '2:45'},
    tokens=registration_tokens,
)
response = messaging.send_multicast(message)
if response.failure_count > 0:
    responses = response.responses
    failed_tokens = []
    for idx, resp in enumerate(responses):
        if not resp.success:
            # The order of responses corresponds to the order of the registration tokens.
            failed_tokens.append(registration_tokens[idx])
    print('List of tokens that caused failures: {0}'.format(failed_tokens))

Vai

// 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}");
}

DESCANSO

Cada sub-envio 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 para tópicos

Depois de criar um tópico, assinando instâncias do aplicativo cliente no tópico no lado do cliente ou por meio da API do servidor , você pode enviar mensagens para o tópico. Se esta for a primeira vez que você cria solicitações de envio para o FCM, consulte o guia do ambiente do servidor e do FCM para obter informações importantes de configuração e antecedentes.

Em sua lógica de envio no back-end, especifique o nome do tópico desejado conforme mostrado:

Node.js

// The topic name can be optionally prefixed with "/topics/".
const topic = 'highScores';

const message = {
  data: {
    score: '850',
    time: '2:45'
  },
  topic: topic
};

// Send a message to devices subscribed to the provided topic.
getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

// The topic name can be optionally prefixed with "/topics/".
String topic = "highScores";

// See documentation on defining a message payload.
Message message = Message.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .setTopic(topic)
    .build();

// Send a message to the devices subscribed to the provided topic.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);

Pitão

# The topic name can be optionally prefixed with "/topics/".
topic = 'highScores'

# See documentation on defining a message payload.
message = messaging.Message(
    data={
        'score': '850',
        'time': '2:45',
    },
    topic=topic,
)

# Send a message to the devices subscribed to the provided topic.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)

Vai

// 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);

DESCANSO

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 enviará mensagens para dispositivos que estão inscritos no TopicA e TopicB ou TopicC :

"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"

O FCM primeiro avalia quaisquer condições entre parênteses e, em seguida, avalia a expressão da esquerda para a direita. Na expressão acima, um usuário inscrito em um único tópico não recebe a mensagem. Da mesma forma, um usuário que não assina o TopicA não recebe a mensagem. Essas combinações o recebem:

  • TopicA e TopicB
  • TopicA e TopicC

Você pode incluir até cinco tópicos em sua expressão condicional.

Para enviar para uma condição:

Node.js

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
const condition = '\'stock-GOOG\' in topics || \'industry-tech\' in topics';

// See documentation on defining a message payload.
const message = {
  notification: {
    title: '$FooCorp up 1.43% on the day',
    body: '$FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
  },
  condition: condition
};

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
String condition = "'stock-GOOG' in topics || 'industry-tech' in topics";

// See documentation on defining a message payload.
Message message = Message.builder()
    .setNotification(Notification.builder()
        .setTitle("$GOOG up 1.43% on the day")
        .setBody("$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.")
        .build())
    .setCondition(condition)
    .build();

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);

Pitão

# Define a condition which will send to devices which are subscribed
# to either the Google stock or the tech industry topics.
condition = "'stock-GOOG' in topics || 'industry-tech' in topics"

# See documentation on defining a message payload.
message = messaging.Message(
    notification=messaging.Notification(
        title='$GOOG up 1.43% on the day',
        body='$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
    ),
    condition=condition,
)

# Send a message to devices subscribed to the combination of topics
# specified by the provided condition.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)

Vai

// 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);

DESCANSO

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
   "message":{
    "condition": "'dogs' in topics || 'cats' in topics",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message",
    }
  }
}

Comando cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "notification": {
    "title": "FCM Message",
    "body": "This is a Firebase Cloud Messaging Topic Message!",
  },
  "condition": "'dogs' in topics || 'cats' in topics"
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Envie um lote de mensagens

A API REST e os SDKs Admin oferecem suporte ao envio de mensagens em lotes. Você pode agrupar até 500 mensagens em um único lote e enviá-las todas em uma única chamada de API, com melhoria significativa de desempenho em relação ao envio de solicitações HTTP separadas para cada mensagem.

Esse recurso pode ser usado para criar um conjunto personalizado de mensagens e enviá-las a diferentes destinatários, incluindo tópicos ou tokens de registro de dispositivos específicos. Use esse recurso quando, por exemplo, você precisar enviar mensagens simultaneamente para diferentes públicos com detalhes ligeiramente diferentes no corpo da mensagem.

Node.js

// Create a list containing up to 500 messages.
const messages = [];
messages.push({
  notification: { title: 'Price drop', body: '5% off all electronics' },
  token: registrationToken,
});
messages.push({
  notification: { title: 'Price drop', body: '2% off all books' },
  topic: 'readers-club',
});

getMessaging().sendAll(messages)
  .then((response) => {
    console.log(response.successCount + ' messages were sent successfully');
  });

Java

// Create a list containing up to 500 messages.
List<Message> messages = Arrays.asList(
    Message.builder()
        .setNotification(Notification.builder()
            .setTitle("Price drop")
            .setBody("5% off all electronics")
            .build())
        .setToken(registrationToken)
        .build(),
    // ...
    Message.builder()
        .setNotification(Notification.builder()
            .setTitle("Price drop")
            .setBody("2% off all books")
            .build())
        .setTopic("readers-club")
        .build()
);

BatchResponse response = FirebaseMessaging.getInstance().sendAll(messages);
// See the BatchResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " messages were sent successfully");

Pitão

# Create a list containing up to 500 messages.
messages = [
    messaging.Message(
        notification=messaging.Notification('Price drop', '5% off all electronics'),
        token=registration_token,
    ),
    # ...
    messaging.Message(
        notification=messaging.Notification('Price drop', '2% off all books'),
        topic='readers-club',
    ),
]

response = messaging.send_all(messages)
# See the BatchResponse reference documentation
# for the contents of response.
print('{0} messages were sent successfully'.format(response.success_count))

Vai

// 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");

DESCANSO

Construa uma solicitação em lote HTTP combinando uma lista de subsolicitações:

--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
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

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--

Você pode consultar o BatchResponse retornado para verificar quantas das mensagens foram entregues ao FCM com sucesso. 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 habilitadas para inicialização direta (somente Android)

Você pode enviar mensagens para dispositivos no modo de inicialização direta usando HTTP v1 ou APIs HTTP herdadas. Antes de enviar para dispositivos no modo de inicialização direta, certifique-se de ter concluído as etapas para permitir que os dispositivos cliente recebam mensagens do FCM no modo de inicialização direta .

Enviar usando a API HTTP do FCM v1

A solicitação de mensagem deve incluir a chave "direct_boot_ok" : true nas opções AndroidConfig do corpo da solicitação. Por exemplo:

https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send
Content-Type:application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{
  "message":{
    "token" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
    "data": {
      "score": "5x1",
      "time": "15:10"
    },
    "android": {
      "direct_boot_ok": true,
    },
}

Enviar usando a API HTTP legada do FCM

A solicitação de mensagem deve incluir a chave "direct_boot_ok" : true no nível superior do corpo da solicitação. Por exemplo:

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{ "data": {
    "score": "5x1",
    "time": "15:10"
  },
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  "direct_boot_ok" : true
}

As mensagens enviadas com essa chave no corpo da solicitação podem ser tratadas por aplicativos em dispositivos atualmente no modo de inicialização direta (e também quando não estiverem nesse modo).

Personalize mensagens entre plataformas

O SDK Admin do Firebase e o protocolo HTTP do FCM v1 permitem que suas solicitações de mensagem definam todos os campos disponíveis no objeto de message . Isso inclui:

  • um conjunto comum de campos a serem interpretados por todas as instâncias do aplicativo que recebem a mensagem.
  • conjuntos de campos específicos da plataforma, como AndroidConfig e WebpushConfig , interpretados apenas por instâncias do aplicativo em execução na plataforma especificada.

Os blocos específicos da plataforma oferecem flexibilidade para personalizar mensagens para diferentes plataformas para garantir que sejam tratadas corretamente quando recebidas. O back-end do FCM levará em consideração todos os parâmetros especificados e personalizará a mensagem para cada plataforma.

Quando usar campos comuns

Use campos comuns quando estiver:

  • Segmentação de instâncias de aplicativos em todas as plataformas — Apple, Android e Web
  • Enviando mensagens para tópicos

Todas as instâncias do aplicativo, independentemente da plataforma, podem interpretar os seguintes campos comuns:

Quando usar campos específicos da plataforma

Use campos específicos da plataforma quando quiser:

  • Envie campos apenas para plataformas específicas
  • Envie campos específicos da plataforma além dos campos comuns

Sempre que você quiser enviar valores apenas para plataformas específicas, não use campos comuns; use campos específicos da plataforma. Por exemplo, para enviar uma notificação apenas para plataformas Apple e web, mas não para Android, você deve usar dois conjuntos separados de campos, um para Apple e outro para web.

Ao enviar mensagens com opções de entrega específicas , use campos específicos da plataforma para defini-las. Você pode especificar valores diferentes por plataforma, se desejar. No entanto, mesmo quando você deseja definir essencialmente o mesmo valor entre plataformas, você deve usar campos específicos da plataforma. Isso ocorre porque cada plataforma pode interpretar o valor de forma ligeiramente diferente – por exemplo, o tempo de vida é definido no Android como um tempo de expiração em segundos, enquanto na Apple é definido como uma data de expiração .

Exemplo: mensagem de notificação com opções de cores e ícones

Este exemplo de solicitação de envio envia um título e conteúdo de notificação comum para todas as plataformas, mas também envia algumas substituições específicas da plataforma para dispositivos Android.

Para Android, a solicitação define um ícone e uma cor especiais para exibição em dispositivos Android. Conforme observado na referência para AndroidNotification , a cor é especificada no formato #rrggbb e a imagem deve ser um recurso de ícone desenhável local para o aplicativo Android.

Aqui está uma aproximação do efeito visual no dispositivo de um usuário:

Desenho simples de dois dispositivos, com um exibindo um ícone e uma cor personalizados

Node.js

const topicName = 'industry-tech';

const message = {
  notification: {
    title: '`$FooCorp` up 1.43% on the day',
    body: 'FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
  },
  android: {
    notification: {
      icon: 'stock_ticker_update',
      color: '#7e55c3'
    }
  },
  topic: topicName,
};

getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

Message message = Message.builder()
    .setNotification(Notification.builder()
        .setTitle("$GOOG up 1.43% on the day")
        .setBody("$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.")
        .build())
    .setAndroidConfig(AndroidConfig.builder()
        .setTtl(3600 * 1000)
        .setNotification(AndroidNotification.builder()
            .setIcon("stock_ticker_update")
            .setColor("#f45342")
            .build())
        .build())
    .setApnsConfig(ApnsConfig.builder()
        .setAps(Aps.builder()
            .setBadge(42)
            .build())
        .build())
    .setTopic("industry-tech")
    .build();

Pitão

message = messaging.Message(
    notification=messaging.Notification(
        title='$GOOG up 1.43% on the day',
        body='$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
    ),
    android=messaging.AndroidConfig(
        ttl=datetime.timedelta(seconds=3600),
        priority='normal',
        notification=messaging.AndroidNotification(
            icon='stock_ticker_update',
            color='#f45342'
        ),
    ),
    apns=messaging.APNSConfig(
        payload=messaging.APNSPayload(
            aps=messaging.Aps(badge=42),
        ),
    ),
    topic='industry-tech',
)

Vai

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",
};

DESCANSO

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
     "topic":"industry-tech",
     "notification":{
       "title":"`$FooCorp` up 1.43% on the day",
       "body":"FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day."
     },
     "android":{
       "notification":{
         "icon":"stock_ticker_update",
         "color":"#7e55c3"
       }
     }
   }
 }

Consulte a documentação de referência do HTTP v1 para obter detalhes completos sobre as chaves disponíveis em blocos específicos da plataforma no corpo da mensagem.

Exemplo: mensagem de notificação com imagem personalizada

O exemplo de solicitação de envio a seguir envia um título de notificação comum a todas as plataformas, mas também envia uma imagem. Aqui está uma aproximação do efeito visual no dispositivo de um usuário:

Desenho simples de uma imagem em uma notificação de exibição

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);
  });

DESCANSO

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
     "topic":"industry-tech",
     "notification":{
       "title":"Sparky says hello!",
     },
     "android":{
       "notification":{
         "image":"https://foo.bar/pizza-monster.png"
       }
     },
     "apns":{
       "payload":{
         "aps":{
           "mutable-content":1
         }
       },
       "fcm_options": {
           "image":"https://foo.bar/pizza-monster.png"
       }
     },
     "webpush":{
       "headers":{
         "image":"https://foo.bar/pizza-monster.png"
       }
     }
   }
 }

Consulte a documentação de referência do HTTP v1 para obter detalhes completos sobre as chaves disponíveis em blocos específicos da plataforma no corpo da mensagem.

Exemplo: mensagem de notificação com uma ação de clique associada

O exemplo de solicitação de envio a seguir envia um título de notificação comum a todas as plataformas, mas também envia uma ação para o aplicativo executar em resposta à interação do usuário com a notificação. Aqui está uma aproximação do efeito visual no dispositivo de um usuário:

Desenho simples de um toque de usuário abrindo uma página da web

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);
  });

DESCANSO

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
     "topic":"industry-tech",
     "notification":{
       "title":"Breaking News...",
     },
     "android":{
       "notification":{
         "click_action":"news_intent"
       }
     },
     "apns":{
       "payload":{
         "aps":{
           "category" : "INVITE_CATEGORY"
         }
       },
     },
     "webpush":{
       "fcm_options":{
         "link":"breakingnews.html"
       }
     }
   }
 }

Consulte a documentação de referência do HTTP v1 para obter detalhes completos sobre as chaves disponíveis em blocos específicos da plataforma no corpo da mensagem.

Exemplo: mensagem de notificação com opções de localização

O exemplo de solicitação de envio a seguir envia opções de localização para o cliente exibir mensagens localizadas. Aqui está uma aproximação do efeito visual no dispositivo de um usuário:

Desenho simples de dois dispositivos exibindo texto em inglês e espanhol

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);
  });

DESCANSO

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
             "topic":"Tech",
             "android":{
               "ttl":"3600s",
               "notification":{
                 "body_loc_key": "STOCK_NOTIFICATION_BODY",
                 "body_loc_args":  ["FooCorp", "11.80", "835.67", "1.43"],
               },
             },
             "apns":{
               "payload":{
                 "aps":{
                   "alert" : {
                     "loc-key": "STOCK_NOTIFICATION_BODY",
                     "loc-args":  ["FooCorp", "11.80", "835.67", "1.43"],
                    },
                 },
               },
             },
  },
}'

Consulte a documentação de referência do HTTP v1 para obter detalhes completos sobre as chaves disponíveis em blocos específicos da plataforma no corpo da mensagem.

Códigos de erro do administrador

A tabela a seguir lista os códigos de erro da API Firebase Admin FCM e suas descrições, incluindo as etapas de resolução recomendadas.

Erro de código Etapas de descrição e resolução
messaging/invalid-argument Um argumento inválido foi fornecido para um método 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 carga útil de mensagem inválido foi fornecido. A mensagem de erro deve conter informações adicionais.
messaging/invalid-data-payload-key A carga da mensagem de dados contém uma chave inválida. Consulte a documentação de referência para DataMessagePayload para chaves restritas.
messaging/payload-size-limit-exceeded A carga útil da mensagem fornecida excede os limites de tamanho do FCM. O limite é de 4096 bytes para a maioria das mensagens. Para mensagens enviadas para tópicos, o limite é de 2.048 bytes. O tamanho total da carga útil inclui chaves e valores.
messaging/invalid-options Um objeto de opções de mensagem inválido foi fornecido. A mensagem de erro deve conter informações adicionais.
messaging/invalid-registration-token Token de registro inválido fornecido. Verifique se ele corresponde ao token de registro que o aplicativo cliente recebe ao se registrar no FCM. Não trunque ou adicione caracteres adicionais a ele.
messaging/registration-token-not-registered O token de registro fornecido não está registrado. Um token de registro anteriormente válido pode ter o registro cancelado por vários motivos, incluindo:
  • O aplicativo cliente cancelou o registro do FCM.
  • O aplicativo cliente teve o registro cancelado automaticamente. Isso pode acontecer se o usuário desinstalar o aplicativo ou, em plataformas Apple, se o Serviço de Feedback de APNs reportar o token de APNs como inválido.
  • O token de registro expirou. Por exemplo, o Google pode decidir atualizar os tokens de registro ou o token APNs pode ter expirado para dispositivos Apple.
  • O aplicativo cliente foi atualizado, mas a nova versão não está configurada para receber mensagens.
Para todos esses casos, remova esse token de registro e pare de usá-lo para enviar mensagens.
messaging/invalid-package-name A mensagem foi endereçada a um token de registro cujo nome do pacote não corresponde à opção restrictedPackageName fornecida.
messaging/message-rate-exceeded A taxa de mensagens para um destino específico é muito alta. Reduza o número de mensagens enviadas para este dispositivo ou tópico e não tente enviar novamente para este destino imediatamente.
messaging/device-message-rate-exceeded A taxa de mensagens para um determinado dispositivo é muito alta. Reduza o número de mensagens enviadas para este dispositivo e não tente enviar novamente para este dispositivo imediatamente.
messaging/topics-message-rate-exceeded A taxa de mensagens para assinantes de um tópico específico é muito alta. Reduza o número de mensagens enviadas para este tópico e não tente enviar novamente para este tópico imediatamente.
messaging/too-many-topics Um token de registro foi inscrito no número máximo de tópicos e não pode mais ser inscrito.
messaging/invalid-apns-credentials Uma mensagem direcionada a um dispositivo Apple não pôde ser enviada porque o certificado SSL APNs necessário não foi carregado ou expirou. Verifique a validade dos seus certificados de desenvolvimento e produção.
messaging/mismatched-credential A credencial usada para autenticar este SDK não tem permissão para enviar mensagens ao dispositivo correspondente ao token de registro fornecido. Verifique se a credencial e o token de registro pertencem ao mesmo projeto do Firebase. Consulte Adicionar o Firebase ao seu aplicativo para obter a documentação sobre como autenticar os SDKs Admin do Firebase.
messaging/authentication-error O SDK não pôde autenticar nos servidores FCM. Certifique-se de autenticar o SDK Admin do Firebase com uma credencial que tenha as permissões adequadas para enviar mensagens do FCM. Consulte Adicionar o Firebase ao seu aplicativo para obter a documentação sobre como autenticar os SDKs Admin do Firebase.
messaging/server-unavailable O servidor FCM não pôde processar a solicitação a tempo. Você deve tentar novamente a mesma solicitação, mas deve:
  • Honre o cabeçalho Retry-After se ele estiver incluído na resposta do FCM Connection Server.
  • Implemente a retirada exponencial em seu mecanismo de repetição. Por exemplo, se você esperou um segundo antes da primeira tentativa, espere pelo menos dois segundos antes da próxima, depois quatro segundos e assim por diante. Se você estiver enviando várias mensagens, atrase cada uma de forma independente por um valor aleatório adicional para evitar a emissão de uma nova solicitação para todas as mensagens ao mesmo tempo.
Os remetentes que causam problemas correm o risco de serem colocados na lista negra.
messaging/internal-error O servidor FCM encontrou um erro ao tentar processar a solicitação. Você pode tentar novamente a mesma solicitação seguindo os requisitos listados na linha de messaging/server-unavailable acima. Se o erro persistir, informe o problema ao nosso canal de suporte Bug Report .
messaging/unknown-error Um erro de servidor desconhecido foi retornado. Consulte a resposta do servidor bruto na mensagem de erro para obter mais detalhes. Se você receber este erro, por favor, reporte a mensagem de erro completa ao nosso canal de suporte Bug Report .

Envie mensagens usando os protocolos do servidor de aplicativos legado

Se você preferir usar os protocolos legados, crie solicitações de mensagens conforme mostrado nesta seção. Lembre-se de que, se você estiver enviando para várias plataformas via HTTP, o protocolo v1 pode simplificar suas solicitações de mensagens.

Envie mensagens para dispositivos específicos

Para enviar mensagens para dispositivos específicos, defina to chave para o token de registro para a instância de aplicativo específica. Consulte as informações de configuração do cliente para sua plataforma para saber mais sobre tokens de registro.

Solicitação HTTP POST

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{ "data": {
    "score": "5x1",
    "time": "15:10"
  },
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}

Resposta HTTP

{ "multicast_id": 108,
  "success": 1,
  "failure": 0,
  "results": [
    { "message_id": "1:08" }
  ]
}

mensagem XMPP

<message id="">
  <gcm xmlns="google:mobile:data">
    { "data": {
      "score": "5x1",
      "time": "15:10"
    },
    "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  }
  </gcm>
</message>

Resposta XMPP

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "from":"REGID",
      "message_id":"m-1366082849205"
      "message_type":"ack"
  }
  </gcm>
</message>

O servidor de conexão XMPP fornece algumas outras opções para respostas. Consulte Formato de resposta do servidor .

Para obter a lista completa de opções de mensagens disponíveis ao enviar mensagens downstream para aplicativos cliente, consulte as informações de referência do protocolo de servidor de conexão escolhido, HTTP ou XMPP .

Enviar mensagens para tópicos

O envio de mensagens para um tópico do Firebase Cloud Messaging é muito semelhante ao envio de mensagens para um dispositivo individual ou para um grupo de usuários. O servidor de aplicativos define a chave to com um valor como /topics/yourTopic . Os desenvolvedores podem escolher qualquer nome de tópico que corresponda à expressão regular: "/topics/[a-zA-Z0-9-_.~%]+" .

Para enviar para combinações de vários tópicos, o servidor de aplicativos deve definir a chave de condition (em vez da chave to ) como uma condição booleana que especifica os tópicos de destino. Por exemplo, para enviar mensagens para dispositivos que assinaram TopicA e TopicB ou TopicC :

'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)

O FCM primeiro avalia quaisquer condições entre parênteses e, em seguida, avalia a expressão da esquerda para a direita. Na expressão acima, um usuário inscrito em um único tópico não recebe a mensagem. Da mesma forma, um usuário que não assina o TopicA não recebe a mensagem. Essas combinações o recebem:

  • Tópico A e Tópico B
  • Tópico A e Tópico C

Você pode incluir até cinco tópicos em sua expressão condicional e parênteses são suportados. Operadores suportados: && , || .

Solicitação HTTP POST do 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 "cachorros" ou "gatos":

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA


Resposta HTTP do tópico

//Success example:
{
  "message_id": "1023456"
}

//failure example:
{
  "error": "TopicsMessageRateExceeded"
}

Mensagem do tópico XMPP

Enviar para um único tópico:

<message id="">
  <gcm xmlns="google:mobile:data">


  </gcm>
</message>

Enviar para dispositivos inscritos nos tópicos "cachorros" ou "gatos":

<message id="">
  <gcm xmlns="google:mobile:data">


  </gcm>
</message>

Resposta do tópico XMPP

//Success example:
{
  "message_id": "1023456"
}

//failure example:
{
  "error": "TopicsMessageRateExceeded"
}

Espere até 30 segundos de atraso antes que o FCM Server retorne uma resposta de sucesso ou falha às solicitações de envio de tópico. Certifique-se de definir o valor de tempo limite do servidor de aplicativos na solicitação de acordo.

Enviar mensagens para grupos de dispositivos

O envio de mensagens para um grupo de dispositivos é muito semelhante ao envio de mensagens para um dispositivo individual. Defina o parâmetro to para a chave de notificação exclusiva para o grupo de dispositivos. Consulte Tipos de mensagem para obter detalhes sobre o suporte a carga útil. Os exemplos nesta página mostram como enviar mensagens de dados para grupos de dispositivos nos protocolos HTTP e XMPP legados.

Solicitação HTTP POST do grupo de dispositivos

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{
  "to": "aUniqueKey",
  "data": {
    "hello": "This is a Firebase Cloud Messaging Device Group Message!",
   }
}

Resposta HTTP do grupo de dispositivos

Aqui está um exemplo de "sucesso" — a notification_key tem 2 tokens de registro associados a ela, e a mensagem foi enviada com sucesso para ambos:

{
  "success": 2,
  "failure": 0
}

Aqui está um exemplo de "sucesso parcial" — a notification_key tem 3 tokens de registro associados a ela. A mensagem foi enviada com sucesso apenas para 1 dos tokens de registro. A mensagem de resposta lista os tokens de registro ( registration_ids ) que não receberam a mensagem:

{
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

Quando uma mensagem não é entregue a um ou mais tokens de registro associados a um notification_key , o servidor de aplicativos deve tentar novamente com espera entre as tentativas.

Se o servidor tentar enviar uma mensagem para um grupo de dispositivos que não tenha membros, a resposta será semelhante à seguinte, com 0 sucesso e 0 falha:

{
  "success": 0,
  "failure": 0
}

Mensagem XMPP do grupo de dispositivos

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to": "aUniqueKey",
      "message_id": "m-1366082849205" ,
      "data": {
          "hello":"This is a Firebase Cloud Messaging Device Group Message!"
      }
  }
  </gcm>
</message>

Resposta XMPP do grupo de dispositivos

Quando a mensagem é enviada para qualquer um dos dispositivos do grupo com sucesso, o servidor de conexão XMPP responde com um ACK. Se todas as mensagens enviadas para todos os dispositivos do grupo falharem, o servidor de conexão XMPP responderá com um NACK.

Aqui está um exemplo de "sucesso" — o notification_key tem 3 tokens de registro associados a ele, e a mensagem foi enviada com sucesso para todos eles:

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success": 3,
  "failure": 0,
  "message_id": "m-1366082849205"
}

Aqui está um exemplo de "sucesso parcial" — a notification_key tem 3 tokens de registro associados a ela. A mensagem foi enviada com sucesso apenas para 1 dos tokens de registro. A mensagem de resposta lista os tokens de registro que não receberam a mensagem:

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

Quando o servidor de conexão FCM não entrega a todos os dispositivos do grupo. O servidor de aplicativos receberá uma resposta nack.

Para obter a lista completa de opções de mensagens, consulte as informações de referência do protocolo de servidor de conexão escolhido, HTTP ou XMPP .

Métodos de envio legados do SDK Admin do Firebase

O SDK do Firebase Admin Node.js é compatível com métodos de envio de mensagens (FCM) com base na API do servidor FCM herdado . Esses métodos aceitam argumentos diferentes em comparação com o método send() . Você deve usar o método send() sempre que possível e usar apenas os métodos descritos nesta página ao enviar mensagens para dispositivos individuais ou grupos de dispositivos.

Enviar para dispositivos individuais

Você pode passar um token de registro para o método sendToDevice() para enviar uma mensagem para esse dispositivo:

Node.js

// This registration token comes from the client FCM SDKs.
const registrationToken = 'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...';

// See the "Defining the message payload" section below for details
// on how to define a message payload.
const payload = {
  data: {
    score: '850',
    time: '2:45'
  }
};

// Send a message to the device corresponding to the provided
// registration token.
getMessaging().sendToDevice(registrationToken, payload)
  .then((response) => {
    // See the MessagingDevicesResponse reference documentation for
    // the contents of response.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

O método sendToDevice() também pode enviar uma mensagem multicast (ou seja, uma mensagem para vários dispositivos) passando uma matriz de tokens de registro em vez de apenas um único token de registro:

Node.js

// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
  'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...',
  // ...
  'ecupwIfBy1w:APA91bFtuMY7MktgxA3Au_Qx7cKqnf...'
];

// See the "Defining the message payload" section below for details
// on how to define a message payload.
const payload = {
  data: {
    score: '850',
    time: '2:45'
  }
};

// Send a message to the devices corresponding to the provided
// registration tokens.
getMessaging().sendToDevice(registrationTokens, payload)
  .then((response) => {
    // See the MessagingDevicesResponse reference documentation for
    // the contents of response.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

O método sendToDevice() retorna uma promessa que é resolvida com um objeto MessagingDevicesResponse contendo a resposta do FCM. O tipo de retorno tem o mesmo formato ao passar um único token de registro ou uma matriz de tokens de registro.

Alguns casos, como um erro de autenticação ou limitação de taxa, fazem com que toda a mensagem não seja processada. Nesses casos, a promessa retornada por sendToDevice() é rejeitada com um erro. Para obter uma lista completa de códigos de erro, incluindo descrições e etapas de resolução, consulte Admin FCM API Errors .

Enviar para um grupo de dispositivos

As mensagens de grupo de dispositivos permitem adicionar vários dispositivos a um único grupo. Isso é semelhante à mensagem de tópico, mas inclui autenticação para garantir que a associação ao grupo seja gerenciada apenas por seus servidores. Por exemplo, se você deseja enviar mensagens diferentes para modelos de telefone diferentes, seus servidores podem adicionar/remover registros para os grupos apropriados e enviar a mensagem apropriada para cada grupo. As mensagens de grupo de dispositivos diferem das mensagens de tópico porque envolvem o gerenciamento de grupos de dispositivos de seus servidores em vez de diretamente em seu aplicativo.

Você pode usar as mensagens do grupo de dispositivos por meio dos protocolos XMPP ou HTTP herdados em seu servidor de aplicativos. As versões mais antigas do SDK Admin do Firebase para Node.js são baseadas nos protocolos legados e também oferecem recursos de mensagens de grupo de dispositivos. O número máximo de membros permitido para uma chave de notificação é 20.

Você pode criar grupos de dispositivos e gerar chaves de notificação por meio de um servidor de aplicativos ou de um cliente Android. Consulte Gerenciando grupos de dispositivos para obter detalhes.

O método sendToDeviceGroup() permite enviar uma mensagem para um grupo de dispositivos especificando a chave de notificação para esse grupo de dispositivos:

Node.js

// See the "Managing device groups" link above on how to generate a
// notification key.
const notificationKey = 'some-notification-key';

// See the "Defining the message payload" section below for details
// on how to define a message payload.
const payload = {
  data: {
    score: '850',
    time: '2:45'
  }
};

// Send a message to the device group corresponding to the provided
// notification key.
getMessaging().sendToDeviceGroup(notificationKey, payload)
  .then((response) => {
    // See the MessagingDeviceGroupResponse reference documentation for
    // the contents of response.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

O método sendToDeviceGroup() retorna uma promessa que é resolvida com um objeto MessagingDevicesResponse contendo a resposta do FCM.

Alguns casos, como um erro de autenticação ou limitação de taxa, fazem com que toda a mensagem não seja processada. Nesses casos, a promessa retornada por sendToDeviceGroup() é rejeitada com um erro. Para obter uma lista completa de códigos de erro, incluindo descrições e etapas de resolução, consulte Admin FCM API Errors .

Definindo a carga útil da mensagem

Os métodos acima baseados nos protocolos legados do FCM aceitam uma carga útil de mensagem como seu segundo argumento e suportam mensagens de notificação e de dados . Você pode especificar um ou ambos os tipos de mensagem criando um objeto com os data e/ou chaves de notification . Por exemplo, veja como definir diferentes tipos de carga útil de mensagem:

Mensagem de notificação

const payload = {
  notification: {
    title: '$FooCorp up 1.43% on the day',
    body: '$FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
  }
};

Mensagem de dados

const payload = {
  data: {
    score: '850',
    time: '2:45'
  }
};

Mensagem combinada

const payload = {
  notification: {
    title: '$FooCorp up 1.43% on the day',
    body: '$FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
  },
  data: {
    stock: 'GOOG',
    open: '829.62',
    close: '635.67'
  }
};

As cargas úteis da mensagem de notificação têm um subconjunto predefinido de propriedades válidas e diferem um pouco dependendo do sistema operacional móvel que você está direcionando. Consulte os documentos de referência para NotificationMessagePayload para obter uma lista completa.

As cargas úteis de mensagens de dados são compostas de pares de valores-chave personalizados com algumas restrições, incluindo o fato de que todos os valores devem ser strings. Consulte os documentos de referência para DataMessagePayload para obter uma lista completa de restrições.

Definindo as opções de mensagem

Os métodos acima baseados nos protocolos legados do FCM aceitam um terceiro argumento opcional especificando algumas opções para a mensagem. Por exemplo, o exemplo a seguir envia uma mensagem de alta prioridade para um dispositivo que expira após 24 horas:

Node.js

// This registration token comes from the client FCM SDKs.
const registrationToken = 'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...';

// See the "Defining the message payload" section above for details
// on how to define a message payload.
const payload = {
  notification: {
    title: 'Urgent action needed!',
    body: 'Urgent action is needed to prevent your account from being disabled!'
  }
};

// Set the message as high priority and have it expire after 24 hours.
const options = {
  priority: 'high',
  timeToLive: 60 * 60 * 24
};

// Send a message to the device corresponding to the provided
// registration token with the provided options.
getMessaging().sendToDevice(registrationToken, payload, options)
  .then((response) => {
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Consulte os documentos de referência de MessagingOptions para obter uma lista completa das opções disponíveis.