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

Korzystając z protokołów serwera aplikacji Firebase Admin SDK lub FCM, możesz tworzyć żądania wiadomości i wysyłać je do tych typów odbiorcó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 polu danych lub z kombinacji obu tych typów 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. Znajdziesz tam też wskazówki dotyczące wysyłania wiadomości za pomocą przestarzałych protokołów HTTP i XMPP.

.

Wysyłanie wiadomości na określone urządzenia

Aby wysłać wiadomość do konkretnego urządzenia, prześlij 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

W przypadku powodzenia 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ądzeń. Możesz określić maksymalnie 500 tokenów rejestracji urządzenia na 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, na przykład przez subskrybowanie instancji aplikacji klienta po stronie klienta lub za pomocą interfejsu API serwera, możesz wysyłać do niego wiadomości. Jeśli po raz pierwszy tworzysz żądania wysyłania w przypadku usługi FCM, zapoznaj się z przewodnikiem dotyczącym środowiska serwera i usługi FCM, aby uzyskać ważne informacje wstępne i informacje o konfiguracji.

W logice wysyłania na zapleczu określ 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 to wyrażenie spowoduje wysyłanie wiadomości do urządzeń, które mają subskrypcję TopicA i TopicB lub TopicC:

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

Funkcja FCM najpierw sprawdza warunki w nawiasach, a następnie 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. Te kombinacje otrzymują:

  • TopicA i TopicB
  • TopicA i TopicC

W wyrażeniu warunkowym możesz uwzględnić 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 HTTP API w wersji 1. Jeśli obecnie wysyłasz dane do grup urządzeń za pomocą przestarzałych interfejsów API do wysyłania danych (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 zbioru 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 tworzyć niestandardowe zestawy wiadomości i wysyłać je do różnych odbiorców, w tym na podstawie tematów lub konkretnych tokenów rejestracji urządzenia. Użyj tej funkcji, gdy chcesz na przykład wysłać jednocześnie wiadomości do różnych odbiorców z nieco innymi szczegółami w tekstach 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");
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 wiadomości do urządzeń w trybie bezpośredniego uruchamiania, wykonaj czynności umożliwiające odbieranie wiadomości FCM w tym trybie.

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

.

Żą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 wysyłane z tym kluczem w ciele żądania mogą być obsługiwane przez aplikacje na urządzeniach, które są w trybie bezpośredniego uruchamiania (i także wtedy, gdy nie są w tym trybie).

Dostosowywanie 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ść;
  • zestawy pól określonej platformy, np. AndroidConfig i WebpushConfig, interpretowane tylko przez instancje aplikacji działające na określonej platformie.

Blokady dla poszczególnych platform umożliwiają dostosowywanie wiadomości do różnych platform, aby zapewnić ich prawidłowe przetwarzanie po otrzymaniu. Backend FCM weźmie pod uwagę wszystkie określone parametry i dostosuje wiadomość do każdej platformy.

Kiedy używać pól wspólnych

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łanie pól tylko na określone platformy
  • Wyślij pola specyficzne dla platformy oprócz pól wspólnych.

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 na przykład wysyłać powiadomienia tylko na platformy Apple i do przeglądarki, ale nie na urządzenia z Androidem, musisz użyć 2 oddzielnych zestawów pól: jednego dla Apple i drugiego dla przeglądarki.

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 jeśli chcesz ustawić tę samą wartość na wszystkich platformach, musisz użyć pól specyficznych dla danej platformy. Dzieje się tak, ponieważ każda platforma może interpretować tę wartość nieco inaczej. Na przykład czas życia w Androidzie jest ustawiany jako czas wygaśnięcia w sekundach, a w przypadku Apple jako data wygaśnięcia.

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

W tym przykładowym żądaniu wysyłania wysyłamy wspólny tytuł i treść powiadomienia na wszystkie platformy, ale na urządzeniach z Androidem wysyłamy też niektóre zastąpienia specyficzne dla danej platformy.

W przypadku Androida żądanie ustawia specjalną ikonę i kolor, które będą wyświetlane na urządzeniach z Androidem. Jak wspomniano w dokumentacji dotyczącej AndroidNotification, kolor jest określony w formacie #rrggbb, a obraz musi być zasobowiązanym do rysowania zasobem ikony dostępnym lokalnie w aplikacji na Androida.

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

Prosty rysunek przedstawiający 2 urządzenia, z których jedno ma niestandardową 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"
       }
     }
   }
 }

Pełne informacje o kluczach dostępnych w blokach związanych z konkretną platformą w treści wiadomości znajdziesz w dokumentacji referencyjnej HTTP w wersji 1.

Przykład: wiadomość z powiadomieniem z niestandardowym obrazem

W tym przykładzie żądanie wysyłania zawiera wspólny tytuł powiadomienia na wszystkich platformach, ale także obraz. Oto przybliżony efekt wizualny na urządzeniu użytkownika:

Prosty rysunek obrazu w powiadomieniu wyświetlanym na ekranie

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

Pełne informacje o kluczach dostępnych w blokach związanych z konkretną platformą w treści wiadomości znajdziesz w dokumentacji referencyjnej HTTP w wersji 1.

Przykład: wiadomość z powiadomieniem z powiązanym działaniem po kliknięciu

W tym przykładzie żądanie wysyłania wysyła wspólny tytuł powiadomienia na wszystkie platformy, ale także zawiera 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:

Prosty rysunek przedstawiający użytkownika otwierającego 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"
       }
     }
   }
 }

Pełne informacje o kluczach dostępnych w blokach związanych z konkretną platformą w treści wiadomości znajdziesz w dokumentacji referencyjnej HTTP w wersji 1.

Przykład: wiadomość z powiadomieniem z opcjami lokalizacji

W tym przykładzie żądanie wysyłania przekazuje opcje lokalizacji, aby klient mógł wyświetlać lokalizowane wiadomości. Oto przybliżony efekt wizualny na urządzeniu użytkownika:

Prosty rysunek przedstawiający 2 urządzenia z tekstem w językach 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"],
                    },
                 },
               },
             },
  },
}'

Pełne informacje o kluczach dostępnych w blokach związanych z konkretną platformą w treści wiadomości znajdziesz w dokumentacji referencyjnej HTTP w wersji 1.

Kody błędów REST w przypadku interfejsu API HTTP w wersji 1

Odpowiedzi na błędy HTTP w interfejsie 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ź z błędem na żądanie interfejsu API HTTP w wersji 1 z nieprawidłową wartością w wiadomości danych

{
  "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ź z błędem na żądanie interfejsu API HTTP v1 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 ma typ type.googleapis.com/google.rpc.BadRequest, który wskazuje na błąd w wartościach żądania. 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 FCM REST v1 i ich opisy.

Kod błędu Opis i kroki prowadzące do rozwiązania
UNSPECIFIED_ERROR Brak więcej informacji o tym błędzie. Brak.
INVALID_ARGUMENT (kod błędu HTTP = 400) Parametry żądania były nieprawidłowe. Zwracany jest obiekt rozszerzenia typu google.rpc.BadRequest, który określa, które pole było nieprawidłowe. Możliwe przyczyny to nieprawidłowa rejestracja, nieprawidłowa nazwa pakietu, zbyt duża wiadomość, nieprawidłowy klucz danych, nieprawidłowa wartość TTL lub inne nieprawidłowe parametry.
Nieprawidłowa rejestracja: sprawdź format tokena rejestracji przekazywanego na serwer. Upewnij się, że jest on 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: sprawdź, czy wiadomość została wysłana do tokenu rejestracji, którego nazwa pakietu jest zgodna z wartością przekazaną w żądaniu.
Wiadomość jest za duża: sprawdź, czy łączny rozmiar danych w załadunku 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 (np. from, gcm lub dowolnej wartości z prefiksem google), który jest używany wewnętrznie przez FCM. Pamiętaj, że niektóre słowa (np. collapse_key) są też używane przez FCM, ale są dozwolone w pliku danych. W takim przypadku wartość pliku danych zostanie zastąpiona wartością FCM.
Nieprawidłowa wartość TTL: sprawdź, czy wartość użyta w polu ttl jest liczbą całkowitą reprezentującą czas trwania w sekundach z zakresu 0–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 odłączona od FCM. Zwykle oznacza to, że użyty token nie jest już ważny i należy użyć nowego. Ten błąd może być spowodowany brakiem tokenów rejestracji lub niezarejestrowanymi tokenami.
Brak rejestracji: jeśli docelowy element wiadomości to 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 takich przypadkach usuń ten 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 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. Podczas wysyłania wiadomości do aplikacji klienta należy użyć jednego z tych identyfikatorów nadawcy. Jeśli przełączysz się na innego nadawcę, dotychczasowe 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 określa, który limit został przekroczony. Ten błąd może być spowodowany przekroczeniem limitu szybkości wysyłania wiadomości, limitu szybkości wysyłania wiadomości na urządzenie lub limitu szybkości wysyłania wiadomości na temat.
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. Aby ponownie wysłać odrzucone wiadomości, użyj wykładniczego opóźnienia z minimalnym początkowym opóźnieniem wynoszącym 1 minutę.
Częstotliwość wysyłania wiadomości na urządzenie przekroczona: częstotliwość wysyłania wiadomości na konkretne urządzenie jest zbyt wysoka. Zobacz limit szybkości wysyłania wiadomości na jedno urządzenie. 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ść.
Przekroczenie częstotliwości wysyłania wiadomości w temacie: częstotliwość wysyłania wiadomości do subskrybentów danego tematu jest zbyt wysoka. Zmniejsz liczbę wiadomości wysyłanych w danym temacie 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 w czasie. Ponownie wysłać to samo żądanie, ale musisz:
- Honorować nagłówek Retry-After, jeśli jest on uwzględniony w odpowiedzi z serwera połączenia FCM.
– Wdrożyć wzrastający czas do ponowienia w mechanizmie ponownych prób. (np.jeśli przed pierwszą próbą czekasz 1 sekundę, przed kolejną poczekaj co najmniej 2 sekundy, a przed kolejną – 4 sekundy itd.). Jeśli wysyłasz wiele wiadomości, rozważ zastosowanie jitteringu. Więcej informacji znajdziesz w artykule Zarządzanie ponownymi próbami. Nadawcy, którzy powodują problemy, mogą zostać dodani do listy zablokowanych.
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 sugestiacjami 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ść danych logowania do wersji deweloperskiej i produkcyjnej.

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 Opis i kroki prowadzące do rozwiązania
messaging/invalid-argument Metoda FCM otrzymała nieprawidłowy argument. Komunikat o błędzie powinien zawierać dodatkowe informacje.
messaging/invalid-recipient Podany 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 zawiera nieprawidłowy klucz. Aby dowiedzieć się więcej o kluczach z ograniczeniami, zapoznaj się z dokumentacją DataMessagePayload.
messaging/payload-size-limit-exceeded Dane zawarte w wiadomości przekraczają limit 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 danych to 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 klienta otrzymuje podczas rejestracji w usłudze 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 klienta 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ł. Google może na przykład zdecydować się na odświeżenie tokenów rejestracji lub token APN może wygasnąć w przypadku urządzeń Apple.
  • Aplikacja klienta została zaktualizowana, ale nowa wersja nie jest skonfigurowana do odbierania wiadomości.
W takich przypadkach usuń ten token rejestracji i przestań go używać do wysyłania wiadomości.
messaging/invalid-package-name Wiadomość została wysłana do tokena rejestracji, którego nazwa pakietu nie odpowiada podanej opcji restrictedPackageName.
messaging/message-rate-exceeded Liczba wiadomości wysyłanych do określonej grupy odbiorców jest zbyt duża. Zmniejsz liczbę wiadomości wysyłanych do tego urządzenia lub tematu i nie próbuj ponownie wysyłać wiadomości do tego celu.
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 udało się wysłać wiadomości kierowanej na urządzenie Apple, ponieważ wymagany certyfikat SSL APN nie został przesłany lub wygasł. Sprawdź ważność certyfikatów rozwoju i produkcji.
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. Upewnij się, że dane logowania i token rejestracji należą do tego samego projektu Firebase. Aby dowiedzieć się, jak uwierzytelniać Firebase Admin SDK, zapoznaj się z dokumentacją dotyczącą dodawania Firebase do aplikacji.
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. Aby dowiedzieć się, jak uwierzytelniać Firebase Admin SDK, zapoznaj się z dokumentacją dotyczącą dodawania Firebase do aplikacji.
messaging/server-unavailable Serwer FCM nie mógł przetworzyć żądania w czasie. Powtórz to samo żądanie, ale:
  • Uwzględnij nagłówek Retry-After, jeśli jest on zawarty w odpowiedzi z serwera połączenia FCM.
  • W mechanizmie ponownych prób zastosuj wzrastający czas do ponowienia. Jeśli na przykład przed pierwszą próbą odczekałeś 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 niezależnie o dodatkowy losowy czas, aby uniknąć wysyłania nowej prośby dotyczącej wszystkich wiadomości w tym samym momencie.
Wydawcy, którzy powodują problemy, mogą zostać dodani do czarnej listy.
messaging/internal-error Podczas przetwarzania żądania serwer FCM napotkał błąd. Możesz ponownie przesłać to samo żądanie, spełniając wymagania podane w wierszu messaging/server-unavailable powyżej. Jeśli błąd będzie się powtarzał, zgłoś problem na naszym kanale pomocy Zgłoszenie 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 komunikat o błędzie, prześlij pełny komunikat o błędzie do naszego kanału pomocy Raportowanie błędów.

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ół w wersji 1 może znacznie uprościć żądania wiadomości.

Wysyłanie wiadomości na określone urządzenia

Aby wysyłać wiadomości na konkretne urządzenia, ustaw klucz to na token rejestracji dla konkretnej 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łączeń XMPP udostępnia kilka innych opcji 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 do tematu Firebase Cloud Messaging jest bardzo podobne do wysyłania wiadomości do konkretnego urządzenia lub grupy użytkowników. Serwer aplikacji ustawia klucz to z wartością, np. /topics/yourTopic. Programiści mogą wybrać dowolną nazwę tematu, która pasuje do wyrażenia regularnego: "/topics/[a-zA-Z0-9-_.~%]+".

Aby wysyłać dane do kombinacji wielu tematów, serwer aplikacji musi ustawić klucz condition (zamiast klucza to) jako 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)

FCM najpierw ocenia warunki w nawiasach, a następnie wyrażenie od lewej do prawej. W powyższym wyrażeniu użytkownik subskrybujący dowolny temat nie otrzymuje wiadomości. Podobnie użytkownik, który nie subskrybuje TopicA, nie otrzyma tej wiadomości. Te kombinacje otrzymują je:

  • TematA i TematB
  • TematA i TematC

W wyrażeniu warunkowym możesz uwzględnić maksymalnie 5 tematów. Obsługiwane są nawiasy. Obsługiwane operatory: && i ||.

Żądanie HTTP POST dotyczące 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 dotyczący 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 odpowiednio ustawić wartość limitu czasu serwera aplikacji w żądaniu.

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ń za pomocą 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” – konto notification_key ma powiązane 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 podjąć kolejną próbę z opóźnieniem między próbami.

Jeśli serwer próbuje wysłać wiadomość do grupy urządzeń, która nie ma żadnych członków, odpowiedź będzie wyglądać tak: 0 sukcesów i 0 błędów: 

{
  "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ń

Gdy wiadomość zostanie wysłana do dowolnego urządzenia w grupie, serwer połączeń XMPP odpowie potwierdzeniem. Jeśli wszystkie wiadomości wysłane do wszystkich urządzeń w grupie nie zostaną odebrane, serwer XMPP odpowie NACK.

Oto przykład „sukcesu” – usługa notification_key ma powiązane 3 tokeny rejestracji, a wiadomość została wysłana do wszystkich z nich: 

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

Oto przykład „częściowego sukcesu” – konto notification_key ma powiązane 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 wiadomości znajdziesz w informacjach 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) na podstawie starszego interfejsu API serwera FCM. Te metody akceptują 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ć wiadomości grupowe (czyli wiadomości do wielu 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. Typ zwracanych danych ma ten sam format, niezależnie od tego, czy przekazujesz pojedynczy token rejestracji, czy tablicę 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 ich opisy i sposoby rozwiązywania, znajdziesz w artykule Błędy interfejsu API FCM.

Wysyłanie do grupy urządzeń

Metoda sendToDeviceGroup() pozwala wysłać wiadomość do grupy urządzeń, podając klucz powiadomienia 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.

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ę sendToDeviceGroup() jest odrzucana z błędem. Pełną listę kodów błędów, w tym ich opisy i sposoby rozwiązywania, znajdziesz w artykule Błędy interfejsu API FCM.

Definiowanie ładunku wiadomości

Powyższe metody oparte na starszych protokołach FCM przyjmują jako drugi argument ładunek wiadomości 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 za pomocą kluczy data lub notification. Oto przykład definiowania różnych typów ł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'
  }
};

Dane payload 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 tego, na jaki system operacyjny mobilny się kierujesz. Pełną listę znajdziesz w dokumentacji NotificationMessagePayload.

Ładunki wiadomości danych składają się z niestandardowych par klucz-wartość z kilkoma ograniczeniami, w tym z wymogiem, aby wszystkie wartości były ciągami znaków. Pełną listę ograniczeń znajdziesz w dokumentacji 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.