Utwórz serwer aplikacji na potrzeby wysyłania żądań

Za pomocą protokołów serwera aplikacji Firebase Admin SDK lub FCM możesz tworzyć żądania wiadomości i wysyłać je do tych typów celów:

  • Nazwa tematu
  • Stan
  • Token rejestracji urządzenia
  • Nazwa grupy urządzeń (tylko protokół)

Możesz wysyłać wiadomości z danymi powiadomienia utworzonymi z definiowanych wstępnie pól, z danych użytkownika zdefiniowanych w polach użytkownika lub z danych zawierających oba te typy danych. Więcej informacji znajdziesz w sekcji Typy wiadomości.

Przykłady na tej stronie pokazują, jak wysyłać wiadomości z powiadomieniami za pomocą biblioteki Firebase Admin SDK (która obsługuje Node, Java, Python, C# i Go) oraz protokołu HTTP w wersji 1. Dostępne są też wskazówki dotyczące 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ć wiadomość do jednego, konkretnego urządzenia, przekaż token rejestracji urządzenia w sposób pokazany na ilustracji. Aby dowiedzieć się więcej o tokenach rejestracji, zapoznaj się z informacjami o konfiguracji klienta na swojej platformie.

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

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

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

Po udanym działaniu każda metoda wysyłania zwraca identyfikator wiadomości. Funkcja Firebase Admin SDK zwraca ciąg znaków 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ń

Interfejsy API Admin FCM umożliwiają wysyłanie wiadomości w ramach transmisji wielodostępnej na listę tokenów rejestracji urządzenia. Możesz określić do 500 tokenów rejestracji urządzenia 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");
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

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

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

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

Wysyłanie wiadomości do tematów

Po utworzeniu tematu przez subskrybowanie instancji aplikacji klienckiej w temacie po stronie klienta lub za pomocą interfejsu API serwera możesz wysyłać wiadomości do tematu. Jeśli tworzysz żądania wysyłania żądań dla usługi FCM po raz pierwszy, zapoznaj się z przewodnikiem po środowisku serwera iFCM w celu uzyskania ważnych informacji o tle i konfiguracji.

W logice wysyłania w backendzie określ odpowiednią nazwę tematu, jak pokazano poniżej:

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

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

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, czyli wyrażenie logiczne określające tematy docelowe. Na przykład poniższy 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)"

Funkcja FCM najpierw sprawdza wszystkie warunki w nawiasach, a potem ocenia wyrażenie od lewej do prawej. W przypadku tego wyrażenia użytkownik, który subskrybuje dowolny temat, nie otrzyma wiadomości. Podobnie użytkownik, który nie subskrybuje kanału TopicA, nie otrzyma wiadomości. Wynika to z tych kombinacji:

  • TopicA i TopicB
  • TopicA i TopicC

Wyrażenie warunkowe może zawierać maksymalnie 5 tematów.

Aby wysłać 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);
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

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

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 w wersji 1. Jeśli obecnie wysyłasz dane do grup urządzeń za pomocą przestarzałych interfejsów API do wysyłania (HTTP lub XMPP) lub dowolnej ze starszych wersji interfejsu Firebase Admin SDK do Node.js opartej na przestarzałych protokołach, zdecydowanie zalecamy jak najszybsze przenieś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ń jest bardzo podobne do wysyłania wiadomości do pojedynczego urządzenia. W obu przypadkach stosuje się tę samą metodę autoryzacji żądań wysyłania. W polu token ustaw klucz powiadomienia grupowego:

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 w partiach. Możesz utworzyć grupę zawierającą do 500 wiadomości i wysłać je w ramach jednego wywołania interfejsu API, co znacznie poprawi wydajność w porównaniu z wysyłaniem osobnych żądań HTTP dla każdej wiadomości.

Za pomocą tej funkcji możesz utworzyć niestandardowy zestaw wiadomości i wysyłać je do różnych adresatów, w tym tematów lub określonych tokenów rejestracji urządzenia. Użyj tej funkcji, jeśli na przykład musisz jednocześnie wysyłać wiadomości do różnych odbiorców z nieco odmiennymi szczegółami treś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");
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

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

Wysyłanie wiadomości z możliwością bezpośredniego uruchomienia (tylko Android)

Możesz wysyłać wiadomości do urządzeń w trybie bezpośredniego uruchamiania, korzystając z interfejsów HTTP w wersji 1 lub starszych interfejsów HTTP. Zanim wyślesz urządzenie do urządzeń w trybie bezpośredniego rozruchu, wykonaj odpowiednie czynności, aby umożliwić urządzeniom klienckim odbieranie wiadomości FCM w trybie bezpośredniego rozruchu.

Wysyłanie przy użyciu interfejsu HTTP FCM w wersji 1

Żądanie wiadomości musi zawierać klucz "direct_boot_ok" : true w opcjach AndroidConfig w 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 przy użyciu starszej wersji interfejsu HTTP API FCM

Żądanie 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 z tym kluczem w treści żądania mogą być obsługiwane przez aplikacje na urządzeniach znajdujących się obecnie w trybie rozruchu bezpośredniego (a także wtedy, gdy nie są w tym trybie).

Dostosuj wiadomości na różnych platformach

Zarówno protokół Firebase Admin SDK, jak i protokół HTTP FCM w wersji 1 umożliwiają ustawianie w żądaniach wiadomości wszystkich pól dostępnych w obiekcie message. Obejmuje to m.in.:

  • wspólny zestaw pól, które mają być interpretowane przez wszystkie wystąpienia aplikacji, które otrzymują wiadomość;
  • zbiorów pól związanych z konkretną platformą, takich jak AndroidConfig i WebpushConfig, interpretowane tylko przez instancje aplikacji działające na określonej platformie.

Blokady związane z konkretnymi platformami umożliwiają dostosowywanie wiadomości do różnych platform, dzięki czemu są one przetwarzane poprawnie po otrzymaniu. Backend FCM weźmie pod uwagę wszystkie określone parametry i dostosuje wiadomość do każdej platformy.

Kiedy używać wspólnych pól

Używaj pól wspólnych, gdy:

  • kierowanie na instancje aplikacji na wszystkich platformach: Apple, Android i internet;
  • Wysyłanie wiadomości do tematów

Wszystkie instancje aplikacji (niezależnie od platformy) mogą interpretować te wspólne pola:

Kiedy używać pól związanych z poszczególnymi platformami

Używaj pól związanych z poszczególnymi platformami, jeśli chcesz:

  • Wysyłaj pola tylko do określonych platform
  • Wysyłaj pola dotyczące platformy oprócz wspólnych pól.

Jeśli chcesz wysyłać wartości tylko na określone platformy, nie używaj wspólnych pól. Zamiast nich używaj pól specyficznych dla danej platformy. Aby np. wysłać powiadomienie tylko na platformy Apple i w przeglądarce, ale nie na Androida, musisz użyć 2 osobnych zbiorów pól – jednego dla Apple i drugiego dla internetu.

Jeśli wysyłasz wiadomości z określonymi opcjami dostarczania, użyj pól określonych dla danej platformy, aby je ustawić. W razie potrzeby możesz podać różne wartości dla poszczególnych platform. Nawet wtedy, gdy chcesz ustawić zasadniczo tę samą wartość na różnych platformach, musisz użyć pól dotyczących konkretnej platformy. Jest to spowodowane tym, że każda platforma może nieco inaczej interpretować wartość – na przykład na Androidzie czas życia jest ustawiany jako czas ważności w sekundach, a na Apple – jako datę ważności.

Przykład: wiadomość z powiadomieniem z opcjami koloru i ikony

To przykładowe żądanie wysłania wysyła ten sam tytuł i treść powiadomienia na wszystkie platformy, ale wysyła też niektóre zastąpienia na urządzeniach z Androidem.

W przypadku Androida żądanie to ustawia specjalną ikonę i kolor do wyświetlania na urządzeniach z Androidem. Jak wspomnieliśmy w odniesieniu do Android Notification, kolor jest określony w formacie #rrggbb, a obraz musi być zasobem ikony z możliwością rysowania i lokalnie w aplikacji na Androida.

Oto przybliżony efekt wizualny na urządzeniu użytkownika:

Prosty rysunek na 2 urządzeniach, z których jedno wyświetla własną ikonę i kolor

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

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

Szczegółowe informacje na temat kluczy dostępnych w blokach na poziomie platformy znajdziesz w treści wiadomości w dokumentacji referencyjnej HTTP w wersji 1.

Przykład: komunikat z niestandardowym obrazem

Poniższe przykładowe żądanie wysłania powoduje wysłanie wspólnego tytułu powiadomienia do wszystkich platform, ale powoduje też przesłanie obrazu. Oto przybliżony efekt wizualny na urządzeniu użytkownika:

Prosty rysunek z obrazem w powiadomieniu o wyświetlaniu

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

Szczegółowe informacje na temat kluczy dostępnych w blokach na poziomie platformy znajdziesz w treści wiadomości w dokumentacji referencyjnej HTTP w wersji 1.

Przykład: powiadomienie z powiązanym działaniem powodującym kliknięcie

Poniższe przykładowe żądanie wysyłania wysyła ten sam tytuł powiadomienia na wszystkie platformy, ale wysyła też działanie, które aplikacja ma wykonać w odpowiedzi na interakcję użytkownika z powiadomieniem. Oto szacowany efekt wizualny na urządzenie użytkownika:

Prosty rysunek przedstawiający użytkowniczkę otwierającą stronę internetową

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

Szczegółowe informacje na temat kluczy dostępnych w blokach na poziomie platformy znajdziesz w treści wiadomości w dokumentacji referencyjnej HTTP w wersji 1.

Przykład: wiadomość z opcjami lokalizacji

Poniższe przykładowe żądanie wysyłania wysyła do klienta opcje lokalizacji umożliwiające wyświetlenie zlokalizowanych wiadomości. Oto przybliżony efekt wizualny na urządzeniu użytkownika:

Prosty rysunek na 2 urządzeniach wyświetlających tekst w języku angielskim i hiszpańskim

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

Szczegółowe informacje na temat kluczy dostępnych w blokach na poziomie platformy znajdziesz w treści wiadomości w dokumentacji referencyjnej HTTP w wersji 1.

Kody błędów REST interfejsu HTTP v1 API

Odpowiedzi na błędy HTTP dla interfejsu API HTTP w wersji 1 zawierają kod błędu, komunikat o błędzie i stan błędu. Mogą też zawierać tablicę details ze szczegółowymi informacjami o błędzie.

Oto 2 przykładowe odpowiedzi na błąd:

Przykład 1. Odpowiedź błędu z żądania HTTP w wersji 1 interfejsu API z nieprawidłową wartością w komunikacie 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ź błędu z żądania HTTP w wersji 1 do interfejsu API 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"
      }
    ]
   }
}

Zwróć uwagę, że obie wiadomości mają ten sam kod i stan, ale tablica szczegółów zawiera wartości o różnych typach. Pierwszy przykład zawiera typ type.googleapis.com/google.rpc.BadRequest, który wskazuje błąd w wartościach żądań. Drugi przykład z typem type.googleapis.com/google.firebase.fcm.v1.FcmError zawiera błąd FCM. W przypadku wielu błędów tablica szczegółów zawiera informacje potrzebne do debugowania i rozwiązania problemu.

W tabeli poniżej znajdziesz kody błędów interfejsu API REST FCM w wersji 1 wraz z opisami.

Kod błędu Etapy opisu i rozwiązania
UNSPECIFIED_ERROR Brak dodatkowych informacji na temat tego błędu. Brak.
INVALID_ARGUMENT (kod błędu HTTP = 400) Parametry żądania były nieprawidłowe. Zwracane jest rozszerzenie typu google.rpc.BadRequest, aby określić, które pole było nieprawidłowe. Potencjalne przyczyny to m.in. nieprawidłowa rejestracja, niewłaściwa nazwa pakietu, zbyt duża wiadomość, nieprawidłowy klucz danych, nieprawidłowa wartość TTL i inne nieprawidłowe parametry.
Nieprawidłowa rejestracja: sprawdź format tokena rejestracji, który przekazujesz na serwer. Upewnij się, że jest zgodny z tokenem rejestracji, który aplikacja klienta otrzymuje podczas rejestracji w FCM. Nie skracaj tokena ani nie dodawaj dodatkowych znaków.
Nieprawidłowa nazwa pakietu: upewnij się, że wiadomość była zaadresowana na token rejestracji, którego nazwa pakietu pasuje do 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 do tematów. Dotyczy to zarówno kluczy, jak i wartości.
Nieprawidłowy klucz danych: sprawdź, czy dane ładunku nie zawierają klucza (takiego jak from, gcm lub wartości poprzedzonej prefiksem google) używanego wewnętrznie przez FCM. Pamiętaj, że niektóre słowa (takie jak fold_key) są również 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żyta w parametrze ttl jest liczbą całkowitą oznaczają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) Wystąpienie aplikacji zostało wyrejestrowane z FCM. Zwykle oznacza to, że użyty token nie jest już ważny i należy użyć nowego. Przyczyną tego błędu może być brak tokenów rejestracji lub niezarejestrowane tokeny.
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, np.:
- jeśli aplikacja klienta wyrejestruje się w FCM.
- jeśli aplikacja kliencka zostanie automatycznie wyrejestrowana, co może się zdarzyć, gdy użytkownik ją odinstaluje. Na przykład w iOS, jeśli usługa informacji zwrotnych APNs zgłosiła, że token APNs jest nieprawidłowy.
- jeśli token rejestracji wygaśnie (na przykład Google może zdecydować się na odświeżenie tokenów rejestracji lub token APN wygaśnie na urządzeniach z iOS).
– jeśli aplikacja klienta została zaktualizowana, ale nowa wersja nie jest skonfigurowana do odbierania wiadomości.
W tych przypadkach usuń token rejestracji z serwera aplikacji i przestań używać go do wysyłania wiadomości.
SENDER_ID_MISMATCH (kod błędu HTTP = 403) Uwierzytelniony identyfikator nadawcy różni się od identyfikatora nadawcy tokena rejestracji. Token rejestracji jest powiązany z określoną grupą nadawców. Gdy aplikacja klienta rejestruje się w FCM, musi określić, którzy nadawcy mogą wysyłać wiadomości. Jeden z tych identyfikatorów nadawcy należy używać podczas wysyłania wiadomości do aplikacji klienckiej. Jeśli zmienisz nadawcę, istniejące tokeny rejestracji nie będą działać.
QUOTA_EXCEEDED (kod błędu HTTP = 429) przekroczono limit wysyłania dla docelowego odbiorcy wiadomości. Zwracane jest rozszerzenie typu google.rpc.QuotaFailure, które wskazuje, który limit został przekroczony. Przyczyną tego błędu może być przekroczenie limitu liczby wiadomości na urządzeniu, przekroczenie limitu liczby wiadomości na urządzeniu lub przekroczenie limitu liczby wiadomości w temacie.
Przekroczenie szybkości wysyłania wiadomości: szybkość wysyłania wiadomości jest zbyt wysoka. Musisz zmniejszyć ogólną częstotliwość wysyłania wiadomości. Używaj wykładniczego czasu do ponowienia z minimalnym opóźnieniem początkowym wynoszącym 1 minutę, aby ponawiać próby odrzucenia wiadomości.
Przekroczono liczbę wiadomości na urządzeniu: liczba wiadomości wysyłanych na określone urządzenie jest za duża. Zobacz ograniczenie liczby wiadomości na jednym urządzeniu. Zmniejsz liczbę wiadomości wysyłanych na to urządzenie i użyj strategii wzrastającego czasu do ponowienia, aby ponownie spróbować wysłać wiadomość.
Przekroczono liczbę wiadomości z tego tematu: liczba wiadomości do subskrybentów na dany temat jest za wysoka. Zmniejsz liczbę wiadomości wysyłanych w ramach tego tematu i użyj wykładniczego opóźnienia z minimalnym początkowym opóźnieniem wynoszącym 1 minutę, aby ponownie spróbować wysłać wiadomość.
UNAVAILABLE (kod błędu HTTP = 503) Serwer jest przeciążony. Serwer nie mógł przetworzyć żądania na czas. Ponów to samo żądanie, ale pamiętaj, że:
– uznanie nagłówka Ponów próbę po, jeśli jest on zawarty w odpowiedzi serwera połączenia FCM.
– Wdróż wykładniczy czas do ponowienia w mechanizmie ponawiania prób. (np.jeśli odczekałeś sekundy przed pierwszą próbą, odczekaj co najmniej dwie sekundy przed kolejną, potem 4 sekundy itd.). Jeśli wysyłasz wiele wiadomości, rozważ zastosowanie zakłóceń. Więcej informacji znajdziesz w artykule Obsługa ponownych prób. Nadawcy, którzy powodują problemy, mogą zostać umieszczone na liście odrzuconych.
INTERNAL (Kod błędu HTTP = 500) Wystąpił nieznany błąd wewnętrzny. Podczas próby przetworzenia żądania serwer napotkał błąd. Możesz ponownie wysłać to samo żądanie, postępując zgodnie z sugestiam podanymi 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) Certyfikat APN lub klucz uwierzytelniający web push jest nieprawidłowy lub go brakuje. Nie udało się wysłać wiadomości kierowanej na urządzenie z iOS lub rejestracji powiadomień push w internecie. Sprawdź poprawność swoich uprawnień związanych z programowaniem i produkcją.

Kody błędów administratora

W tabeli poniżej znajdziesz kody błędów interfejsu API FCM Firebase Admin oraz ich opisy, w tym zalecane sposoby rozwiązania problemu.

Kod błędu Etapy opisu i rozwiązania
messaging/invalid-argument Podano nieprawidłowy argument do metody FCM. Komunikat o błędzie powinien zawierać dodatkowe informacje.
messaging/invalid-recipient Adresat 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 zawiera nieprawidłowy klucz. Informacje o kluczach z ograniczeniami znajdziesz w dokumentacji referencyjnej DataMessagePayload.
messaging/payload-size-limit-exceeded Dane zawarte w wiadomości przekraczają limit rozmiaru FCM. Limit dla większości wiadomości to 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. Sprawdź, czy jest zgodny z tokenem rejestracji, który aplikacja kliencka otrzymuje po rejestracji w FCM. Nie skracaj ani nie dodawaj do niego dodatkowych znaków.
messaging/registration-token-not-registered Podany token rejestracji nie jest zarejestrowany. Poprzednio ważny token rejestracji może zostać wyrejestrowany z różnych powodów, między innymi:
  • Aplikacja klienta została wyrejestrowana z usługi FCM.
  • Aplikacja kliencka została automatycznie wyrejestrowana. Może się tak zdarzyć, jeśli użytkownik odinstaluje aplikację lub jeśli na platformach Apple usługa informacji zwrotnych APNs zgłosi, że token APNs jest nieprawidłowy.
  • Token rejestracji wygasł. Na przykład Google może postanowić odświeżyć tokeny rejestracji lub token APNs mógł wygasnąć dla urządzeń Apple.
  • Aplikacja kliencka została zaktualizowana, ale nowa wersja nie jest skonfigurowana do odbierania wiadomości.
We wszystkich tych przypadkach usuń ten token rejestracji i przestań używać go do wysyłania wiadomości.
messaging/invalid-package-name Wiadomość była zaadresowana na token rejestracji, którego nazwa pakietu nie zgadza się z podaną opcją restrictedPackageName.
messaging/message-rate-exceeded Częstotliwość wysyłania wiadomości do określonej grupy docelowej jest zbyt wysoka. Zmniejsz liczbę wiadomości wysyłanych do tego urządzenia lub tematu i nie ponawiaj próby wysłania od razu do tego miejsca docelowego.
messaging/device-message-rate-exceeded Liczba wiadomości wysyłanych na konkretne urządzenie jest zbyt wysoka. Zmniejsz liczbę wiadomości wysyłanych na to urządzenie i nie próbuj od razu wysyłać kolejnych.
messaging/topics-message-rate-exceeded Liczba wiadomości wysyłanych do subskrybentów danego tematu jest zbyt duża. Zmniejsz liczbę wiadomości wysyłanych do tego tematu i nie próbuj ponownie wysyłać wiadomości do tego tematu.
messaging/too-many-topics Token rejestracji został subskrybowany w maksymalnej liczbie tematów i nie można go już subskrybować.
messaging/invalid-apns-credentials Nie można 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 wiadomości na urządzenie odpowiadające podanemu tokenowi rejestracji. Sprawdź, czy dane logowania i token rejestracji należą do tego samego projektu Firebase. Przeczytaj artykuł Dodawanie Firebase do aplikacji, aby zapoznać się z dokumentacją dotyczącą uwierzytelniania Firebase Admin SDK.
messaging/authentication-error Pakiet SDK nie mógł uwierzytelnić się na serwerach FCM. Upewnij się, że uwierzytelniasz Firebase Admin SDK za pomocą danych logowania, które mają odpowiednie uprawnienia do wysyłania wiadomości FCM. Przeczytaj artykuł Dodawanie Firebase do aplikacji, aby zapoznać się z dokumentacją dotyczącą uwierzytelniania Firebase Admin SDK.
messaging/server-unavailable Serwer FCM nie mógł przetworzyć żądania na czas. Ponów tę samą prośbę, ale musisz:
  • Uwzględniaj nagłówek Retry-After, jeśli znajduje się on w odpowiedzi z serwera połączenia FCM.
  • Wdróż wykładniczy czas ponowienia w mechanizmie ponawiania. Jeśli na przykład przed pierwszą próbą zaczekasz 1 sekundę, przed kolejną odczekaj co najmniej 2 sekundy, a przed kolejną 4 sekundy itd. Jeśli wysyłasz wiele wiadomości, opóźnij każdą z nich o dodatkową losową ilość, aby uniknąć wysyłania nowego żądania do wszystkich wiadomości w tym samym czasie.
Wydawcy, którzy powodują problemy, mogą zostać umieszczeni na liście zablokowanych.
messaging/internal-error Podczas próby przetworzenia żądania wystąpił błąd serwera FCM. Możesz wysłać tę samą prośbę ponownie, spełniając wymagania wymienione w wierszu messaging/server-unavailable powyżej. Jeśli błąd będzie się powtarzał, zgłoś go zespołowi pomocy zgłoszenia błędu.
messaging/unknown-error Zwrócono nieznany błąd serwera. Aby uzyskać więcej informacji, sprawdź nieprzetworzone dane odpowiedzi serwera w komunikacie o błędzie. Jeśli pojawi się ten błąd, prześlij pełny komunikat o błędzie, korzystając z naszego kanału pomocy dotyczącego raportu o błędzie.

Wysyłanie wiadomości przy użyciu starszych protokołów serwera aplikacji

.

Jeśli obecnie używasz starszych protokołów, twórz żądania wiadomości w sposób pokazany w tej sekcji. Pamiętaj, że 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 do określonych urządzeń, jako klucz to ustaw token rejestracji danej instancji aplikacji. Aby dowiedzieć się więcej o tokenach rejestracji, zapoznaj się z informacjami o konfiguracji klienta na swojej platformie.

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

Wiadomość 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 oferuje inne opcje odpowiedzi. Zobacz Format odpowiedzi serwera.

Pełną listę opcji wiadomości dostępnych podczas wysyłania wiadomości do aplikacji klienckich znajdziesz w informacjach referencyjnych dotyczących wybranego protokołu serwera połączeń (HTTP lub XMPP).

Wysyłanie wiadomości do tematów

Wysyłanie wiadomości na temat Firebase Cloud Messaging jest bardzo podobne do wysyłania wiadomości na poszczególne urządzenia lub do grupy użytkowników. Serwer aplikacji ustawia klucz to na wartość taką jak /topics/yourTopic. Programiści mogą wybrać dowolną nazwę tematu, która pasuje do wyrażenia regularnego: "/topics/[a-zA-Z0-9-_.~%]+".

Aby wysyłać wiadomości do kombinacji tematów, serwer aplikacji musi ustawić klucz condition (zamiast klucza to) na warunek logiczny określający 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)

Funkcja FCM najpierw sprawdza wszystkie warunki w nawiasach, a potem ocenia wyrażenie od lewej do prawej. W powyższym wyrażeniu użytkownik zasubskrybowany dowolny pojedynczy temat nie otrzymuje wiadomości. Podobnie użytkownik, który nie subskrybuje tematu A, nie otrzyma tej wiadomości. Te kombinacje otrzymują:

  • Tematy A i B
  • TematA i TematC

Wyrażenie warunkowe może zawierać maksymalnie 5 tematów. Nawiasy są obsługiwane. Obsługiwane operatory: && i ||.

Żą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 z 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 na temat

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

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

Spodziewaj się opóźnienia do 30 sekund, zanim serwer FCM odpowie na żądanie wysłania tematu. Pamiętaj, aby ustawić w żądaniu odpowiedni limit czasu oczekiwania serwera aplikacji.

Wysyłanie wiadomości do grup urządzeń

.

Wysyłanie wiadomości do grupy urządzeń za pomocą starszych interfejsów API jest bardzo podobne do wysyłania wiadomości do pojedynczego urządzenia. Ustaw parametr to na unikalny klucz powiadomienia dla grupy urządzeń. Przykłady w tej sekcji pokazują, jak wysyłać wiadomości z danymi do grup urządzeń przy użyciu starszych protokołów 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 „sukcesu” – usługa notification_key ma 2 powiązane z nią tokeny rejestracji, a wiadomość została wysłana do obu z nich: 

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

Oto przykład „częściowego sukcesu” – z notification_key powiązane są 3 tokeny rejestracji. Wiadomość została wysłana tylko do 1 tokena rejestracji. Wiadomość z odpowiedzią zawiera listę tokenów rejestracji (registration_ids), które nie otrzymały wiadomości: 

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

Jeśli nie uda się dostarczyć wiadomości do co najmniej jednego z tokenów rejestracji powiązanych z notification_key, serwer aplikacji powinien spróbować ponownie, stosując odstęp między próbami.

Jeśli serwer próbuje wysłać wiadomość do grupy urządzeń, która nie ma użytkowników, odpowiedź wygląda tak jak poniżej (0 powodów, 0 niepowodzeń): 

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

Wiadomość 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>

Odpowiedź XMPP grupy urządzeń

Jeśli wiadomość zostanie pomyślnie wysłana na dowolne z urządzeń w grupie, serwer połączeń XMPP zwróci odpowiedź ACK. Jeśli wszystkie wiadomości wysłane do wszystkich urządzeń w grupie nie zostaną odebrane, serwer XMPP odpowie NACK.

Oto przykład „sukcesu” – z notification_key powiązane są 3 tokeny rejestracji, a komunikat został do nich wysłany: 

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

Oto przykład „częściowego sukcesu” – z notification_key powiązane są 3 tokeny rejestracji. Wiadomość została wysłana tylko do 1 tokena rejestracji. Wiadomość z odpowiedzią zawiera listę tokenów rejestracji, które nie otrzymał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 przesłać danych do wszystkich urządzeń w grupie. Serwer aplikacji otrzyma odpowiedź nack.

Pełną listę opcji komunikatów znajdziesz w materiałach referencyjnych dotyczących wybranego protokołu serwera połączeń, HTTP lub XMPP.

Firebase Admin SDK starsze metody wysyłania

Pakiet SDK Firebase Admin Node.js obsługuje metody wysyłania wiadomości (FCM) oparte na starszym interfejsie API serwera FCM. Te metody przyjmują inne argumenty niż metoda send(). W miarę możliwości należy używać metody send(), a metody opisane na tej stronie należy stosować tylko do wysyłania wiadomości do poszczególnych urządzeń lub grup urządzeń.

Wysyłanie do poszczególnych urządzeń

Aby wysłać wiadomość na to urządzenie, możesz przekazać token rejestracji do metody sendToDevice():

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ż wysyłać komunikat multicast (czyli wiadomość na wiele urządzeń), przekazując tablicę tokenów rejestracji zamiast pojedynczego 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 metody FCM. Zwracany typ ma ten sam format podczas przekazywania pojedynczego tokena rejestracji lub tablicy tokenów rejestracji.

W niektórych przypadkach, np. gdy wystąpi błąd uwierzytelniania lub ograniczenie szybkości, nie udaje się przetworzyć całej wiadomości. W takich przypadkach obietnica zwracana 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 administratora.

Wyślij do grupy urządzeń

Metoda sendToDeviceGroup() umożliwia wysyłanie wiadomości do grupy urządzeń przez określenie klucza powiadomień dla tej grupy:

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 metody FCM.

Niektóre przypadki, takie jak błąd uwierzytelniania lub ograniczenie liczby żądań, mogą spowodować niepowodzenie przetwarzania całej wiadomości. W takich przypadkach obietnica zwrócona przez funkcję sendToDeviceGroup() jest odrzucana z powodu błędu. 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 administratora.

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 z powiadomieniami, jak i wiadomości z danymi. Możesz określić jeden lub oba typy wiadomości, tworząc obiekt z kluczami data lub notification. Tak na przykład możesz zdefiniować różne typy ładunków wiadomości:

Powiadomienie

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.'
  }
};

Komunikat o 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 powiadomieniami mają wstępnie zdefiniowany podzbiór prawidłowych właściwości i różnią się nieco w zależności od tego, na który mobilny system operacyjny są kierowane reklamy. Pełną listę znajdziesz w dokumentacji referencyjnej NotificationMessagePayload.

Ładunki komunikatów z danymi składają się z niestandardowych par klucz-wartość z kilkoma ograniczeniami, między innymi z tym, że wszystkie wartości muszą być ciągami tekstowymi. Pełną listę ograniczeń znajdziesz w dokumentach referencyjnych dotyczących DataMessagePayload.

Definiowanie opcji wiadomości

Powyższe metody oparte na starszych protokołach FCMakceptują opcjonalny trzeci argument, który określa niektóre opcje wiadomości. Na przykład w tym przykładzie wysyłamy wiadomość o wysokim priorytecie na urządzenie, która wygaśnie 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.