Richieste di invio del server di app della build

Utilizzando i protocolli del server app Firebase Admin SDK o FCM, puoi creare richieste di messaggi e inviarle a questi tipi di target:

  • Nome argomento
  • Condizione
  • Token di registrazione del dispositivo
  • Nome del gruppo di dispositivi (solo protocollo)

Puoi inviare messaggi con un payload di notifica costituito da campi predefiniti, un payload di dati dei tuoi campi definiti dall'utente o un messaggio contenente entrambi i tipi di payload. Per ulteriori informazioni, consulta Tipi di messaggi.

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 1.0. Sono inoltre fornite indicazioni per l'invio di messaggi tramite i protocolli HTTP e XMPP legacy deprecati.

Inviare messaggi a dispositivi specifici

Per inviare a un singolo dispositivo specifico, passa il token di registrazione del dispositivo come mostrato. Per scoprire di più sui token di registrazione, consulta le informazioni di configurazione del client per la tua piattaforma.

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);
FirebaseMessagingSnippets.java

Python

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

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

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

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)
messaging.go

C#

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

// See documentation on defining a message payload.
var message = new Message()
{
    Data = new Dictionary<string, string>()
    {
        { "score", "850" },
        { "time", "2:45" },
    },
    Token = registrationToken,
};

// Send a message to the device corresponding to the provided
// registration token.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

REST

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

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

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

Comando cURL:

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

In caso di esito positivo, ogni 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"
    }

Inviare messaggi a più dispositivi

Le API FCM di amministrazione ti consentono di inviare un messaggio in multicast a un elenco di token di registrazione del dispositivo. Puoi specificare fino a 500 token di registrazione del dispositivo per chiamata.

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");
FirebaseMessagingSnippets.java

Python

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

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

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)
messaging.go

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");
FirebaseMessagingSnippets.cs

Il valore restituito è un elenco di token che corrisponde all'ordine dei token di input. Questo è utile per 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);
    }
  });

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);
}
FirebaseMessagingSnippets.java

Python

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

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

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)
}
messaging.go

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

FirebaseMessagingSnippets.cs

Invia messaggi agli argomenti

Dopo aver creato un argomento, sottoscrivendo le istanze dell'app client all'argomento sul lato client o tramite l'API server, puoi inviare messaggi all'argomento. Se è la prima volta che crei richieste di invio per FCM, consulta la guida relativa al tuo ambiente server e a FCM per informazioni importanti di contesto e configurazione.

Nella logica di invio sul backend, specifica il nome dell'argomento preferito come mostrato di seguito:

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);
FirebaseMessagingSnippets.java

Python

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

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

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

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)
messaging.go

C#

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

// See documentation on defining a message payload.
var message = new Message()
{
    Data = new Dictionary<string, string>()
    {
        { "score", "850" },
        { "time", "2:45" },
    },
    Topic = topic,
};

// Send a message to the devices subscribed to the provided topic.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

REST

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

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
    "topic" : "foo-bar",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message"
      }
   }
}

Comando cURL:

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

Per inviare un messaggio a una combinazione di argomenti, specifica 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 eventuali condizioni tra parentesi, quindi valuta l'espressione da sinistra a destra. Nell'espressione precedente, un utente iscritto a qualsiasi singolo argomento non riceve il messaggio. Allo stesso modo, un utente che non si abbona a TopicA non riceve il messaggio. Queste combinazioni lo ricevono:

  • TopicA e TopicB
  • TopicA e TopicC

Puoi includere fino a cinque argomenti nell'espressione condizionale.

Per inviare un messaggio 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);
  });

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);
FirebaseMessagingSnippets.java

Python

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

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

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

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)
messaging.go

C#

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

// See documentation on defining a message payload.
var message = new Message()
{
    Notification = new Notification()
    {
        Title = "$GOOG up 1.43% on the day",
        Body = "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
    },
    Condition = condition,
};

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

REST

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

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

Comando cURL:

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

Inviare messaggi ai gruppi di dispositivi

Per inviare messaggi a gruppi di dispositivi, utilizza l'API HTTP v1. Se al momento invii messaggi a gruppi di dispositivi utilizzando le API di invio legacy ritirate per HTTP o XMPP o una delle versioni precedenti di Firebase Admin SDK per Node.js basate sui protocolli legacy, ti consigliamo vivamente di eseguire la migrazione all'API HTTP v1 al più presto. Le API di invio legacy verranno disabilitate e rimosse a 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 l'invio delle richieste. Imposta il campo token sulla chiave di notifica del gruppo:

REST

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

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

{
   "message":{
      "token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
      "data":{
        "hello": "This is a Firebase Cloud Messaging device group message!"
      }
   }
}

Comando cURL

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
   "data":{
     "hello": "This is a Firebase Cloud Messaging device group message!"
   },
   "token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

Inviare un batch di messaggi

Gli SDK Amministrazione supportano l'invio di messaggi in batch. Puoi raggruppare fino a 500 messaggi in un unico batch e inviarli tutti in una singola chiamata API, con un miglioramento significativo del rendimento rispetto all'invio di richieste HTTP separate per ogni messaggio.

Questa funzionalità può essere utilizzata per creare un insieme di messaggi personalizzati e inviarli a diversi destinatari, inclusi argomenti o token di registrazione del dispositivo specifici. Utilizza questa funzionalità, ad esempio, se devi inviare contemporaneamente messaggi a segmenti di pubblico 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');
  });

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");
FirebaseMessagingSnippets.java

Python

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

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

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)
messaging.go

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");
FirebaseMessagingSnippets.cs

Invia messaggi abilitati per l'avvio diretto (solo Android)

Puoi inviare messaggi ai dispositivi in modalità di avvio diretto utilizzando le API HTTP v1 o HTTP legacy. Prima di inviare i messaggi 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 tramite l'API HTTP FCM v1

La richiesta di messaggio deve includere la chiave "direct_boot_ok" : true nelle opzioni AndroidConfig del corpo della richiesta. Ad 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,
    },
}

Invio tramite l'API HTTP FCM precedente

La richiesta di messaggio deve includere la chiave "direct_boot_ok" : true al livello superiore del corpo della richiesta. Ad 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 questa modalità).

Personalizza i messaggi su più piattaforme

Sia il protocollo HTTP Firebase Admin SDK sia il protocollo HTTP FCM 1.0 consentono alle richieste di messaggio di impostare tutti i campi disponibili nell'oggetto message. Sono inclusi:

  • un insieme comune di campi da interpretare da tutte le istanze dell'app che ricevono il messaggio.
  • insiemi di campi specifici della piattaforma, come AndroidConfig e WebpushConfig, 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 assicurarti che vengano gestiti correttamente al momento della ricezione. Il backend FCM prenderà in considerazione tutti i parametri specificati e personalizzerà il messaggio per ogni piattaforma.

Quando utilizzare i campi comuni

Utilizza i campi comuni quando:

  • Targeting di istanze di app su tutte le piattaforme: Apple, Android e web
  • Invio di messaggi per 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 vuoi:

  • Inviare campi solo a piattaforme specifiche
  • Invia campi specifici della piattaforma oltre a quelli comuni

Quando vuoi inviare valori solo a piattaforme specifiche, non utilizzare i campi comuni, ma quelli specifici della piattaforma. Ad esempio, per inviare una notifica solo alle piattaforme Apple e al web, ma non ad Android, devi utilizzare due insiemi di campi distinti, uno per Apple e uno per il web.

Quando invii messaggi con opzioni di recapito specifiche, utilizza i campi specifici della piattaforma per impostarle. Se vuoi, puoi specificare valori diversi per piattaforma. Tuttavia, anche se vuoi impostare essenzialmente lo stesso valore su tutte le piattaforme, devi utilizzare campi specifici della piattaforma. Questo perché ogni piattaforma potrebbe interpretare il valore in modo leggermente diverso. Ad esempio, il TTL è impostato su Android come data e ora di scadenza in secondi, mentre su Apple è impostato come data di scadenza.

Esempio: messaggio di notifica con opzioni di colore e icona

Questa richiesta di invio di esempio invia un titolo e contenuti di notifica comuni a tutte le piattaforme, ma invia anche alcune sostituzioni specifiche della piattaforma ai dispositivi Android.

Per Android, con la richiesta vengono impostati un'icona e un colore speciali da visualizzare sui dispositivi Android. Come indicato nella documentazione di riferimento di AndroidNotification, il colore è specificato nel formato #rrggbb e l'immagine deve essere una risorsa icona drawable locale dell'app per Android.

Ecco un'approssimazione dell'effetto visivo sul dispositivo di un utente:

Semplice disegno di due dispositivi, uno dei quali mostra un&#39;icona e un colore personalizzati

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();
FirebaseMessagingSnippets.java

Python

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

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",
}
messaging.go

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

REST

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

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

Consulta la documentazione di riferimento HTTP v1 per informazioni dettagliate sulle chiavi disponibili nei blocchi specifici della piattaforma nel corpo del messaggio.

Esempio: messaggio di notifica con un'immagine personalizzata

L'esempio seguente di richiesta di invio 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:

Disegno semplice di un&#39;immagine in una notifica sul display

Node.js

const topicName = 'industry-tech';

const message = {
  notification: {
    title: 'Sparky says hello!'
  },
  android: {
    notification: {
      imageUrl: 'https://foo.bar.pizza-monster.png'
    }
  },
  apns: {
    payload: {
      aps: {
        'mutable-content': 1
      }
    },
    fcm_options: {
      image: 'https://foo.bar.pizza-monster.png'
    }
  },
  webpush: {
    headers: {
      image: 'https://foo.bar.pizza-monster.png'
    }
  },
  topic: topicName,
};

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

REST

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

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

Consulta la documentazione di riferimento HTTP v1 per informazioni dettagliate 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 dell'esempio seguente invia un titolo di notifica comune a tutte le piattaforme, ma anche un'azione che l'app deve eseguire in risposta all'interazione dell'utente con la notifica. Di seguito è riportata un'approssimazione dell'effetto visivo sul dispositivo di un utente:

Disegno semplice di un tocco dell&#39;utente che apre una pagina 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);
  });

REST

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

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

Consulta la documentazione di riferimento per HTTP v1 per tutti i dettagli sulle chiavi disponibili nei blocchi specifici della piattaforma nel corpo del messaggio.

Esempio: messaggio di notifica con opzioni di localizzazione

L'esempio seguente mostra una richiesta di invio che invia le opzioni di localizzazione per consentire al client di visualizzare i messaggi localizzati. Ecco un'approssimazione dell'effetto visivo sul dispositivo di un utente:

Disegno semplice di due dispositivi che mostrano testo in inglese e spagnolo

Node.js

var topicName = 'industry-tech';

var message = {
  android: {
    ttl: 3600000,
    notification: {
      bodyLocKey: 'STOCK_NOTIFICATION_BODY',
      bodyLocArgs: ['FooCorp', '11.80', '835.67', '1.43']
    }
  },
  apns: {
    payload: {
      aps: {
        alert: {
          locKey: 'STOCK_NOTIFICATION_BODY',
          locArgs: ['FooCorp', '11.80', '835.67', '1.43']
        }
      }
    }
  },
  topic: topicName,
};

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

REST

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

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

Consulta la documentazione di riferimento per HTTP v1 per tutti i dettagli sulle chiavi disponibili nei blocchi specifici della piattaforma nel corpo del messaggio.

Codici di errore REST per l'API HTTP v1

Le risposte di errore HTTP per l'API HTTP v1 contengono un codice di errore, un messaggio di errore e lo stato di errore. Potrebbero anche contenere un array details con ulteriori dettagli sull'errore.

Ecco due esempi di risposte di errore:

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"
      }
    ]
   }
}

Nota che entrambi i messaggi hanno lo stesso codice e lo stesso stato, ma l'array di dettagli contiene valori di tipi diversi. 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 presenta un errore specifico di FCM. Per molti errori, l'array details contiene le informazioni necessarie per eseguire il debug e trovare una soluzione.

Nella tabella seguente sono elencati i codici di errore dell'API REST FCM 1.0 e le relative descrizioni.

Codice di errore Descrizione e passaggi per la risoluzione
UNSPECIFIED_ERROR Non sono disponibili altre informazioni su questo errore. Nessuno.
INVALID_ARGUMENT (codice di errore HTTP = 400) Parametri della richiesta non validi. Viene restituita un'estensione di tipo google.rpc.BadRequest per specificare quale campo non è valido. Le potenziali cause includono registrazione non valida, nome del pacchetto non valido, messaggio troppo grande, chiave di 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 ricevuto dall'app client dalla registrazione a FCM. Non troncare il token o aggiungere altri caratteri.
Nome del pacchetto non valido: assicurati che il messaggio sia indirizzato a un token di registrazione il cui nome del pacchetto corrisponda al valore passato nella richiesta.
Messaggio troppo grande: verifica che le dimensioni totali dei dati del payload inclusi in un messaggio non superino i limiti di FCM: 4096 byte per la maggior parte dei messaggi o 2048 byte per i messaggi agli argomenti. Sono inclusi sia le chiavi che i valori.
Chiave di dati non valida: verifica che i dati del payload non contengano una chiave (ad esempio from, gcm o qualsiasi valore con prefisso google) utilizzata internamente da FCM. Tieni presente che alcune parole (ad esempio collapse_key) vengono utilizzate anche da FCM, ma sono consentite nel payload. In questo caso, il valore del payload verrà sostituito dal valore FCM.
TTL non valido: verifica che il valore utilizzato in ttl sia un numero intero che rappresenti 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 di errore HTTP = 404) È stata annullata la registrazione dell'istanza dell'app in FCM. In genere, significa che il token utilizzato non è più valido e deve essere utilizzato uno nuovo. Questo errore può essere causato da token di registrazione mancanti o non registrati.
Registrazione mancante: se il valore di destinazione del messaggio è un valore token, verifica che la richiesta contenga un token di registrazione.
Non registrato: un token di registrazione esistente potrebbe non essere più valido in diversi scenari, tra cui:
- Se l'app client annulla la registrazione con FCM.
- Se l'app client non è registrata automaticamente, il che può accadere se l'utente disinstalla l'applicazione. Ad esempio, su iOS, se il servizio di feedback APNs ha segnalato il token APNs come non valido.
- Se il token di registrazione scade (ad esempio, Google potrebbe decidere di aggiornare i token di registrazione o se il token del servizio APN è scaduto per i dispositivi iOS).
- Se l'app client è aggiornata, ma la nuova versione non è configurata per ricevere messaggi.
Per tutti questi casi, rimuovi questo token di registrazione dal server dell'app e smetti di utilizzarlo per inviare messaggi.
SENDER_ID_MISMATCH (codice di errore HTTP = 403) L'ID mittente autenticato è diverso dall'ID mittente per il token di registrazione. Un token di registrazione è associato 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 per inviare messaggi all'app client. Se passi a un altro mittente, i token di registrazione esistenti non funzioneranno.
QUOTA_EXCEEDED (codice di 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 di frequenza di invio dei messaggi, della quota di frequenza di invio dei messaggi per dispositivo o della quota di frequenza di invio dei messaggi per argomento.
Frequenza di messaggi superata: la frequenza di invio dei messaggi è troppo elevata. ma devi ridurre la frequenza complessiva di invio dei messaggi. Utilizza il backoff esponenziale con un ritardo iniziale minimo di 1 minuto per riprovare i messaggi rifiutati.
Tasso di messaggi del dispositivo superato: la frequenza dei messaggi inviati a un determinato dispositivo è troppo elevata. Vedi Limite di frequenza dei messaggi per un singolo dispositivo. Riduci il numero di messaggi inviati a questo dispositivo e utilizza il backoff esponenziale per riprovare a inviare.
Percentuale di messaggi superata: la percentuale di messaggi inviati ai sottoscrittori di un determinato argomento è troppo elevata. Riduci il numero di messaggi inviati per questo argomento e utilizza il backoff esponenziale con un ritardo iniziale minimo di 1 minuto per riprovare a inviare.
UNAVAILABLE (codice di errore HTTP = 503) Il server è sovraccarico. Il server non è riuscito a elaborare la richiesta in tempo. Riprova a eseguire la stessa richiesta, ma devi:
- Rispettare l'intestazione Riprova se è inclusa nella risposta del server di connessione FCM.
- Implementa il backoff esponenziale nel meccanismo di nuovo tentativo. Ad esempio, se hai aspettato un secondo prima del primo tentativo, attendi almeno due secondi prima del successivo, poi 4 secondi e così via. Se invii più messaggi, valuta la possibilità di applicare il tremolio. Per saperne di più, consulta Gestione dei tentativi ripetuti. I mittenti che causano problemi rischiano di essere inseriti nella lista negativa.
INTERNAL (codice errore HTTP = 500) Si è verificato un errore interno sconosciuto. Il server ha riscontrato un errore durante il tentativo di elaborazione della richiesta. Puoi riprovare a inviare la stessa richiesta seguendo i suggerimenti riportati in Gestione delle ripetizioni. Se l'errore persiste, contatta l'assistenza Firebase.
THIRD_PARTY_AUTH_ERROR (codice di errore HTTP = 401) Il certificato APN o la chiave di autenticazione push web non è valido o non è presente. Impossibile inviare un messaggio indirizzato a un dispositivo iOS o una registrazione push web. Verifica la validità delle credenziali di sviluppo e produzione.

Codici di errore amministratore

La tabella seguente elenca i codici di errore dell'API FCM Firebase Admin e le relative descrizioni, inclusi i passaggi per la risoluzione consigliati.

Codice di errore Descrizione e passaggi per la 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 di FCM. Il limite è 4096 byte per la maggior parte dei messaggi. Per i messaggi inviati agli argomenti, il limite è di 2048 byte. La dimensione totale del payload include sia le chiavi che i valori.
messaging/invalid-options È stato fornito un oggetto di opzioni di messaggio non valido. Il messaggio di errore deve contenere informazioni aggiuntive.
messaging/invalid-registration-token Token di registrazione non valido fornito. Assicurati che corrisponda al token di registrazione ricevuto dall'app client dalla registrazione con FCM. Non troncare o aggiungere altri caratteri.
messaging/registration-token-not-registered Il token di registrazione fornito non è registrato. Un token di registrazione precedentemente valido può essere annullato per una serie di motivi, tra cui:
  • L'app client si è annullata la registrazione da FCM.
  • La registrazione dell'app client è stata automaticamente annullata. Ciò può accadere se l'utente disinstalla l'applicazione o, sulle piattaforme Apple, se il Servizio di feedback APNs ha segnalato il token APNs come non valido.
  • Il token di registrazione è scaduto. Ad esempio, Google potrebbe decidere di aggiornare i token di registrazione o il token APN potrebbe essere scaduto per i dispositivi Apple.
  • L'app client è stata aggiornata, ma la nuova versione non è configurata per ricevere messaggi.
Per tutti questi casi, rimuovi questo token di registrazione e smetti di utilizzarlo per inviare messaggi.
messaging/invalid-package-name Il messaggio è stato indirizzato a un token di registrazione il cui nome del pacchetto non corrisponde all'opzione restrictedPackageName fornita.
messaging/message-rate-exceeded La frequenza dei messaggi inviati a un particolare target è troppo elevata. Riduci il numero di messaggi inviati a questo dispositivo o argomento e non riprovare immediatamente a inviare a questo target.
messaging/device-message-rate-exceeded La frequenza dei messaggi inviati a un determinato dispositivo è troppo elevata. Riduci il numero di messaggi inviati a questo dispositivo e non riprovare immediatamente a inviare messaggi a questo dispositivo.
messaging/topics-message-rate-exceeded La frequenza dei messaggi inviati agli iscritti a un determinato argomento è troppo elevata. Riduci il numero di messaggi inviati per questo argomento e non riprovare immediatamente a eseguire l'invio a questo argomento.
messaging/too-many-topics Un token di registrazione è stato sottoscritto per il numero massimo di argomenti e non è possibile sottoscrivere altri abbonamenti.
messaging/invalid-apns-credentials Non è stato possibile inviare un messaggio che ha come target un dispositivo Apple perché il certificato SSL richiesto del servizio APN non è stato caricato o è scaduto. Verifica la validità dei certificati di sviluppo e produzione.
messaging/mismatched-credential La credenziale utilizzata per autenticare questo SDK non ha l'autorizzazione per inviare messaggi al dispositivo corrispondente al token di registrazione fornito. Assicurati che la credenziale e il token di registrazione appartengano allo stesso progetto Firebase. Consulta Aggiungere Firebase all'app per la documentazione su come autenticare i Firebase Admin SDK.
messaging/authentication-error L'SDK non è riuscito ad autenticarsi sui server FCM. Assicurati di autenticare Firebase Admin SDK con una credenziale che dispone delle autorizzazioni appropriate per inviare messaggi FCM. Consulta Aggiungi Firebase alla tua app per la documentazione su come autenticare i Firebase Admin SDK.
messaging/server-unavailable Il server FCM non è riuscito a elaborare la richiesta in tempo. Dovresti riprovare a inviare la stessa richiesta, ma devi:
  • Rispetta l'intestazione Retry-After se è inclusa nella risposta del server di connessione FCM.
  • Implementa il backoff esponenziale nel meccanismo di ripetizione. Ad esempio, se hai aspettato un secondo prima del primo tentativo, attendi almeno due secondi prima del successivo, poi quattro secondi e così via. Se invii più messaggi, ritardali singolarmente di un valore aggiuntivo casuale per evitare di emettere una nuova richiesta per tutti i messaggi contemporaneamente.
I mittenti che causano problemi rischiano di essere inseriti nella lista nera.
messaging/internal-error Il server FCM ha riscontrato un errore durante il tentativo di elaborazione della richiesta. Puoi riprovare a inviare la stessa richiesta rispettando i requisiti elencati nella riga messaging/server-unavailable sopra. Se l'errore persiste, segnala il problema al nostro canale di assistenza Bug Report.
messaging/unknown-error È stato restituito un errore del server sconosciuto. Per ulteriori dettagli, consulta la risposta non elaborata del server nel messaggio di errore. Se ricevi questo errore, segnala il messaggio di errore completo al nostro canale di assistenza per i bug report.

Inviare messaggi utilizzando i protocolli del server app precedente

Se al momento utilizzi i protocolli precedenti, crea le richieste di messaggio come mostrato in questa sezione. Tieni presente che, se invii su più piattaforme tramite HTTP, il protocollo v1 può semplificare notevolmente le richieste di messaggi.

Inviare messaggi a dispositivi specifici

Per inviare messaggi a dispositivi specifici, imposta la chiave to sul token di registrazione per l'istanza dell'app specifica. Per ulteriori informazioni sui token di registrazione, consulta le informazioni di configurazione del client per la tua piattaforma.

Richiesta 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..."
}

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. Consulta Formato della risposta del server.

Per l'elenco completo delle opzioni dei messaggi disponibili per l'invio di messaggi downstream alle app client, consulta le informazioni di riferimento per il protocollo del server di connessione scelto, HTTP o XMPP.

Inviare 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. L'app server imposta la chiave to con un valore simile a /topics/yourTopic. Gli sviluppatori possono scegliere qualsiasi nome argomento che corrisponda all'espressione regolare: "/topics/[a-zA-Z0-9-_.~%]+".

Per inviare a combinazioni di più argomenti, il server dell'app deve impostare la chiave condition (anziché la chiave to) su una condizione booleana che specifichi gli argomenti di destinazione. Ad esempio, per inviare messaggi a dispositivi con abbonamenti a TopicA e a TopicB o TopicC:

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

FCM valuta prima le eventuali condizioni tra parentesi e poi 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 si iscrive all'argomento A non riceve il messaggio. Sono le seguenti combinazioni:

  • ArgomentoA e ArgomentoB
  • Argomento A e Argomento C

Puoi includere fino a cinque argomenti nell'espressione condizionale e le parentesi sono supportate. Operatori supportati: &&, ||.

Richiesta POST HTTP per l'argomento

Inviare 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 relativo all'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 all'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 operazione riuscita o non riuscita alle richieste di invio dell'argomento. Assicurati di impostare di conseguenza il valore del timeout del server dell'app nella richiesta.

Inviare messaggi ai gruppi di dispositivi

L'invio di messaggi a un gruppo di dispositivi utilizzando le API legacy ritirate è molto simile all'invio di messaggi a un singolo dispositivo. Imposta il parametro to sulla chiave di notifica univoca per il gruppo di dispositivi. Gli esempi in questa sezione mostrano come inviare messaggi di dati ai gruppi di dispositivi nei protocolli HTTP e XMPP precedenti.

Richiesta POST HTTP per il 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": a notification_key sono associati due token di registrazione e il messaggio è stato inviato correttamente a entrambi: 

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

Ecco un esempio di "successo parziale": il valore notification_key è associato a 3 token di registrazione. Il messaggio è stato inviato correttamente solo a uno 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 di app deve riprovare con il backoff tra un nuovo tentativo e l'altro.

Se il server tenta di inviare un messaggio a un gruppo di dispositivi senza membri, la risposta è simile alla seguente, con 0 success e 0 failure: 

{
  "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 dei dispositivi del gruppo, il server di connessione XMPP risponde con un ACK. Se tutti i messaggi inviati a tutti i dispositivi del gruppo non vanno a buon fine, il server di connessione XMPP risponde con un NACK.

Ecco un esempio di "successo": a notification_key sono associati 3 token di registrazione e il messaggio è stato inviato correttamente a tutti e tre: 

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

Ecco un esempio di "successo parziale": il valore notification_key è associato a 3 token di registrazione. Il messaggio è stato inviato correttamente solo a uno 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 inviare il messaggio a tutti i dispositivi del gruppo. Il server dell'app riceverà una risposta nack.

Per l'elenco completo delle opzioni di messaggio, consulta le informazioni di riferimento per il protocollo del server di connessione scelto, HTTP o XMPP.

Firebase Admin SDK metodi di invio precedenti

L'SDK Firebase Admin Node.js supporta metodi per l'invio di messaggi (FCM) basati sull'API server FCM legacy. Questi metodi accettano argomenti diversi rispetto al metodo send(). Ti consigliamo di utilizzare il metodo send(), se possibile, e di utilizzare solo i metodi descritti in questa pagina per l'invio di 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 al 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 anziché 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 risolta con un oggetto MessagingDevicesResponse contenente la risposta di FCM. Il tipo di ritorno ha lo stesso formato quando viene passato un singolo token di registrazione o un array di token di registrazione.

In alcuni casi, ad esempio in caso di errore di autenticazione o limitazione della frequenza, l'elaborazione del messaggio non va a buon fine. In questi casi, la promessa restituita da sendToDevice() viene rifiutata con un errore. Per un elenco completo dei codici di errore, incluse descrizioni e procedure di risoluzione, consulta Errori dell'API FCM Amministrazione.

Inviare 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 da FCM.

In alcuni casi, ad esempio in caso di errore di autenticazione o limitazione della frequenza, l'elaborazione del messaggio non va a buon fine. In questi casi, la promessa restituita da sendToDeviceGroup() viene rifiutata con un errore. Per un elenco completo dei codici di errore, incluse descrizioni e procedure di risoluzione, consulta Errori dell'API FCM Amministrazione.

definisci il payload dei messaggi

I metodi precedenti basati sui protocolli legacy FCM accettano un payload del messaggio come secondo argomento e supportano sia i messaggi di notifica che quelli di dati. Puoi specificare uno o entrambi i tipi di messaggio creando un oggetto con le chiavi data e / o 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. Per un elenco completo, consulta la documentazione di riferimento di NotificationMessagePayload.

I payload dei messaggi di dati sono composti da coppie chiave-valore personalizzate con alcune limitazioni, tra cui il fatto che tutti i valori devono essere stringhe. Consulta la documentazione di riferimento di DataMessagePayload per un elenco completo delle limitazioni.

Definire le opzioni del messaggio

I metodi precedenti basati sui protocolli legacy FCM accettano un terzo argomento facoltativo che specifica alcune opzioni per il messaggio. Ad esempio, l'esempio seguente invia un messaggio con priorità elevata 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);
  });

Per un elenco completo delle opzioni disponibili, consulta la documentazione di riferimento di MessagingOptions.