Za pomocą pakietu SDK Firebase Admin lub protokołów serwera aplikacji FCM możesz tworzyć żądania wiadomości i wysyłać je do następujących typów celów:
- Nazwa tematu
- Warunek
- Token rejestracji urządzenia
- Nazwa grupy urządzeń (tylko protokół)
Możesz wysyłać wiadomości z ładunkiem powiadomień składającym się ze wstępnie zdefiniowanych pól, ładunkiem danych własnych pól zdefiniowanych przez użytkownika lub wiadomością zawierającą oba typy ładunków. Więcej informacji znajdziesz w sekcji Typy wiadomości.
Przykłady na tej stronie pokazują, jak wysyłać powiadomienia za pomocą pakietu SDK Firebase Admin (który obsługuje Node, Java, Python, C# i Go) oraz protokół HTTP v1. Możesz też korzystać z wytycznych dotyczących wysyłania wiadomości za pomocą wycofanych starszych protokołów HTTP i XMPP.
Wysyłanie wiadomości na określone urządzenia
Aby wysłać dane na pojedyncze, konkretne urządzenie, przekaż jego token rejestracji zgodnie z ilustracją. Aby dowiedzieć się więcej o tokenach rejestracji, zapoznaj się z informacjami na temat konfiguracji klienta dla Twojej platformy.
Node.js
// This registration token comes from the client FCM SDKs.
const registrationToken = 'YOUR_REGISTRATION_TOKEN';
const message = {
data: {
score: '850',
time: '2:45'
},
token: registrationToken
};
// Send a message to the device corresponding to the provided
// registration token.
getMessaging().send(message)
.then((response) => {
// Response is a message ID string.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Java
// This registration token comes from the client FCM SDKs.
String registrationToken = "YOUR_REGISTRATION_TOKEN";
// See documentation on defining a message payload.
Message message = Message.builder()
.putData("score", "850")
.putData("time", "2:45")
.setToken(registrationToken)
.build();
// Send a message to the device corresponding to the provided
// registration token.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
Python
# This registration token comes from the client FCM SDKs.
registration_token = 'YOUR_REGISTRATION_TOKEN'
# See documentation on defining a message payload.
message = messaging.Message(
data={
'score': '850',
'time': '2:45',
},
token=registration_token,
)
# Send a message to the device corresponding to the provided
# registration token.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
Go
// Obtain a messaging.Client from the App.
ctx := context.Background()
client, err := app.Messaging(ctx)
if err != nil {
log.Fatalf("error getting Messaging client: %v\n", err)
}
// This registration token comes from the client FCM SDKs.
registrationToken := "YOUR_REGISTRATION_TOKEN"
// See documentation on defining a message payload.
message := &messaging.Message{
Data: map[string]string{
"score": "850",
"time": "2:45",
},
Token: registrationToken,
}
// Send a message to the device corresponding to the provided
// registration token.
response, err := client.Send(ctx, message)
if err != nil {
log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)
C#
// This registration token comes from the client FCM SDKs.
var registrationToken = "YOUR_REGISTRATION_TOKEN";
// See documentation on defining a message payload.
var message = new Message()
{
Data = new Dictionary<string, string>()
{
{ "score", "850" },
{ "time", "2:45" },
},
Token = registrationToken,
};
// Send a message to the device corresponding to the provided
// registration token.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"notification":{
"body":"This is an FCM notification message!",
"title":"FCM Message"
}
}
}
Polecenie 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
Jeśli operacja się uda, każda metoda wysyłania zwróci identyfikator wiadomości. Pakiet Firebase Admin SDK zwraca ciąg identyfikatora w formacie projects/{project_id}/messages/{message_id}.
Odpowiedź protokołu HTTP to pojedynczy klucz JSON:
{
"name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
}
Wysyłanie wiadomości na wiele urządzeń
Admin FCM API umożliwiają łączenie wiadomości na listę tokenów rejestracji urządzeń. Możesz określić maksymalnie 500 tokenów rejestracji urządzeń na jedno wywołanie.
Node.js
// Create a list containing up to 500 registration tokens.
// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
'YOUR_REGISTRATION_TOKEN_1',
// …
'YOUR_REGISTRATION_TOKEN_N',
];
const message = {
data: {score: '850', time: '2:45'},
tokens: registrationTokens,
};
getMessaging().sendMulticast(message)
.then((response) => {
console.log(response.successCount + ' messages were sent successfully');
});
Java
// Create a list containing up to 500 registration tokens.
// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n"
);
MulticastMessage message = MulticastMessage.builder()
.putData("score", "850")
.putData("time", "2:45")
.addAllTokens(registrationTokens)
.build();
BatchResponse response = FirebaseMessaging.getInstance().sendMulticast(message);
// See the BatchResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " messages were sent successfully");
Python
# Create a list containing up to 500 registration tokens.
# These registration tokens come from the client FCM SDKs.
registration_tokens = [
'YOUR_REGISTRATION_TOKEN_1',
# ...
'YOUR_REGISTRATION_TOKEN_N',
]
message = messaging.MulticastMessage(
data={'score': '850', 'time': '2:45'},
tokens=registration_tokens,
)
response = messaging.send_multicast(message)
# See the BatchResponse reference documentation
# for the contents of response.
print('{0} messages were sent successfully'.format(response.success_count))
Go
// Create a list containing up to 500 registration tokens.
// This registration tokens come from the client FCM SDKs.
registrationTokens := []string{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
}
message := &messaging.MulticastMessage{
Data: map[string]string{
"score": "850",
"time": "2:45",
},
Tokens: registrationTokens,
}
br, err := client.SendMulticast(context.Background(), message)
if err != nil {
log.Fatalln(err)
}
// See the BatchResponse reference documentation
// for the contents of response.
fmt.Printf("%d messages were sent successfully\n", br.SuccessCount)
C#
// Create a list containing up to 500 registration tokens.
// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
};
var message = new MulticastMessage()
{
Tokens = registrationTokens,
Data = new Dictionary<string, string>()
{
{ "score", "850" },
{ "time", "2:45" },
},
};
var response = await FirebaseMessaging.DefaultInstance.SendEachForMulticastAsync(message);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");
Zwracana wartość to lista tokenów odpowiadająca kolejności tokenów wejściowych. Jest to przydatne, gdy chcesz sprawdzić, które tokeny spowodowały błędy.
Node.js
// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
'YOUR_REGISTRATION_TOKEN_1',
// …
'YOUR_REGISTRATION_TOKEN_N',
];
const message = {
data: {score: '850', time: '2:45'},
tokens: registrationTokens,
};
getMessaging().sendMulticast(message)
.then((response) => {
if (response.failureCount > 0) {
const failedTokens = [];
response.responses.forEach((resp, idx) => {
if (!resp.success) {
failedTokens.push(registrationTokens[idx]);
}
});
console.log('List of tokens that caused failures: ' + failedTokens);
}
});
Java
// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n"
);
MulticastMessage message = MulticastMessage.builder()
.putData("score", "850")
.putData("time", "2:45")
.addAllTokens(registrationTokens)
.build();
BatchResponse response = FirebaseMessaging.getInstance().sendMulticast(message);
if (response.getFailureCount() > 0) {
List<SendResponse> responses = response.getResponses();
List<String> failedTokens = new ArrayList<>();
for (int i = 0; i < responses.size(); i++) {
if (!responses.get(i).isSuccessful()) {
// The order of responses corresponds to the order of the registration tokens.
failedTokens.add(registrationTokens.get(i));
}
}
System.out.println("List of tokens that caused failures: " + failedTokens);
}
Python
# These registration tokens come from the client FCM SDKs.
registration_tokens = [
'YOUR_REGISTRATION_TOKEN_1',
# ...
'YOUR_REGISTRATION_TOKEN_N',
]
message = messaging.MulticastMessage(
data={'score': '850', 'time': '2:45'},
tokens=registration_tokens,
)
response = messaging.send_multicast(message)
if response.failure_count > 0:
responses = response.responses
failed_tokens = []
for idx, resp in enumerate(responses):
if not resp.success:
# The order of responses corresponds to the order of the registration tokens.
failed_tokens.append(registration_tokens[idx])
print('List of tokens that caused failures: {0}'.format(failed_tokens))
Go
// Create a list containing up to 500 registration tokens.
// This registration tokens come from the client FCM SDKs.
registrationTokens := []string{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
}
message := &messaging.MulticastMessage{
Data: map[string]string{
"score": "850",
"time": "2:45",
},
Tokens: registrationTokens,
}
br, err := client.SendMulticast(context.Background(), message)
if err != nil {
log.Fatalln(err)
}
if br.FailureCount > 0 {
var failedTokens []string
for idx, resp := range br.Responses {
if !resp.Success {
// The order of responses corresponds to the order of the registration tokens.
failedTokens = append(failedTokens, registrationTokens[idx])
}
}
fmt.Printf("List of tokens that caused failures: %v\n", failedTokens)
}
C#
// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
};
var message = new MulticastMessage()
{
Tokens = registrationTokens,
Data = new Dictionary<string, string>()
{
{ "score", "850" },
{ "time", "2:45" },
},
};
var response = await FirebaseMessaging.DefaultInstance.SendEachForMulticastAsync(message);
if (response.FailureCount > 0)
{
var failedTokens = new List<string>();
for (var i = 0; i < response.Responses.Count; i++)
{
if (!response.Responses[i].IsSuccess)
{
// The order of responses corresponds to the order of the registration tokens.
failedTokens.Add(registrationTokens[i]);
}
}
Console.WriteLine($"List of tokens that caused failures: {failedTokens}");
}
Wysyłanie wiadomości do tematów
Po utworzeniu tematu (przez zasubskrybowanie instancji aplikacji klienckich do tematu po stronie klienta lub za pomocą interfejsu API serwera) możesz wysyłać wiadomości do tego tematu. Jeśli po raz pierwszy tworzysz żądania wysyłania żądań w FCM, przeczytaj przewodnik na temat środowiska serwera i FCM, w którym znajdziesz ważne informacje o konfiguracji i konfiguracji.
W logice wysyłania w backendzie określ żądaną nazwę tematu w następujący sposób:
Node.js
// The topic name can be optionally prefixed with "/topics/".
const topic = 'highScores';
const message = {
data: {
score: '850',
time: '2:45'
},
topic: topic
};
// Send a message to devices subscribed to the provided topic.
getMessaging().send(message)
.then((response) => {
// Response is a message ID string.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Java
// The topic name can be optionally prefixed with "/topics/".
String topic = "highScores";
// See documentation on defining a message payload.
Message message = Message.builder()
.putData("score", "850")
.putData("time", "2:45")
.setTopic(topic)
.build();
// Send a message to the devices subscribed to the provided topic.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
Python
# The topic name can be optionally prefixed with "/topics/".
topic = 'highScores'
# See documentation on defining a message payload.
message = messaging.Message(
data={
'score': '850',
'time': '2:45',
},
topic=topic,
)
# Send a message to the devices subscribed to the provided topic.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
Go
// The topic name can be optionally prefixed with "/topics/".
topic := "highScores"
// See documentation on defining a message payload.
message := &messaging.Message{
Data: map[string]string{
"score": "850",
"time": "2:45",
},
Topic: topic,
}
// Send a message to the devices subscribed to the provided topic.
response, err := client.Send(ctx, message)
if err != nil {
log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)
C#
// The topic name can be optionally prefixed with "/topics/".
var topic = "highScores";
// See documentation on defining a message payload.
var message = new Message()
{
Data = new Dictionary<string, string>()
{
{ "score", "850" },
{ "time", "2:45" },
},
Topic = topic,
};
// Send a message to the devices subscribed to the provided topic.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"topic" : "foo-bar",
"notification" : {
"body" : "This is a Firebase Cloud Messaging Topic Message!",
"title" : "FCM Message"
}
}
}
Polecenie 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
Aby wysłać wiadomość do kombinacji tematów, określ warunek – wyrażenie logiczne określające tematy docelowe. Na przykład ten warunek spowoduje wysłanie wiadomości do urządzeń, które subskrybują TopicA i TopicB lub TopicC:
"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"
FCM najpierw ocenia warunki w nawiasach, a potem ocenia wyrażenie z kolei od lewej do prawej. W powyższym wyrażeniu użytkownik zasubskrybował
dowolny temat, ale nie otrzyma tej wiadomości. Analogicznie użytkownik, który nie subskrybuje TopicA, nie otrzyma wiadomości. Dane go otrzymują:
TopicAiTopicBTopicAiTopicC
W wyrażeniu warunkowym możesz uwzględnić maksymalnie 5 tematów.
Aby wysłać wiadomość do warunku:
Node.js
// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
const condition = '\'stock-GOOG\' in topics || \'industry-tech\' in topics';
// See documentation on defining a message payload.
const message = {
notification: {
title: '$FooCorp up 1.43% on the day',
body: '$FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
},
condition: condition
};
// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
getMessaging().send(message)
.then((response) => {
// Response is a message ID string.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Java
// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
String condition = "'stock-GOOG' in topics || 'industry-tech' in topics";
// See documentation on defining a message payload.
Message message = Message.builder()
.setNotification(Notification.builder()
.setTitle("$GOOG up 1.43% on the day")
.setBody("$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.")
.build())
.setCondition(condition)
.build();
// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
Python
# Define a condition which will send to devices which are subscribed
# to either the Google stock or the tech industry topics.
condition = "'stock-GOOG' in topics || 'industry-tech' in topics"
# See documentation on defining a message payload.
message = messaging.Message(
notification=messaging.Notification(
title='$GOOG up 1.43% on the day',
body='$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
),
condition=condition,
)
# Send a message to devices subscribed to the combination of topics
# specified by the provided condition.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
Go
// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
condition := "'stock-GOOG' in topics || 'industry-tech' in topics"
// See documentation on defining a message payload.
message := &messaging.Message{
Data: map[string]string{
"score": "850",
"time": "2:45",
},
Condition: condition,
}
// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
response, err := client.Send(ctx, message)
if err != nil {
log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)
C#
// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
var condition = "'stock-GOOG' in topics || 'industry-tech' in topics";
// See documentation on defining a message payload.
var message = new Message()
{
Notification = new Notification()
{
Title = "$GOOG up 1.43% on the day",
Body = "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
},
Condition = condition,
};
// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"condition": "'dogs' in topics || 'cats' in topics",
"notification" : {
"body" : "This is a Firebase Cloud Messaging Topic Message!",
"title" : "FCM Message",
}
}
}
Polecenie 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
Wysyłanie wiadomości do grup urządzeń
Aby wysyłać wiadomości do grup urządzeń, użyj interfejsu API HTTP v1. Jeśli obecnie wysyłasz wiadomości do grup urządzeń za pomocą wycofanych starszych interfejsów API do wysyłania obsługujących HTTP lub XMPP albo dowolnej starszej wersji pakietu SDK Firebase Admin SDK dla Node.js opartego na starszych protokołach, zdecydowanie zalecamy jak najszybsze przejście na interfejs HTTP v1 API. Starsze interfejsy API do wysyłania zostaną wyłączone i usunięte w czerwcu 2024 r.
Wysyłanie wiadomości do grupy urządzeń bardzo przypomina wysyłanie wiadomości na pojedyncze urządzenia – w ten sam sposób autoryzujesz żądania wysłania. Ustaw pole token na klucz powiadomień grupy:
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!"
}
}
}
Polecenie 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
Wysyłanie grupy wiadomości
Pakiety Admin SDK obsługują wysyłanie wiadomości partiami. Możesz zgrupować do 500 wiadomości w jedną grupę i wysłać je wszystkie w jednym wywołaniu interfejsu API. Pozwala to znacznie zwiększyć wydajność w porównaniu z wysyłaniem osobnych żądań HTTP do każdej wiadomości.
Ta funkcja może służyć do tworzenia niestandardowego zestawu wiadomości i wysyłania ich do różnych odbiorców, w tym tematów lub konkretnych tokenów rejestracji urządzenia. Używaj tej funkcji, gdy chcesz np. wysyłać jednocześnie wiadomości do różnych odbiorców z nieco różniącymi się szczegółami w treści wiadomości.
Node.js
// Create a list containing up to 500 messages.
const messages = [];
messages.push({
notification: { title: 'Price drop', body: '5% off all electronics' },
token: registrationToken,
});
messages.push({
notification: { title: 'Price drop', body: '2% off all books' },
topic: 'readers-club',
});
getMessaging().sendAll(messages)
.then((response) => {
console.log(response.successCount + ' messages were sent successfully');
});
Java
// Create a list containing up to 500 messages.
List<Message> messages = Arrays.asList(
Message.builder()
.setNotification(Notification.builder()
.setTitle("Price drop")
.setBody("5% off all electronics")
.build())
.setToken(registrationToken)
.build(),
// ...
Message.builder()
.setNotification(Notification.builder()
.setTitle("Price drop")
.setBody("2% off all books")
.build())
.setTopic("readers-club")
.build()
);
BatchResponse response = FirebaseMessaging.getInstance().sendAll(messages);
// See the BatchResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " messages were sent successfully");
Python
# Create a list containing up to 500 messages.
messages = [
messaging.Message(
notification=messaging.Notification('Price drop', '5% off all electronics'),
token=registration_token,
),
# ...
messaging.Message(
notification=messaging.Notification('Price drop', '2% off all books'),
topic='readers-club',
),
]
response = messaging.send_all(messages)
# See the BatchResponse reference documentation
# for the contents of response.
print('{0} messages were sent successfully'.format(response.success_count))
Go
// Create a list containing up to 500 messages.
messages := []*messaging.Message{
{
Notification: &messaging.Notification{
Title: "Price drop",
Body: "5% off all electronics",
},
Token: registrationToken,
},
{
Notification: &messaging.Notification{
Title: "Price drop",
Body: "2% off all books",
},
Topic: "readers-club",
},
}
br, err := client.SendAll(context.Background(), messages)
if err != nil {
log.Fatalln(err)
}
// See the BatchResponse reference documentation
// for the contents of response.
fmt.Printf("%d messages were sent successfully\n", br.SuccessCount)
C#
// Create a list containing up to 500 messages.
var messages = new List<Message>()
{
new Message()
{
Notification = new Notification()
{
Title = "Price drop",
Body = "5% off all electronics",
},
Token = registrationToken,
},
new Message()
{
Notification = new Notification()
{
Title = "Price drop",
Body = "2% off all books",
},
Topic = "readers-club",
},
};
var response = await FirebaseMessaging.DefaultInstance.SendEachAsync(messages);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");
Wysyłanie wiadomości z włączonym rozruchem bezpośrednim (tylko Android)
Możesz wysyłać komunikaty do urządzeń w trybie rozruchu bezpośredniego, korzystając z HTTP w wersji 1 lub starszych interfejsów API HTTP. Zanim zaczniesz wysyłać wiadomości na urządzenia w trybie rozruchu bezpośredniego, wykonaj odpowiednie czynności, aby umożliwić urządzeniom klienckim odbieranie wiadomości FCM w trybie rozruchu bezpośredniego.
Wysyłanie za pomocą interfejsu API HTTP FCM w wersji 1
Żądanie dotyczące wiadomości musi zawierać klucz "direct_boot_ok" : true w opcjach AndroidConfig treści żądania. Przykład:
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,
},
}
Wysyłanie przez starszy interfejs HTTP API FCM
Żądanie dotyczące wiadomości musi zawierać klucz "direct_boot_ok" : true na najwyższym poziomie treści żądania. Przykład:
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
}
Wiadomości wysłane za pomocą tego klucza w treści żądania mogą być obsługiwane przez aplikacje na urządzeniach, które obecnie są w trybie bezpośredniego uruchamiania (oraz gdy nie są w tym trybie).
Dostosowywanie wiadomości na różnych platformach
Zarówno pakiet SDK Firebase Admin, jak i protokół HTTP FCM v1 pozwalają w żądaniu wiadomości ustawić wszystkie pola dostępne w obiekcie message. Obejmuje to:
- wspólny zbiór pól do interpretowania przez wszystkie instancje aplikacji, które otrzymały wiadomość.
- Zbiory pól związane z konkretną platformą, takie jak
AndroidConfigiWebpushConfig, interpretowane tylko przez instancje aplikacji działające na określonej platformie.
Blokady związane z określoną platformą umożliwiają elastyczne dostosowywanie wiadomości przeznaczonych dla różnych platform, aby zapewnić ich prawidłową obsługę po otrzymaniu. Backend FCM weźmie pod uwagę wszystkie określone parametry i dostosuje wiadomość dla każdej platformy.
Kiedy używać wspólnych pól
Używaj często używanych pól, gdy:
- kierowanie na instancje aplikacji na wszystkich platformach – Apple, Android i w internecie;
- Wysyłanie wiadomości do tematów
Wszystkie instancje aplikacji, niezależnie od platformy, mogą interpretować te typowe pola:
Kiedy używać pól zależnie od platformy
Użyj pól związanych z daną platformą, jeśli chcesz:
- Wysyłaj pola tylko na określone platformy
- Wysyłaj pola związane z poszczególnymi platformami oprócz wspólnych pól.
Jeśli chcesz wysyłać wartości tylko do określonych platform, nie używaj wspólnych pól. Stosuj pola związane z daną platformą. Aby np. wysłać powiadomienie tylko na platformy Apple i strony internetowe, ale nie na Androida, musisz użyć 2 osobnych zestawów pól – jednego dla Apple i jednego dla stron internetowych.
Gdy wysyłasz wiadomości z określonymi opcjami dostarczania, skorzystaj z pól właściwych na danej platformie, aby skonfigurować te opcje. Jeśli chcesz, możesz podać różne wartości dla poszczególnych platform. Jeśli jednak chcesz ustawić zasadniczo tę samą wartość na różnych platformach, musisz użyć pól związanych z daną platformą. Wynika to z faktu, że każda platforma może interpretować tę wartość nieco inaczej, np. na Androidzie jest to czas ważności w sekundach, a w Apple – data.
Przykład: wiadomość powiadomienia z opcjami koloru i ikon
To przykładowe żądanie wysyłania zawiera wspólny tytuł powiadomienia i jego treść do wszystkich platform, ale powoduje też wysłanie niektórych zastąpień związanych z daną platformą na urządzenia z Androidem.
W przypadku Androida żądanie ustawia specjalną ikonę i kolor, które będą wyświetlane na urządzeniach z Androidem. Jak wspomnieliśmy w pliku referencyjnym dla Android Notification, kolor jest określony w formacie #rrggbb, a obraz musi być rysowalnym zasobem ikony wyświetlanej lokalnie w aplikacji na Androida.
Oto przybliżony efekt wizualny na urządzeniu użytkownika:
Node.js
const topicName = 'industry-tech';
const message = {
notification: {
title: '`$FooCorp` up 1.43% on the day',
body: 'FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
},
android: {
notification: {
icon: 'stock_ticker_update',
color: '#7e55c3'
}
},
topic: topicName,
};
getMessaging().send(message)
.then((response) => {
// Response is a message ID string.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Java
Message message = Message.builder()
.setNotification(Notification.builder()
.setTitle("$GOOG up 1.43% on the day")
.setBody("$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.")
.build())
.setAndroidConfig(AndroidConfig.builder()
.setTtl(3600 * 1000)
.setNotification(AndroidNotification.builder()
.setIcon("stock_ticker_update")
.setColor("#f45342")
.build())
.build())
.setApnsConfig(ApnsConfig.builder()
.setAps(Aps.builder()
.setBadge(42)
.build())
.build())
.setTopic("industry-tech")
.build();
Python
message = messaging.Message(
notification=messaging.Notification(
title='$GOOG up 1.43% on the day',
body='$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
),
android=messaging.AndroidConfig(
ttl=datetime.timedelta(seconds=3600),
priority='normal',
notification=messaging.AndroidNotification(
icon='stock_ticker_update',
color='#f45342'
),
),
apns=messaging.APNSConfig(
payload=messaging.APNSPayload(
aps=messaging.Aps(badge=42),
),
),
topic='industry-tech',
)
Go
oneHour := time.Duration(1) * time.Hour
badge := 42
message := &messaging.Message{
Notification: &messaging.Notification{
Title: "$GOOG up 1.43% on the day",
Body: "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
},
Android: &messaging.AndroidConfig{
TTL: &oneHour,
Notification: &messaging.AndroidNotification{
Icon: "stock_ticker_update",
Color: "#f45342",
},
},
APNS: &messaging.APNSConfig{
Payload: &messaging.APNSPayload{
Aps: &messaging.Aps{
Badge: &badge,
},
},
},
Topic: "industry-tech",
}
C#
var message = new Message
{
Notification = new Notification()
{
Title = "$GOOG up 1.43% on the day",
Body = "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
},
Android = new AndroidConfig()
{
TimeToLive = TimeSpan.FromHours(1),
Notification = new AndroidNotification()
{
Icon = "stock_ticker_update",
Color = "#f45342",
},
},
Apns = new ApnsConfig()
{
Aps = new Aps()
{
Badge = 42,
},
},
Topic = "industry-tech",
};
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"topic":"industry-tech",
"notification":{
"title":"`$FooCorp` up 1.43% on the day",
"body":"FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day."
},
"android":{
"notification":{
"icon":"stock_ticker_update",
"color":"#7e55c3"
}
}
}
}
Więcej informacji o kluczach dostępnych w blokach na poszczególnych platformach w treści wiadomości znajdziesz w dokumentacji protokołu HTTP w wersji 1.
Przykład: wiadomość z powiadomieniem z niestandardowym obrazem
Poniższy przykład wysyłania żądania wysyłania wysyła wspólny tytuł powiadomienia do wszystkich platform, ale wysyła też obraz. Oto w przybliżeniu efekt wizualny na urządzenie użytkownika:
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"
}
}
}
}
Więcej informacji o kluczach dostępnych w blokach na poszczególnych platformach w treści wiadomości znajdziesz w dokumentacji protokołu HTTP w wersji 1.
Przykład: wiadomość z powiązanym działaniem kliknięcia
Ten przykładowy kod wysyłania wysyła wspólny tytuł powiadomienia do wszystkich platform, ale wysyła też działanie, które aplikacja ma wykonać w odpowiedzi na interakcję użytkownika z powiadomieniem. Oto przybliżony efekt wizualny na urządzeniu użytkownika:
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"
}
}
}
}
Więcej informacji o kluczach dostępnych w blokach na poszczególnych platformach w treści wiadomości znajdziesz w dokumentacji protokołu HTTP w wersji 1.
Przykład: powiadomienie z opcjami lokalizacji
Poniższy przykładowy kod żądania wysyła opcje lokalizacji, aby umożliwić klientowi wyświetlanie zlokalizowanych wiadomości. Oto przybliżony efekt wizualny na urządzeniu użytkownika:
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"],
},
},
},
},
},
}'
Więcej informacji o kluczach dostępnych w blokach na poszczególnych platformach w treści wiadomości znajdziesz w dokumentacji protokołu HTTP w wersji 1.
Kody błędów REST dla interfejsu API HTTP w wersji 1
Odpowiedzi na błędy HTTP w przypadku interfejsu API HTTP w wersji 1 zawierają kod błędu, komunikat o błędzie i stan błędu.
Mogą też zawierać tablicę details z dodatkowymi informacjami o błędzie.
Oto 2 przykładowe odpowiedzi na błędy:
Przykład 1. Odpowiedź o błędzie na żądanie interfejsu API HTTP w wersji 1 z nieprawidłową wartością w wiadomości z danymi
{
"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"
}
]
}
]
}
}
Przykład 2. Odpowiedź o błędzie przesłana na żądanie interfejsu API HTTP w wersji 1 z nieprawidłowym tokenem rejestracji
{
"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"
}
]
}
}
Pamiętaj, że oba komunikaty mają ten sam kod i stan, ale tablica szczegółów zawiera wartości w różnych typach. W pierwszym przykładzie typ type.googleapis.com/google.rpc.BadRequest wskazuje na błąd w wartościach żądań. W drugim przykładzie typu type.googleapis.com/google.firebase.fcm.v1.FcmError występuje błąd związany z FCM. W przypadku wielu błędów tablica szczegółów zawiera informacje, które trzeba debugować i znaleźć rozwiązanie.
W tabeli poniżej znajdziesz kody błędów interfejsu API REST FCM w wersji 1 oraz ich opisy.
| Kod błędu | Opis i sposoby rozwiązania problemu |
|---|---|
UNSPECIFIED_ERROR Nie ma więcej informacji o tym błędzie. |
Brak. |
INVALID_ARGUMENT (kod błędu HTTP = 400) Nieprawidłowe parametry żądania. Zwracane jest rozszerzenie typu google.rpc.BadRequest, które wskazuje, które pole było nieprawidłowe. |
Potencjalne przyczyny obejmują nieprawidłową rejestrację, nieprawidłową nazwę pakietu, zbyt duży komunikat, nieprawidłowy klucz danych, nieprawidłowy czas TTL lub inne nieprawidłowe parametry. Nieprawidłowa rejestracja: sprawdź format tokena rejestracji przekazywanego do serwera. Upewnij się, że jest on zgodny z tokenem rejestracji, który aplikacja kliencka otrzymuje w związku z rejestracją w FCM. Nie obcinaj tokena ani nie dodawaj dodatkowych znaków. Nieprawidłowa nazwa pakietu: sprawdź, czy wiadomość została zaadresowana na token rejestracji, którego nazwa pakietu odpowiada wartości przekazanej w żądaniu. Wiadomość jest za duża: sprawdź, czy łączny rozmiar danych ładunku zawartych w wiadomości nie przekracza limitów FCM: 4096 bajtów w przypadku większości wiadomości lub 2048 bajtów w przypadku wiadomości wysyłanych do tematów. Obejmuje to zarówno klucze, jak i wartości. Nieprawidłowy klucz danych: sprawdź, czy dane ładunku nie zawierają klucza (np. from, gcm lub innej wartości poprzedzonej przez Google), który jest używany wewnętrznie przez FCM. Pamiętaj, że niektóre słowa (np. Zwiń_key) są też używane przez FCM, ale są dozwolone w ładunku. W takim przypadku wartość ładunku zostanie zastąpiona wartością FCM. Nieprawidłowa wartość TTL: sprawdź, czy wartość używana w ttl jest liczbą całkowitą określającą czas trwania w sekundach z zakresu od 0 do 2 419 200 (4 tygodnie). Nieprawidłowe parametry: sprawdź, czy podane parametry mają prawidłową nazwę i typ. |
UNREGISTERED (kod błędu HTTP = 404) instancja aplikacji została wyrejestrowana z FCM. Zwykle oznacza to, że użyty token utracił ważność i należy użyć nowego. |
Ten błąd może być spowodowany brakiem tokenów rejestracji lub niezarejestrowanych tokenów. Brak rejestracji: jeśli celem wiadomości jest wartość token, sprawdź, czy żądanie zawiera token rejestracji.Niezarejestrowany: istniejący token rejestracji może przestać być ważny w różnych sytuacjach, między innymi: – wyrejestrowaniu się aplikacji klienckiej z FCM; – jeśli aplikacja kliencka zostanie automatycznie wyrejestrowana, co może mieć miejsce, gdy użytkownik ją odinstaluje; Na przykład na urządzeniu z iOS, jeśli usługa opinii o punktach APN zgłosiła token APNs jako nieprawidłowy. – gdy token rejestracji wygaśnie (na przykład Google może odświeżyć tokeny rejestracji lub token APNs wygasł w przypadku urządzeń z iOS). – Jeśli aplikacja kliencka jest zaktualizowana, ale nowa wersja nie jest skonfigurowana do odbierania wiadomości. We wszystkich tych przypadkach usuń token rejestracji z serwera aplikacji i przestań go używać do wysyłania wiadomości. |
SENDER_ID_MISMATCH (kod błędu HTTP = 403) Uwierzytelniony identyfikator nadawcy różni się od identyfikatora nadawcy przypisanego do tokena rejestracji. |
Token rejestracji jest powiązany z określoną grupą nadawców. Gdy aplikacja kliencka rejestruje się w FCM, musi określać, którzy nadawcy mogą wysyłać wiadomości. Podczas wysyłania wiadomości do aplikacji klienckiej należy użyć jednego z tych identyfikatorów nadawcy. Jeśli zmienisz nadawcę, istniejące tokeny rejestracji nie będą działać. |
QUOTA_EXCEEDED (kod błędu HTTP = 429) Przekroczono limit wysyłania w celu wiadomości. Zwracane jest rozszerzenie typu google.rpc.QuotaFailure, które wskazuje, który limit został przekroczony. |
Ten błąd może być spowodowany przekroczeniem limitu liczby wiadomości, przekroczeniem limitu liczby wiadomości na urządzeniu lub przekroczeniem limitu liczby wiadomości w temacie. Przekroczona częstotliwość wysyłania wiadomości: częstotliwość wysyłania wiadomości jest za duża. Musisz zmniejszyć ogólną częstotliwość wysyłania wiadomości. Do ponawiania odrzuconych wiadomości używaj wykładniczego ponowienia z minimalnym początkowym opóźnieniem wynoszącym 1 minutę. Przekroczono limit wiadomości na urządzeniu: liczba wiadomości wysyłanych do danego urządzenia jest za wysoki. Zobacz ograniczenie liczby wiadomości na jednym urządzeniu. Zmniejsz liczbę wiadomości wysyłanych na to urządzenie i użyj wykładniczego ponowienia, aby ponowić próbę wysłania. Przekroczono liczbę wiadomości dotyczących danego tematu: liczba wiadomości wysyłanych do subskrybentów danego tematu jest zbyt wysoki. Zmniejsz liczbę wiadomości wysyłanych w tym temacie i użyj wykładniczego ponowienia z minimalnym początkowym opóźnieniem wynoszącym 1 minutę, aby ponowić próbę wysłania. |
UNAVAILABLE (kod błędu HTTP = 503) Serwer jest przeciążony. |
Serwer nie mógł przetworzyć żądania na czas. Ponów to samo żądanie, ale musisz: – uwzględnić nagłówek Retry-After, jeśli znajduje się on w odpowiedzi z serwera połączenia FCM; – Zaimplementuj wykładnicze ponawianie w mechanizmie ponawiania prób. Jeśli np. pierwsza próba powtarzała się w 1 sekundę, poczekaj co najmniej 2 sekundy przed następną, a następnie 4 sekundy itd. Jeśli wysyłasz wiele wiadomości, rozważ zastosowanie zakłóceń. Więcej informacji znajdziesz w sekcji na temat ponawiania prób. Nadawca, który powoduje problemy, może zostać zablokowany. |
INTERNAL (kod błędu HTTP = 500) Wystąpił nieznany błąd wewnętrzny. |
Podczas próby przetworzenia żądania serwer napotkał błąd. Możesz spróbować jeszcze raz przesłać to samo żądanie, postępując zgodnie z sugestiami w artykule Obsługa ponownych prób. Jeśli błąd będzie się powtarzał, skontaktuj się z zespołem pomocy Firebase. |
THIRD_PARTY_AUTH_ERROR (kod błędu HTTP = 401) – brak certyfikatu APNs lub klucza uwierzytelniania Web push. |
Nie udało się wysłać wiadomości kierowanej na urządzenie z iOS lub rejestracji push w internecie. Sprawdź poprawność swoich danych logowania do programowania i wersji produkcyjnej. |
Kody błędów administratora
W tabeli poniżej znajdziesz kody błędów interfejsu Firebase Admin FCM API i ich opisy, w tym zalecane czynności, które należy wykonać.
| Kod błędu | Opis i sposoby rozwiązania problemu |
|---|---|
messaging/invalid-argument |
Podano nieprawidłowy argument metody FCM. Komunikat o błędzie powinien zawierać dodatkowe informacje. |
messaging/invalid-recipient |
Docelowy odbiorca wiadomości jest nieprawidłowy. Komunikat o błędzie powinien zawierać dodatkowe informacje. |
messaging/invalid-payload |
Podano nieprawidłowy obiekt ładunku wiadomości. Komunikat o błędzie powinien zawierać dodatkowe informacje. |
messaging/invalid-data-payload-key |
Ładunek wiadomości z danymi zawiera nieprawidłowy klucz. Informacje o kluczach z ograniczeniami znajdziesz w dokumentacji
DataMessagePayload.
|
messaging/payload-size-limit-exceeded |
Podany ładunek wiadomości przekracza limity rozmiaru FCM. W przypadku większości wiadomości limit wynosi 4096 bajtów. W przypadku wiadomości wysyłanych do tematów limit wynosi 2048 bajtów. Łączny rozmiar ładunku obejmuje zarówno klucze, jak i wartości. |
messaging/invalid-options |
Podano nieprawidłowy obiekt opcji wiadomości. Komunikat o błędzie powinien zawierać dodatkowe informacje. |
messaging/invalid-registration-token |
Podano nieprawidłowy token rejestracji. Upewnij się, że jest zgodny z tokenem rejestracji, który aplikacja kliencka otrzymuje w wyniku rejestracji w FCM. Nie skracaj tekstu ani nie dodawaj do niego dodatkowych znaków. |
messaging/registration-token-not-registered |
Podany token rejestracji nie jest zarejestrowany. Wcześniej prawidłowy token rejestracji może zostać wyrejestrowany z różnych powodów, takich jak:
|
messaging/invalid-package-name |
Wiadomość została zaadresowana na token rejestracji, którego nazwa pakietu nie zgadza się z podaną opcją
restrictedPackageName.
|
messaging/message-rate-exceeded |
Częstotliwość wiadomości wysyłanych do określonego miejsca docelowego jest zbyt duża. Zmniejsz liczbę wiadomości wysyłanych na to urządzenie lub na ten temat i nie próbuj od razu ponownie wysyłać ich do tego miejsca docelowego. |
messaging/device-message-rate-exceeded |
Ilość wiadomości wysyłanych do danego urządzenia jest zbyt duża. Zmniejsz liczbę wiadomości wysyłanych na to urządzenie i nie próbuj od razu wysyłać na nie ponownie. |
messaging/topics-message-rate-exceeded |
Współczynnik wiadomości do subskrybentów danego tematu jest zbyt wysoki. Zmniejsz liczbę wiadomości wysyłanych w tym temacie i nie próbuj od razu ponownie wysyłać wiadomości do tego tematu. |
messaging/too-many-topics |
Token rejestracji został zasubskrybowany do maksymalnej liczby tematów i nie można go już subskrybować. |
messaging/invalid-apns-credentials |
Nie udało się wysłać wiadomości kierowanej na urządzenie Apple, ponieważ wymagany certyfikat SSL APNs nie został przesłany lub wygasł. Sprawdź poprawność certyfikatów programistycznych i produkcyjnych. |
messaging/mismatched-credential |
Dane logowania używane do uwierzytelniania tego pakietu SDK nie mają uprawnień do wysyłania komunikatów do urządzenia odpowiadającego podanemu tokenowi rejestracji. Upewnij się, że dane logowania i token rejestracji należą do tego samego projektu Firebase. Dokumentacja uwierzytelniania pakietów SDK Firebase Admin SDK znajdziesz w artykule Dodawanie Firebase do aplikacji. |
messaging/authentication-error |
Pakiet SDK nie mógł uwierzytelnić się na serwerach FCM. Pamiętaj, aby uwierzytelnić pakiet Firebase Admin SDK za pomocą danych logowania z odpowiednimi uprawnieniami do wysyłania wiadomości do FCM. Dokumentacja uwierzytelniania pakietów SDK Firebase Admin SDK znajdziesz w artykule Dodawanie Firebase do aplikacji. |
messaging/server-unavailable |
Serwer FCM nie mógł przetworzyć żądania na czas. Wykonaj to samo żądanie jeszcze raz, ale musisz:
|
messaging/internal-error |
Podczas próby przetworzenia żądania serwer FCM napotkał błąd. Możesz ponownie przesłać tę samą prośbę, postępując zgodnie z wymaganiami wymienionymi powyżej w wierszu messaging/server-unavailable. Jeśli błąd będzie się powtarzał, zgłoś go do naszego zespołu pomocy ds. raportu o błędzie.
|
messaging/unknown-error |
Zwrócono nieznany błąd serwera. Więcej informacji znajdziesz w nieprzetworzonej odpowiedzi serwera w komunikacie o błędzie. Jeśli pojawi się ten błąd, zgłoś pełny komunikat o błędzie do naszego kanału pomocy ds. raportu o błędzie. |
Wysyłanie wiadomości przy użyciu starszych protokołów serwera aplikacji
Jeśli obecnie używasz starszych protokołów, utwórz żądania wiadomości w sposób pokazany w tej sekcji. Jeśli wysyłasz wiadomości na wiele platform za pomocą protokołu HTTP, protokół v1 może znacznie uprościć żądania wiadomości.
Wysyłanie wiadomości na określone urządzenia
Aby wysyłać wiadomości na określone urządzenia, ustaw klucz to na token rejestracji danej instancji aplikacji. Aby dowiedzieć się więcej o tokenach rejestracji, zapoznaj się z informacjami o konfiguracji klienta dla Twojej platformy.
Żądanie 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..."
}
odpowiedź HTTP
{ "multicast_id": 108,
"success": 1,
"failure": 0,
"results": [
{ "message_id": "1:08" }
]
}
Komunikat XMPP
<message id="">
<gcm xmlns="google:mobile:data">
{ "data": {
"score": "5x1",
"time": "15:10"
},
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}
</gcm>
</message>
Odpowiedź XMPP
<message id="">
<gcm xmlns="google:mobile:data">
{
"from":"REGID",
"message_id":"m-1366082849205"
"message_type":"ack"
}
</gcm>
</message>
Serwer połączenia XMPP udostępnia inne opcje odpowiedzi. Zobacz Format odpowiedzi serwera.
Pełną listę opcji wyświetlania wiadomości dostępnych podczas wysyłania wiadomości do aplikacji klienckich znajdziesz w dokumentacji wybranego protokołu serwera połączenia – HTTP lub XMPP.
Wysyłanie wiadomości do tematów
Wysyłanie wiadomości do tematu Komunikacji w chmurze Firebase (FCM) jest bardzo podobne do wysyłania wiadomości na pojedyncze urządzenia lub do grupy użytkowników. Serwer aplikacji ustawia klucz to o wartości np. /topics/yourTopic.
Deweloperzy mogą wybrać dowolną nazwę tematu pasującą do wyrażenia regularnego: "/topics/[a-zA-Z0-9-_.~%]+".
Aby możliwe było wysyłanie wiadomości do kombinacji tematów, serwer aplikacji musi ustawić klucz condition (zamiast klucza to) na warunek logiczny, który określa tematy docelowe. Aby na przykład wysłać wiadomości na urządzenia, które subskrybują TopicA i TopicB lub TopicC:
'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)
FCM najpierw ocenia warunki w nawiasach, a potem ocenia wyrażenie z kolejności od lewej do prawej. W powyższym wyrażeniu użytkownik zasubskrybował dowolny temat nie otrzyma tej wiadomości. Analogicznie użytkownik, który nie subskrybuje TopicA, nie otrzyma wiadomości. Jest to możliwe w przypadku tych kombinacji:
- TematA i TematB
- TematA i TematC
W wyrażeniu warunkowym możesz uwzględnić do 5 tematów (obsługiwane są nawiasy).
Obsługiwane operatory: &&, ||.
Żądanie HTTP POST tematu
Wysyłanie do jednego tematu:
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
Wysyłanie na urządzenia subskrybujące tematy „psy” lub „koty”:
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
Odpowiedź HTTP tematu
// Success example:
{
"message_id": "1023456"
}
// failure example:
{
"error": "TopicsMessageRateExceeded"
}
Komunikat XMPP tematu
Wysyłanie do jednego tematu:
<message id="">
<gcm xmlns="google:mobile:data">
</gcm>
</message>
Wysyłanie na urządzenia subskrybujące tematy „psy” lub „koty”:
<message id=""> <gcm xmlns="google:mobile:data"> </gcm> </message>
Odpowiedź XMPP w temacie
// Success example:
{
"message_id": "1023456"
}
// failure example:
{
"error": "TopicsMessageRateExceeded"
}
Zanim serwer FCM zwróci odpowiedź udaną lub nieudaną w odpowiedzi na żądania wysłane w temacie, może minąć do 30 sekund. Pamiętaj, aby w żądaniu ustawić odpowiednią wartość limitu czasu serwera aplikacji.
Wysyłanie wiadomości do grup urządzeń
Wysyłanie wiadomości do grupy urządzeń za pomocą wycofanych starszych interfejsów API jest bardzo podobne do wysyłania wiadomości na pojedyncze urządzenia. Ustaw parametr to na unikalny klucz powiadomień dla grupy urządzeń.
W tej sekcji znajdziesz przykłady, jak wysyłać komunikaty z danymi do grup urządzeń w starszych protokołach HTTP i XMPP.
Żądanie HTTP POST grupy urządzeń
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!",
}
}
Odpowiedź HTTP grupy urządzeń
Oto przykład powodzenia – z notification_key są powiązane 2 tokeny rejestracji i do obu z nich została wysłana wiadomość:
{
"success": 2,
"failure": 0
}
Oto przykład „częściowego sukcesu” – z notification_key są powiązane 3 tokeny rejestracji. Wiadomość została wysłana tylko do 1 tokena rejestracji. Komunikat w odpowiedzi zawiera listę tokenów rejestracji (registration_ids), które nie odebrały wiadomości:
{
"success":1,
"failure":2,
"failed_registration_ids":[
"regId1",
"regId2"
]
}
Jeśli nie uda się dostarczyć wiadomości na co najmniej jeden token rejestracji powiązany z notification_key, serwer aplikacji powinien ponawiać próby dostarczenia po kolejnych próbach.
Jeśli serwer próbuje wysłać wiadomość do grupy urządzeń, która nie ma użytkowników, odpowiedź wygląda tak (0 sukcesu i 0 niepowodzeń):
{
"success": 0,
"failure": 0
}
Komunikat XMPP grupy urządzeń
<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>
Odpowiedzi XMPP grupy urządzeń
Gdy wiadomość zostanie wysłana do dowolnego z urządzeń w grupie, serwer połączenia XMPP wysyła potwierdzenie potwierdzenia. Jeśli wszystkie wiadomości wysłane do wszystkich urządzeń w grupie nie powiodą się, serwer połączeń XMPP w odpowiedzi wysyła NACK.
Oto przykład powodzenia – z domeną notification_key są powiązane 3 tokeny rejestracji i wiadomość została do nich wysłana:
{
"from": "aUniqueKey",
"message_type": "ack",
"success": 3,
"failure": 0,
"message_id": "m-1366082849205"
}
Oto przykład „częściowego sukcesu” – z notification_key są powiązane 3 tokeny rejestracji. Wiadomość została wysłana tylko do 1 tokena rejestracji. Komunikat z odpowiedzią zawiera listę tokenów rejestracji, które nie odebrały wiadomości:
{
"from": "aUniqueKey",
"message_type": "ack",
"success":1,
"failure":2,
"failed_registration_ids":[
"regId1",
"regId2"
]
}
Gdy serwer połączenia FCM nie może dostarczyć wiadomości do wszystkich urządzeń w grupie. Serwer aplikacji otrzyma odpowiedź nack.
Pełną listę opcji komunikatów znajdziesz w dokumentacji wybranego protokołu serwera połączenia – HTTP lub XMPP.
Starsze metody wysyłania z pakietu Firebase Admin SDK
Pakiet SDK Firebase Admin Node.js obsługuje metody wysyłania wiadomości (FCM) oparte na starszym interfejsie API serwera FCM.
Te metody akceptują inne argumenty niż metoda send().
Gdy to możliwe, używaj metody send() i wysyłaj wiadomości do poszczególnych urządzeń lub grup urządzeń wyłącznie z metod opisanych na tej stronie.
Wysyłaj na poszczególne urządzenia
Możesz przekazać token rejestracji do metody sendToDevice(), aby wysłać wiadomość na to urządzenie:
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);
});
Metoda sendToDevice() może też wysłać wiadomość grupową (czyli wiadomość do wielu urządzeń) przez przekazanie tablicy tokenów rejestracji zamiast jednego tokena rejestracji:
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);
});
Metoda sendToDevice() zwraca obietnicę, która jest realizowana za pomocą obiektu MessagingDevicesResponse zawierającego odpowiedź z FCM. Zwracany typ ma ten sam format podczas przekazywania pojedynczego tokena rejestracji lub tablicy tokenów rejestracji.
Niektóre przypadki, takie jak błąd uwierzytelniania lub ograniczenie liczby żądań, mogą spowodować, że cała wiadomość nie zostanie przetworzona. W takich przypadkach obietnica zwrócona przez funkcję sendToDevice() jest odrzucana z błędem. Pełną listę kodów błędów, w tym opisy i sposoby rozwiązywania problemów, znajdziesz w artykule Błędy interfejsu API FCM API dla administratorów.
Wyślij do grupy urządzeń
Metoda sendToDeviceGroup() umożliwia wysłanie wiadomości do grupy urządzeń przez podanie klucza powiadomień dla tej grupy urządzeń:
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);
});
Metoda sendToDeviceGroup() zwraca obietnicę, która jest realizowana za pomocą obiektu MessagingDevicesResponse zawierającego odpowiedź z FCM.
Niektóre przypadki, takie jak błąd uwierzytelniania lub ograniczenie liczby żądań, mogą spowodować, że cała wiadomość nie zostanie przetworzona. W takich przypadkach obietnica zwrócona przez funkcję sendToDeviceGroup() jest odrzucana z błędem. Pełną listę kodów błędów, w tym opisy i sposoby rozwiązywania problemów, znajdziesz w artykule Błędy interfejsu API FCM API dla administratorów.
Definiowanie ładunku wiadomości
Powyższe metody oparte na starszych protokołach FCM przyjmują ładunek wiadomości jako drugi argument i obsługują zarówno wiadomości, jak i wiadomości z danymi.
Możesz określić jeden lub oba typy wiadomości, tworząc obiekt za pomocą kluczy data i / lub notification. Poniżej pokazujemy, jak definiować różne typy ładunków wiadomości:
Wiadomość z powiadomieniem
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.'
}
};
Wiadomość dotycząca danych
const payload = {
data: {
score: '850',
time: '2:45'
}
};
Połączona wiadomość
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'
}
};
Ładunki wiadomości z powiadomieniem mają wstępnie zdefiniowany podzbiór prawidłowych właściwości i różnią się nieco w zależności od docelowego systemu operacyjnego na urządzenia mobilne.
Pełną listę znajdziesz w dokumentacji NotificationMessagePayload.
Ładunki komunikatów na temat danych składają się z niestandardowych par klucz-wartość (z kilkoma ograniczeniami) – między innymi zaś wszystkie wartości muszą być ciągami tekstowymi. Pełną listę ograniczeń znajdziesz w dokumentacji DataMessagePayload.
Definiowanie opcji wiadomości
Powyższe metody oparte na starszych protokołach FCM akceptują opcjonalny trzeci argument określający opcje wiadomości. W tym przykładzie wysyła się wiadomość o wysokim priorytecie na urządzenie, które wygasa po 24 godzinach:
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);
});
Pełną listę dostępnych opcji znajdziesz w dokumentacji MessagingOptions.