Utilizzando i protocolli Firebase Admin SDK o FCM del server app, puoi creare richieste di messaggi e inviarle a questi tipi di destinazioni:
- Nome dell'argomento
- Condizione
- Token di registrazione del dispositivo
- Nome del gruppo di dispositivi (solo protocollo)
Puoi inviare messaggi con un payload di notifica composto da campi predefiniti, un payload di dati composto da campi definiti dall'utente o un messaggio contenente entrambi i tipi di payload. Per ulteriori informazioni, vedere Tipi di messaggio .
Gli esempi in questa pagina mostrano come inviare messaggi di notifica utilizzando Firebase Admin SDK (che supporta Node , Java , Python , C# e Go ) e il protocollo HTTP v1 . Sono inoltre disponibili indicazioni per l'invio di messaggi tramite i protocolli legacy HTTP e XMPP deprecati.
Invia messaggi a dispositivi specifici
Per inviare a un singolo dispositivo specifico, passare il token di registrazione del dispositivo come mostrato. Consulta le informazioni sulla configurazione del client per la tua piattaforma per ulteriori informazioni sui token di registrazione.
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);
});
Giava
// 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);
Pitone
# 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)
Andare
// 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);
RIPOSO
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
In caso di successo, ciascun metodo di invio restituisce un ID messaggio. Firebase Admin SDK restituisce la stringa ID nel formato projects/{project_id}/messages/{message_id}
. La risposta del protocollo HTTP è una singola chiave JSON:
{
"name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
}
Invia messaggi a più dispositivi
Le API Admin FCM ti consentono di trasmettere in multicast un messaggio a un elenco di token di registrazione del dispositivo. È possibile specificare fino a 500 token di registrazione del dispositivo per invocazione.
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');
});
Giava
// 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");
Pitone
# 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))
Andare
// Create a list containing up to 500 registration tokens.
// This registration tokens come from the client FCM SDKs.
registrationTokens := []string{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
}
message := &messaging.MulticastMessage{
Data: map[string]string{
"score": "850",
"time": "2:45",
},
Tokens: registrationTokens,
}
br, err := client.SendMulticast(context.Background(), message)
if err != nil {
log.Fatalln(err)
}
// See the BatchResponse reference documentation
// for the contents of response.
fmt.Printf("%d messages were sent successfully\n", br.SuccessCount)
C#
// Create a list containing up to 500 registration tokens.
// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
};
var message = new MulticastMessage()
{
Tokens = registrationTokens,
Data = new Dictionary<string, string>()
{
{ "score", "850" },
{ "time", "2:45" },
},
};
var response = await FirebaseMessaging.DefaultInstance.SendEachForMulticastAsync(message);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");
Il valore restituito è un elenco di token che corrisponde all'ordine dei token di input. Ciò è utile quando si desidera verificare quali token hanno generato errori.
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);
}
});
Giava
// 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);
}
Pitone
# 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))
Andare
// Create a list containing up to 500 registration tokens.
// This registration tokens come from the client FCM SDKs.
registrationTokens := []string{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
}
message := &messaging.MulticastMessage{
Data: map[string]string{
"score": "850",
"time": "2:45",
},
Tokens: registrationTokens,
}
br, err := client.SendMulticast(context.Background(), message)
if err != nil {
log.Fatalln(err)
}
if br.FailureCount > 0 {
var failedTokens []string
for idx, resp := range br.Responses {
if !resp.Success {
// The order of responses corresponds to the order of the registration tokens.
failedTokens = append(failedTokens, registrationTokens[idx])
}
}
fmt.Printf("List of tokens that caused failures: %v\n", failedTokens)
}
C#
// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
};
var message = new MulticastMessage()
{
Tokens = registrationTokens,
Data = new Dictionary<string, string>()
{
{ "score", "850" },
{ "time", "2:45" },
},
};
var response = await FirebaseMessaging.DefaultInstance.SendEachForMulticastAsync(message);
if (response.FailureCount > 0)
{
var failedTokens = new List<string>();
for (var i = 0; i < response.Responses.Count; i++)
{
if (!response.Responses[i].IsSuccess)
{
// The order of responses corresponds to the order of the registration tokens.
failedTokens.Add(registrationTokens[i]);
}
}
Console.WriteLine($"List of tokens that caused failures: {failedTokens}");
}
Invia messaggi agli argomenti
Dopo aver creato un argomento, sottoscrivendo le istanze dell'app client all'argomento sul lato client o tramite l' API del server , puoi inviare messaggi all'argomento. Se è la prima volta che crei richieste di invio per FCM, consulta la guida al tuo ambiente server e FCM per importanti informazioni di base e di configurazione.
Nella logica di invio sul backend, specifica il nome dell'argomento desiderato come mostrato:
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);
});
Giava
// 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);
Pitone
# 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)
Andare
// 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);
RIPOSO
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
Per inviare un messaggio a una combinazione di argomenti, specificare una condizione , ovvero un'espressione booleana che specifica gli argomenti di destinazione. Ad esempio, la seguente condizione invierà messaggi ai dispositivi iscritti a TopicA
e TopicB
o TopicC
:
"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"
FCM valuta prima le eventuali condizioni tra parentesi, quindi valuta l'espressione da sinistra a destra. Nell'espressione precedente, un utente iscritto a un singolo argomento non riceve il messaggio. Allo stesso modo, un utente che non è iscritto a TopicA
non riceve il messaggio. Queste combinazioni lo ricevono:
-
TopicA
eTopicB
-
TopicA
eTopicC
Puoi includere fino a cinque argomenti nell'espressione condizionale.
Per inviare a una condizione:
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);
});
Giava
// 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);
Pitone
# 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)
Andare
// 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);
RIPOSO
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
Invia messaggi a gruppi di dispositivi
Per inviare messaggi a gruppi di dispositivi, utilizza l'API HTTP v1. Se attualmente invii a gruppi di dispositivi utilizzando le API di invio legacy deprecate per HTTP o XMPP o una qualsiasi delle versioni precedenti di Firebase Admin SDK per Node.js basata sui protocolli legacy, ti consigliamo vivamente di eseguire la migrazione a HTTP v1 API il prima possibile. Le API di invio legacy verranno disabilitate e rimosse nel giugno 2024.
L'invio di messaggi a un gruppo di dispositivi è molto simile all'invio di messaggi a un singolo dispositivo, utilizzando lo stesso metodo per autorizzare le richieste di invio . Imposta il campo token
sulla chiave di notifica del gruppo:
RIPOSO
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
"data":{
"hello": "This is a Firebase Cloud Messaging device group message!"
}
}
}
comando cURL
curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
"data":{
"hello": "This is a Firebase Cloud Messaging device group message!"
},
"token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send
Invia una serie di messaggi
Gli SDK di amministrazione supportano l'invio di messaggi in batch. Puoi raggruppare fino a 500 messaggi in un unico batch e inviarli tutti in un'unica chiamata API, con un significativo miglioramento delle prestazioni rispetto all'invio di richieste HTTP separate per ciascun messaggio.
Questa funzionalità può essere utilizzata per creare un set personalizzato di messaggi e inviarli a destinatari diversi, inclusi argomenti o token di registrazione del dispositivo specifico. Utilizza questa funzionalità quando, ad esempio, devi inviare simultaneamente messaggi a destinatari diversi con dettagli leggermente diversi nel corpo del messaggio.
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');
});
Giava
// 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");
Pitone
# 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))
Andare
// Create a list containing up to 500 messages.
messages := []*messaging.Message{
{
Notification: &messaging.Notification{
Title: "Price drop",
Body: "5% off all electronics",
},
Token: registrationToken,
},
{
Notification: &messaging.Notification{
Title: "Price drop",
Body: "2% off all books",
},
Topic: "readers-club",
},
}
br, err := client.SendAll(context.Background(), messages)
if err != nil {
log.Fatalln(err)
}
// See the BatchResponse reference documentation
// for the contents of response.
fmt.Printf("%d messages were sent successfully\n", br.SuccessCount)
C#
// Create a list containing up to 500 messages.
var messages = new List<Message>()
{
new Message()
{
Notification = new Notification()
{
Title = "Price drop",
Body = "5% off all electronics",
},
Token = registrationToken,
},
new Message()
{
Notification = new Notification()
{
Title = "Price drop",
Body = "2% off all books",
},
Topic = "readers-club",
},
};
var response = await FirebaseMessaging.DefaultInstance.SendEachAsync(messages);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");
Invia messaggi abilitati all'avvio diretto (solo Android)
Puoi inviare messaggi ai dispositivi in modalità di avvio diretto utilizzando HTTP v1 o API HTTP legacy. Prima di inviare ai dispositivi in modalità di avvio diretto, assicurati di aver completato i passaggi per consentire ai dispositivi client di ricevere messaggi FCM in modalità di avvio diretto .
Invia utilizzando l'API HTTP FCM v1
La richiesta del messaggio deve includere la chiave "direct_boot_ok" : true
nelle opzioni AndroidConfig
del corpo della richiesta. Per esempio:
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,
},
}
Invia utilizzando l'API HTTP legacy di FCM
La richiesta del messaggio deve includere la chiave "direct_boot_ok" : true
al livello più alto del corpo della richiesta. Per esempio:
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
}
I messaggi inviati con questa chiave nel corpo della richiesta possono essere gestiti dalle app sui dispositivi attualmente in modalità di avvio diretto (e anche quando non sono in tale modalità).
Personalizza i messaggi su tutte le piattaforme
Sia Firebase Admin SDK che il protocollo HTTP FCM v1 consentono alle richieste di messaggio di impostare tutti i campi disponibili nell'oggetto message
. Ciò comprende:
- un insieme comune di campi che devono essere interpretati da tutte le istanze dell'app che ricevono il messaggio.
- set di campi specifici della piattaforma, come
AndroidConfig
eWebpushConfig
, interpretati solo dalle istanze dell'app in esecuzione sulla piattaforma specificata.
I blocchi specifici della piattaforma ti offrono la flessibilità di personalizzare i messaggi per piattaforme diverse per garantire che vengano gestiti correttamente una volta ricevuti. Il backend FCM terrà conto di tutti i parametri specificati e personalizzerà il messaggio per ciascuna piattaforma.
Quando utilizzare i campi comuni
Utilizza i campi comuni quando:
- Targeting per istanze di app su tutte le piattaforme: Apple, Android e Web
- Invio di messaggi ad argomenti
Tutte le istanze dell'app, indipendentemente dalla piattaforma, possono interpretare i seguenti campi comuni:
Quando utilizzare i campi specifici della piattaforma
Utilizza i campi specifici della piattaforma quando desideri:
- Invia campi solo a piattaforme particolari
- Invia campi specifici della piattaforma oltre ai campi comuni
Ogni volta che desideri inviare valori solo a piattaforme particolari, non utilizzare campi comuni; utilizzare campi specifici della piattaforma. Ad esempio, per inviare una notifica solo alle piattaforme Apple e web ma non ad Android, è necessario utilizzare due set di campi separati, uno per Apple e uno per il web.
Quando invii messaggi con opzioni di consegna specifiche, utilizza i campi specifici della piattaforma per impostarli. Se lo desideri, puoi specificare valori diversi per piattaforma. Tuttavia, anche quando desideri impostare essenzialmente lo stesso valore su tutte le piattaforme, devi utilizzare campi specifici della piattaforma. Questo perché ciascuna piattaforma può interpretare il valore in modo leggermente diverso: ad esempio, il time-to-live è impostato su Android come una scadenza in secondi, mentre su Apple è impostato come una data di scadenza.
Esempio: messaggio di notifica con opzioni di colore e icona
Questa richiesta di invio di esempio invia un titolo e un contenuto di notifica comuni a tutte le piattaforme, ma invia anche alcune sostituzioni specifiche della piattaforma ai dispositivi Android.
Per Android, la richiesta imposta un'icona e un colore speciali da visualizzare sui dispositivi Android. Come indicato nel riferimento per AndroidNotification , il colore è specificato nel formato #rrggbb e l'immagine deve essere una risorsa icona disegnabile locale nell'app Android.
Ecco un'approssimazione dell'effetto visivo sul dispositivo di un utente:
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);
});
Giava
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();
Pitone
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',
)
Andare
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",
};
RIPOSO
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"
}
}
}
}
Consulta la documentazione di riferimento HTTP v1 per dettagli completi sulle chiavi disponibili nei blocchi specifici della piattaforma nel corpo del messaggio.
Esempio: messaggio di notifica con un'immagine personalizzata
La seguente richiesta di invio di esempio invia un titolo di notifica comune a tutte le piattaforme, ma invia anche un'immagine. Ecco un'approssimazione dell'effetto visivo sul dispositivo di un utente:
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);
});
RIPOSO
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"
}
}
}
}
Consulta la documentazione di riferimento HTTP v1 per dettagli completi sulle chiavi disponibili nei blocchi specifici della piattaforma nel corpo del messaggio.
Esempio: messaggio di notifica con un'azione di clic associata
La richiesta di invio di esempio seguente invia un titolo di notifica comune a tutte le piattaforme, ma invia anche un'azione che l'app deve eseguire in risposta all'utente che interagisce con la notifica. Ecco un'approssimazione dell'effetto visivo sul dispositivo di un utente:
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);
});
RIPOSO
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"
}
}
}
}
Consulta la documentazione di riferimento HTTP v1 per dettagli completi sulle chiavi disponibili nei blocchi specifici della piattaforma nel corpo del messaggio.
Esempio: messaggio di notifica con opzioni di localizzazione
La seguente richiesta di invio di esempio invia le opzioni di localizzazione affinché il client possa visualizzare i messaggi localizzati. Ecco un'approssimazione dell'effetto visivo sul dispositivo di un utente:
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);
});
RIPOSO
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"],
},
},
},
},
},
}'
Consulta la documentazione di riferimento HTTP v1 per dettagli completi sulle chiavi disponibili nei blocchi specifici della piattaforma nel corpo del messaggio.
Codici di errore REST per l'API HTTP v1
Le risposte agli errori HTTP per l'API HTTP v1 contengono un codice di errore, un messaggio di errore e uno stato di errore. Possono anche contenere un array details
con maggiori dettagli sull'errore.
Ecco due esempi di risposte agli errori:
Esempio 1: risposta di errore da una richiesta API HTTP v1 con un valore non valido in un messaggio di dati
{
"error": {
"code": 400,
"message": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [
{
"field": "message.data[0].value",
"description": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12"
}
]
}
]
}
}
Esempio 2: risposta di errore da una richiesta API HTTP v1 con un token di registrazione non valido
{
"error": {
"code": 400,
"message": "The registration token is not a valid FCM registration token",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.firebase.fcm.v1.FcmError",
"errorCode": "INVALID_ARGUMENT"
}
]
}
}
Tieni presente che entrambi i messaggi hanno lo stesso codice e stato, ma l'array dei dettagli contiene valori di tipo diverso. Il primo esempio ha il tipo type.googleapis.com/google.rpc.BadRequest
che indica un errore nei valori della richiesta. Il secondo esempio con tipo type.googleapis.com/google.firebase.fcm.v1.FcmError
contiene un errore specifico di FCM. Per molti errori, l'array dei dettagli contiene le informazioni necessarie per eseguire il debug e trovare una soluzione.
La tabella seguente elenca i codici di errore dell'API REST FCM v1 e le relative descrizioni.
Codice di errore | Descrizione e passaggi di risoluzione |
---|---|
UNSPECIFIED_ERROR Non sono disponibili ulteriori informazioni su questo errore. | Nessuno. |
INVALID_ARGUMENT (codice errore HTTP = 400) I parametri della richiesta non erano validi. Viene restituita un'estensione di tipo google.rpc.BadRequest per specificare quale campo non era valido. | Le possibili cause includono registrazione non valida, nome pacchetto non valido, messaggio troppo grande, chiave dati non valida, TTL non valido o altri parametri non validi. Registrazione non valida : controlla il formato del token di registrazione che passi al server. Assicurati che corrisponda al token di registrazione che l'app client riceve dalla registrazione con FCM. Non troncare il token né aggiungere ulteriori caratteri. Nome pacchetto non valido : assicurati che il messaggio fosse indirizzato a un token di registrazione il cui nome pacchetto corrisponde al valore passato nella richiesta. Messaggio troppo grande : verifica che la dimensione totale dei dati del payload inclusi in un messaggio non superi i limiti FCM: 4096 byte per la maggior parte dei messaggi o 2048 byte nel caso di messaggi ad argomenti. Ciò include sia le chiavi che i valori. Chiave dati non valida : controlla che i dati del payload non contengano una chiave (come from, o gcm, o qualsiasi valore con prefisso google) utilizzata internamente da FCM. Tieni presente che alcune parole (come breakdown_key) vengono utilizzate anche da FCM ma sono consentite nel payload, nel qual caso il valore del payload verrà sovrascritto dal valore FCM. TTL non valido : verificare che il valore utilizzato in ttl sia un numero intero che rappresenta una durata in secondi compresa tra 0 e 2.419.200 (4 settimane). Parametri non validi : verifica che i parametri forniti abbiano il nome e il tipo corretti. |
UNREGISTERED (codice errore HTTP = 404) La registrazione dell'istanza dell'app da FCM è stata annullata. Questo di solito significa che il token utilizzato non è più valido ed è necessario utilizzarne uno nuovo. | Questo errore può essere causato dalla mancanza di token di registrazione o da token non registrati. Registrazione mancante : se la destinazione del messaggio è un valore token , verifica che la richiesta contenga un token di registrazione.Non registrato : un token di registrazione esistente può cessare di essere valido in una serie di scenari, tra cui: - Se l'app client annulla la registrazione con FCM. - Se la registrazione dell'app client viene annullata automaticamente, cosa che può verificarsi se l'utente disinstalla l'applicazione. Ad esempio, su iOS, se il servizio di feedback APN segnala il token APN come non valido. - Se il token di registrazione scade (ad esempio, Google potrebbe decidere di aggiornare i token di registrazione o il token APN è scaduto per i dispositivi iOS). - Se l'app client viene aggiornata ma la nuova versione non è configurata per ricevere messaggi. In tutti questi casi, rimuovi questo token di registrazione dal server dell'app e smetti di usarlo per inviare messaggi. |
SENDER_ID_MISMATCH (codice errore HTTP = 403) L'ID mittente autenticato è diverso dall'ID mittente per il token di registrazione. | Un token di registrazione è legato a un determinato gruppo di mittenti. Quando un'app client si registra per FCM, deve specificare quali mittenti sono autorizzati a inviare messaggi. Dovresti utilizzare uno di questi ID mittente quando invii messaggi all'app client. Se passi a un mittente diverso, i token di registrazione esistenti non funzioneranno. |
QUOTA_EXCEEDED (codice errore HTTP = 429) Limite di invio superato per la destinazione del messaggio. Viene restituita un'estensione di tipo google.rpc.QuotaFailure per specificare quale quota è stata superata. | Questo errore può essere causato dal superamento della quota per la velocità dei messaggi, dal superamento della quota per i messaggi del dispositivo o dal superamento della quota per i messaggi dell'argomento. Velocità messaggi superata : la velocità di invio dei messaggi è troppo alta. È necessario ridurre la velocità complessiva con cui si inviano i messaggi. Utilizza il backoff esponenziale con un ritardo iniziale minimo di 1 minuto per ritentare i messaggi rifiutati. Frequenza messaggi dispositivo superata : la frequenza dei messaggi inviati a un particolare dispositivo è troppo alta. Visualizza il limite di velocità dei messaggi per un singolo dispositivo . Riduci il numero di messaggi inviati a questo dispositivo e utilizza il backoff esponenziale per ritentare l'invio. Frequenza messaggi argomento superata : la frequenza dei messaggi agli iscritti a un particolare argomento è troppo alta. Riduci il numero di messaggi inviati per questo argomento e utilizza il backoff esponenziale con un ritardo iniziale minimo di 1 minuto per ritentare l'invio. |
UNAVAILABLE (codice errore HTTP = 503) Il server è sovraccarico. | Il server non è riuscito a elaborare la richiesta in tempo. Riprovare la stessa richiesta, ma è necessario: - Rispettare l'intestazione Retry-After se è inclusa nella risposta dal server di connessione FCM. - Implementa il back-off esponenziale nel meccanismo dei tentativi. (es. se hai aspettato un secondo prima del primo tentativo, aspetta almeno due secondi prima del successivo, poi 4 secondi e così via). Se invii più messaggi, valuta la possibilità di applicare il jitter. Per ulteriori informazioni, vedere Gestione dei tentativi . I mittenti che causano problemi rischiano di essere inseriti nella lista nera. |
INTERNAL (codice errore HTTP = 500) Si è verificato un errore interno sconosciuto. | Il server ha riscontrato un errore durante il tentativo di elaborare la richiesta. Puoi riprovare la stessa richiesta seguendo i suggerimenti in Gestione dei tentativi . Se l'errore persiste, contatta il supporto Firebase. |
THIRD_PARTY_AUTH_ERROR (codice errore HTTP = 401) Il certificato APN o la chiave di autenticazione push Web non erano validi o mancavano. | Non è stato possibile inviare un messaggio destinato a un dispositivo iOS o una registrazione push web. Verifica la validità delle tue credenziali di sviluppo e produzione. |
Codici di errore dell'amministratore
La tabella seguente elenca i codici di errore dell'API FCM di amministrazione di Firebase e le relative descrizioni, inclusi i passaggi di risoluzione consigliati.
Codice di errore | Descrizione e passaggi di risoluzione |
---|---|
messaging/invalid-argument | È stato fornito un argomento non valido a un metodo FCM. Il messaggio di errore dovrebbe contenere informazioni aggiuntive. |
messaging/invalid-recipient | Il destinatario del messaggio previsto non è valido. Il messaggio di errore dovrebbe contenere informazioni aggiuntive. |
messaging/invalid-payload | È stato fornito un oggetto payload del messaggio non valido. Il messaggio di errore dovrebbe contenere informazioni aggiuntive. |
messaging/invalid-data-payload-key | Il payload del messaggio di dati contiene una chiave non valida. Consulta la documentazione di riferimento per DataMessagePayload per le chiavi limitate. |
messaging/payload-size-limit-exceeded | Il payload del messaggio fornito supera i limiti di dimensione FCM. Il limite è 4096 byte per la maggior parte dei messaggi. Per i messaggi inviati agli argomenti, il limite è 2048 byte. La dimensione totale del payload include sia chiavi che valori. |
messaging/invalid-options | È stato fornito un oggetto opzioni messaggio non valido. Il messaggio di errore dovrebbe contenere informazioni aggiuntive. |
messaging/invalid-registration-token | Token di registrazione fornito non valido. Assicurati che corrisponda al token di registrazione che l'app client riceve dalla registrazione con FCM. Non troncare né aggiungere ulteriori caratteri. |
messaging/registration-token-not-registered | Il token di registrazione fornito non è registrato. È possibile annullare la registrazione di un token di registrazione precedentemente valido per diversi motivi, tra cui:
|
messaging/invalid-package-name | Il messaggio è stato indirizzato a un token di registrazione il cui nome di pacchetto non corrisponde all'opzione restrictedPackageName fornita. |
messaging/message-rate-exceeded | La frequenza dei messaggi verso un determinato target è troppo elevata. Riduci il numero di messaggi inviati a questo dispositivo o argomento e non riprovare immediatamente l'invio a questa destinazione. |
messaging/device-message-rate-exceeded | La frequenza dei messaggi inviati a un particolare dispositivo è troppo elevata. Ridurre il numero di messaggi inviati a questo dispositivo e non ritentare immediatamente l'invio a questo dispositivo. |
messaging/topics-message-rate-exceeded | La frequenza dei messaggi agli abbonati a un particolare argomento è troppo alta. Riduci il numero di messaggi inviati per questo argomento e non riprovare immediatamente l'invio a questo argomento. |
messaging/too-many-topics | Un token di registrazione è stato sottoscritto al numero massimo di argomenti e non può più essere sottoscritto. |
messaging/invalid-apns-credentials | Non è stato possibile inviare un messaggio destinato a un dispositivo Apple perché il certificato SSL APN richiesto non è stato caricato o è scaduto. Verifica la validità dei tuoi certificati di sviluppo e produzione. |
messaging/mismatched-credential | La credenziale utilizzata per autenticare questo SDK non dispone dell'autorizzazione per inviare messaggi al dispositivo corrispondente al token di registrazione fornito. Assicurati che la credenziale e il token di registrazione appartengano entrambi allo stesso progetto Firebase. Consulta Aggiungere Firebase alla tua app per la documentazione su come autenticare gli SDK di amministrazione di Firebase. |
messaging/authentication-error | L'SDK non è riuscito ad autenticarsi sui server FCM. Assicurati di autenticare Firebase Admin SDK con una credenziale che disponga delle autorizzazioni adeguate per inviare messaggi FCM. Consulta Aggiungere Firebase alla tua app per la documentazione su come autenticare gli SDK di amministrazione di Firebase. |
messaging/server-unavailable | Il server FCM non è riuscito a elaborare la richiesta in tempo. Dovresti riprovare la stessa richiesta, ma devi:
|
messaging/internal-error | Il server FCM ha riscontrato un errore durante il tentativo di elaborare la richiesta. Puoi riprovare la stessa richiesta seguendo i requisiti elencati nella riga messaging/server-unavailable sopra. Se l'errore persiste, segnala il problema al nostro canale di supporto Segnalazione bug . |
messaging/unknown-error | È stato restituito un errore del server sconosciuto. Per ulteriori dettagli, vedere la risposta grezza del server nel messaggio di errore. Se ricevi questo errore, segnala il messaggio di errore completo al nostro canale di supporto Segnalazione bug . |
Invia messaggi utilizzando i protocolli del server dell'app legacy
Se attualmente utilizzi i protocolli legacy, crea richieste di messaggi come mostrato in questa sezione. Tieni presente che, se invii a più piattaforme tramite HTTP, il protocollo v1 può semplificare notevolmente le tue richieste di messaggi.
Invia messaggi a dispositivi specifici
Per inviare messaggi a dispositivi specifici, imposta la chiave to
sul token di registrazione per l'istanza specifica dell'app. Consulta le informazioni sulla configurazione del client per la tua piattaforma per ulteriori informazioni sui token di registrazione.
Richiesta POST HTTP
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..."
}
Risposta HTTP
{ "multicast_id": 108, "success": 1, "failure": 0, "results": [ { "message_id": "1:08" } ] }
messaggio XMPP
<message id="">
<gcm xmlns="google:mobile:data">
{ "data": {
"score": "5x1",
"time": "15:10"
},
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}
</gcm>
</message>
Risposta XMPP
<message id=""> <gcm xmlns="google:mobile:data"> { "from":"REGID", "message_id":"m-1366082849205" "message_type":"ack" } </gcm> </message>
Il server di connessione XMPP fornisce alcune altre opzioni per le risposte. Vedere Formato di risposta del server .
Per l'elenco completo delle opzioni di messaggio disponibili quando si inviano messaggi downstream alle app client, vedere le informazioni di riferimento per il protocollo del server di connessione scelto, HTTP o XMPP .
Invia messaggi agli argomenti
L'invio di messaggi a un argomento Firebase Cloud Messaging è molto simile all'invio di messaggi a un singolo dispositivo o a un gruppo di utenti. Il server delle applicazioni imposta la chiave to
con un valore come /topics/yourTopic
. Gli sviluppatori possono scegliere qualsiasi nome di argomento che corrisponda all'espressione regolare: "/topics/[a-zA-Z0-9-_.~%]+"
.
Per inviare combinazioni di più argomenti, il server delle applicazioni deve impostare la chiave condition
(invece della chiave to
) su una condizione booleana che specifica gli argomenti di destinazione. Ad esempio, per inviare messaggi ai dispositivi che si sono abbonati a TopicA
e TopicB
o TopicC
:
'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)
FCM valuta prima le eventuali condizioni tra parentesi, quindi valuta l'espressione da sinistra a destra. Nell'espressione precedente, un utente iscritto a un singolo argomento non riceve il messaggio. Allo stesso modo, un utente che non è iscritto a TopicA non riceve il messaggio. Queste combinazioni lo ricevono:
- Argomento A e Argomento B
- ArgomentoA e ArgomentoC
Puoi includere fino a cinque argomenti nell'espressione condizionale e le parentesi sono supportate. Operatori supportati: &&
, ||
.
Richiesta HTTP POST dell'argomento
Invia a un singolo argomento:
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
Invia ai dispositivi iscritti agli argomenti "cani" o "gatti":
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
Risposta HTTP dell'argomento
// Success example: { "message_id": "1023456" } // failure example: { "error": "TopicsMessageRateExceeded" }
Messaggio XMPP dell'argomento
Invia a un singolo argomento:
<message id="">
<gcm xmlns="google:mobile:data">
</gcm>
</message>
Invia ai dispositivi iscritti agli argomenti "cani" o "gatti":
<message id=""> <gcm xmlns="google:mobile:data"> </gcm> </message>
Risposta XMPP dell'argomento
// Success example: { "message_id": "1023456" } // failure example: { "error": "TopicsMessageRateExceeded" }
Sono previsti fino a 30 secondi di ritardo prima che il server FCM restituisca una risposta di esito positivo o negativo alle richieste di invio dell'argomento. Assicurati di impostare di conseguenza il valore di timeout del server dell'app nella richiesta.
Invia messaggi a gruppi di dispositivi
L'invio di messaggi a un gruppo di dispositivi utilizzando le API legacy deprecate è molto simile all'invio di messaggi a un singolo dispositivo. Impostare il parametro to
sulla chiave di notifica univoca per il gruppo di dispositivi. Gli esempi in questa sezione mostrano come inviare messaggi di dati a gruppi di dispositivi nei protocolli HTTP e XMPP legacy.
Richiesta POST HTTP del gruppo di dispositivi
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!", } }
Risposta HTTP del gruppo di dispositivi
Ecco un esempio di "successo": notification_key
ha 2 token di registrazione associati e il messaggio è stato inviato con successo a entrambi:
{ "success": 2, "failure": 0 }
Ecco un esempio di "successo parziale": notification_key
ha 3 token di registrazione associati. Il messaggio è stato inviato correttamente solo a 1 dei token di registrazione. Il messaggio di risposta elenca i token di registrazione ( registration_ids
) che non sono riusciti a ricevere il messaggio:
{ "success":1, "failure":2, "failed_registration_ids":[ "regId1", "regId2" ] }
Quando un messaggio non viene recapitato a uno o più token di registrazione associati a notification_key
, il server delle applicazioni deve riprovare con backoff tra i tentativi.
Se il server tenta di inviare un messaggio a un gruppo di dispositivi che non ha membri, la risposta è simile alla seguente, con 0 successi e 0 errori:
{ "success": 0, "failure": 0 }
Messaggio XMPP del gruppo di dispositivi
<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>
Risposta XMPP del gruppo di dispositivi
Quando il messaggio viene inviato correttamente a uno qualsiasi dei dispositivi del gruppo, il server di connessione XMPP risponde con un ACK. Se tutti i messaggi inviati a tutti i dispositivi del gruppo falliscono, il server di connessione XMPP risponde con un NACK.
Ecco un esempio di "successo": notification_key
ha 3 token di registrazione associati e il messaggio è stato inviato con successo a tutti:
{ "from": "aUniqueKey", "message_type": "ack", "success": 3, "failure": 0, "message_id": "m-1366082849205" }
Ecco un esempio di "successo parziale": notification_key
ha 3 token di registrazione associati. Il messaggio è stato inviato correttamente solo a 1 dei token di registrazione. Il messaggio di risposta elenca i token di registrazione che non sono riusciti a ricevere il messaggio:
{ "from": "aUniqueKey", "message_type": "ack", "success":1, "failure":2, "failed_registration_ids":[ "regId1", "regId2" ] }
Quando il server di connessione FCM non riesce a effettuare la consegna a tutti i dispositivi nel gruppo. Il server dell'app riceverà una risposta nack.
Per l'elenco completo delle opzioni dei messaggi, consulta le informazioni di riferimento per il protocollo del server di connessione scelto, HTTP o XMPP .
Metodi di invio legacy dell'SDK Admin di Firebase
L'SDK Firebase Admin Node.js supporta metodi per l'invio di messaggi (FCM) basati sull'API del server FCM legacy . Questi metodi accettano argomenti diversi rispetto al metodo send()
. Dovresti utilizzare il metodo send()
quando possibile e utilizzare solo i metodi descritti in questa pagina quando invii messaggi a singoli dispositivi o gruppi di dispositivi.
Invia a singoli dispositivi
Puoi passare un token di registrazione al metodo sendToDevice()
per inviare un messaggio a quel 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);
});
Il metodo sendToDevice()
può anche inviare un messaggio multicast (ovvero un messaggio a più dispositivi) passando un array di token di registrazione invece di un solo token di registrazione:
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);
});
Il metodo sendToDevice()
restituisce una promessa che viene risolta con un oggetto MessagingDevicesResponse
contenente la risposta di FCM. Il tipo restituito ha lo stesso formato quando si passa un singolo token di registrazione o una serie di token di registrazione.
Alcuni casi, come un errore di autenticazione o una limitazione della velocità, causano la mancata elaborazione dell'intero messaggio. In questi casi, la promessa restituita da sendToDevice()
viene rifiutata con un errore. Per un elenco completo dei codici di errore, incluse descrizioni e passaggi di risoluzione, consulta Errori API FCM di amministrazione .
Invia a un gruppo di dispositivi
Il metodo sendToDeviceGroup()
consente di inviare un messaggio a un gruppo di dispositivi specificando la chiave di notifica per quel gruppo di dispositivi:
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);
});
Il metodo sendToDeviceGroup()
restituisce una promessa che viene risolta con un oggetto MessagingDevicesResponse
contenente la risposta di FCM.
Alcuni casi, come un errore di autenticazione o una limitazione della velocità, causano la mancata elaborazione dell'intero messaggio. In questi casi, la promessa restituita da sendToDeviceGroup()
viene rifiutata con un errore. Per un elenco completo dei codici di errore, incluse descrizioni e passaggi di risoluzione, consulta Errori API FCM di amministrazione .
Definizione del payload del messaggio
I metodi di cui sopra basati sui protocolli legacy FCM accettano il payload di un messaggio come secondo argomento e supportano sia i messaggi di notifica che quelli di dati . È possibile specificare uno o entrambi i tipi di messaggio creando un oggetto con i data
e/o le chiavi notification
. Ad esempio, ecco come definire diversi tipi di payload dei messaggi:
Messaggio di notifica
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.'
}
};
Messaggio di dati
const payload = {
data: {
score: '850',
time: '2:45'
}
};
Messaggio combinato
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'
}
};
I payload dei messaggi di notifica hanno un sottoinsieme predefinito di proprietà valide e differiscono leggermente a seconda del sistema operativo mobile scelto come target. Consulta i documenti di riferimento per NotificationMessagePayload
per un elenco completo.
I payload dei messaggi di dati sono composti da coppie chiave-valore personalizzate con alcune restrizioni, incluso il fatto che tutti i valori devono essere stringhe. Consulta i documenti di riferimento per DataMessagePayload
per un elenco completo delle restrizioni.
Definizione delle opzioni del messaggio
I metodi precedenti basati sui protocolli legacy FCM accettano un terzo argomento opzionale che specifica alcune opzioni per il messaggio. Ad esempio, l'esempio seguente invia un messaggio ad alta priorità a un dispositivo che scade dopo 24 ore:
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);
});
Consulta i documenti di riferimento per MessagingOptions
per un elenco completo delle opzioni disponibili.