Żądania wysyłania do serwera aplikacji kompilacji

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

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

Możesz wysyłać wiadomości z ładunkiem powiadomień składającym się ze wstępnie zdefiniowanych pól, ładunkiem danych we własnych polach zdefiniowanych przez użytkownika lub wiadomością zawierającą oba typy ładunków. Więcej informacji znajdziesz w sekcji Typy wiadomości.

Przykłady na tej stronie pokazują, jak wysyłać powiadomienia za pomocą pakietu SDK Firebase Admin (który obsługuje Node, Java, Python, C# i Go) oraz v1 protokołu HTTP. 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ść na jedno konkretne urządzenie, 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 dotyczącymi Twojej platformy.

Node.js

// This registration token comes from the client FCM SDKs.
const registrationToken = 'YOUR_REGISTRATION_TOKEN';

const message = {
  data: {
    score: '850',
    time: '2:45'
  },
  token: registrationToken
};

// Send a message to the device corresponding to the provided
// registration token.
getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

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

// See documentation on defining a message payload.
Message message = Message.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .setToken(registrationToken)
    .build();

// Send a message to the device corresponding to the provided
// registration token.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);

Python

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

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

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

Go

// Obtain a messaging.Client from the App.
ctx := context.Background()
client, err := app.Messaging(ctx)
if err != nil {
	log.Fatalf("error getting Messaging client: %v\n", err)
}

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

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Token: registrationToken,
}

// Send a message to the device corresponding to the provided
// registration token.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)

C#

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

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

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

REST

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

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

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

Polecenie cURL:

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

Po udanym działaniu każda metoda wysyłania zwraca identyfikator wiadomości. Pakiet SDK Firebase Admin 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 administratora FCM umożliwiają zbiorcze przesyłanie wiadomości na listę tokenów rejestracji urządzeń. 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");

Python

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

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

Go

// Create a list containing up to 500 registration tokens.
// This registration tokens come from the client FCM SDKs.
registrationTokens := []string{
	"YOUR_REGISTRATION_TOKEN_1",
	// ...
	"YOUR_REGISTRATION_TOKEN_n",
}
message := &messaging.MulticastMessage{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Tokens: registrationTokens,
}

br, err := client.SendMulticast(context.Background(), message)
if err != nil {
	log.Fatalln(err)
}

// See the BatchResponse reference documentation
// for the contents of response.
fmt.Printf("%d messages were sent successfully\n", br.SuccessCount)

C#

// Create a list containing up to 500 registration tokens.
// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n",
};
var message = new MulticastMessage()
{
    Tokens = registrationTokens,
    Data = new Dictionary<string, string>()
    {
        { "score", "850" },
        { "time", "2:45" },
    },
};

var response = await FirebaseMessaging.DefaultInstance.SendEachForMulticastAsync(message);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");

Zwracana wartość to lista tokenów odpowiadająca kolejności tokenów wejściowych. Jest to przydatne, gdy chcesz sprawdzić, które tokeny spowodowały błędy.

Node.js

// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
  'YOUR_REGISTRATION_TOKEN_1',
  // …
  'YOUR_REGISTRATION_TOKEN_N',
];

const message = {
  data: {score: '850', time: '2:45'},
  tokens: registrationTokens,
};

getMessaging().sendMulticast(message)
  .then((response) => {
    if (response.failureCount > 0) {
      const failedTokens = [];
      response.responses.forEach((resp, idx) => {
        if (!resp.success) {
          failedTokens.push(registrationTokens[idx]);
        }
      });
      console.log('List of tokens that caused failures: ' + failedTokens);
    }
  });

Java

// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n"
);

MulticastMessage message = MulticastMessage.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .addAllTokens(registrationTokens)
    .build();
BatchResponse response = FirebaseMessaging.getInstance().sendMulticast(message);
if (response.getFailureCount() > 0) {
  List<SendResponse> responses = response.getResponses();
  List<String> failedTokens = new ArrayList<>();
  for (int i = 0; i < responses.size(); i++) {
    if (!responses.get(i).isSuccessful()) {
      // The order of responses corresponds to the order of the registration tokens.
      failedTokens.add(registrationTokens.get(i));
    }
  }

  System.out.println("List of tokens that caused failures: " + failedTokens);
}

Python

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

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

Go

// Create a list containing up to 500 registration tokens.
// This registration tokens come from the client FCM SDKs.
registrationTokens := []string{
	"YOUR_REGISTRATION_TOKEN_1",
	// ...
	"YOUR_REGISTRATION_TOKEN_n",
}
message := &messaging.MulticastMessage{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Tokens: registrationTokens,
}

br, err := client.SendMulticast(context.Background(), message)
if err != nil {
	log.Fatalln(err)
}

if br.FailureCount > 0 {
	var failedTokens []string
	for idx, resp := range br.Responses {
		if !resp.Success {
			// The order of responses corresponds to the order of the registration tokens.
			failedTokens = append(failedTokens, registrationTokens[idx])
		}
	}

	fmt.Printf("List of tokens that caused failures: %v\n", failedTokens)
}

C#

// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n",
};
var message = new MulticastMessage()
{
    Tokens = registrationTokens,
    Data = new Dictionary<string, string>()
    {
        { "score", "850" },
        { "time", "2:45" },
    },
};

var response = await FirebaseMessaging.DefaultInstance.SendEachForMulticastAsync(message);
if (response.FailureCount > 0)
{
    var failedTokens = new List<string>();
    for (var i = 0; i < response.Responses.Count; i++)
    {
        if (!response.Responses[i].IsSuccess)
        {
            // The order of responses corresponds to the order of the registration tokens.
            failedTokens.Add(registrationTokens[i]);
        }
    }

    Console.WriteLine($"List of tokens that caused failures: {failedTokens}");
}

Wysyłaj 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 po raz pierwszy tworzysz żądania wysyłania żądań do FCM, przeczytaj przewodnik po środowisku serwera i FCM, w którym znajdziesz ważne informacje i informacje o 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);

Python

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

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

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

Go

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

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Topic: topic,
}

// Send a message to the devices subscribed to the provided topic.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)

C#

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

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

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

REST

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

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

Polecenie cURL:

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

Aby wysłać wiadomość do kombinacji tematów, określ warunek, 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)"

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

  • TopicATopicB
  • TopicATopicC

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

Python

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

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

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

Go

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

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Condition: condition,
}

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)

C#

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

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

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

REST

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

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

Polecenie cURL:

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

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

Aby wysyłać wiadomości do grup urządzeń, użyj interfejsu API HTTP w wersji 1. Jeśli wysyłasz obecnie wiadomości do grup urządzeń za pomocą wycofanych starszych wersji interfejsów API wysyłania do HTTP lub XMPP albo dowolnych starszych wersji pakietu SDK Firebase Admin dla Node.js opartego na starszych protokołach, zdecydowanie zalecamy jak najszybsze przejście na interfejs HTTP v1 API. Starsze interfejsy API do wysyłania zostaną wyłączone i usunięte w czerwcu 2024 r.

Wysyłanie wiadomości do grupy urządzeń jest bardzo podobne do wysyłania wiadomości na pojedyncze urządzenie – przy użyciu tej samej metody autoryzowania żądań wysłania. W polu token ustaw klucz powiadomień grupy:

REST

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

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

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

Polecenie cURL

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

Wysyłanie grupy wiadomości

Pakiety Admin SDK obsługują wysyłanie wiadomości zbiorczo. Możesz zgrupować do 500 wiadomości w jedną partię i wysłać je wszystkie w jednym wywołaniu interfejsu API. Zapewnia to znacznie większą wydajność niż wysyłanie 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");

Python

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

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

Go

// Create a list containing up to 500 messages.
messages := []*messaging.Message{
	{
		Notification: &messaging.Notification{
			Title: "Price drop",
			Body:  "5% off all electronics",
		},
		Token: registrationToken,
	},
	{
		Notification: &messaging.Notification{
			Title: "Price drop",
			Body:  "2% off all books",
		},
		Topic: "readers-club",
	},
}

br, err := client.SendAll(context.Background(), messages)
if err != nil {
	log.Fatalln(err)
}

// See the BatchResponse reference documentation
// for the contents of response.
fmt.Printf("%d messages were sent successfully\n", br.SuccessCount)

C#

// Create a list containing up to 500 messages.
var messages = new List<Message>()
{
    new Message()
    {
        Notification = new Notification()
        {
            Title = "Price drop",
            Body = "5% off all electronics",
        },
        Token = registrationToken,
    },
    new Message()
    {
        Notification = new Notification()
        {
            Title = "Price drop",
            Body = "2% off all books",
        },
        Topic = "readers-club",
    },
};

var response = await FirebaseMessaging.DefaultInstance.SendEachAsync(messages);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");

Wysyłanie wiadomości przy włączonym bezpośrednim rozruchu (tylko Android)

Za pomocą interfejsów HTTP w wersji 1 lub starszych interfejsów API HTTP możesz wysyłać wiadomości na urządzenia w trybie bezpośredniego rozruchu. 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.

Wyślij przez interfejs API 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

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

  • wspólny zestaw pól do interpretowania przez wszystkie instancje aplikacji, które otrzymają 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 bierze pod uwagę wszystkie określone parametry i dostosowuje wiadomość dla każdej platformy.

Kiedy używać wspólnych pól

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

  • kierowanie na instancje aplikacji na wszystkich platformach – Apple, Android i sieć.
  • 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 konkretną platformą

Użyj pól związanych z konkretną platformą, 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 do konkretnych platform, nie używaj wspólnych pól. Używaj pól związanych z daną platformą. 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 witryny.

Jeśli wysyłasz wiadomości z określonymi opcjami dostarczania, skorzystaj z pól na odpowiedniej platformie, aby je skonfigurować. Jeśli chcesz, możesz podać różne wartości na poszczególnych platformach. 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: powiadomienie z opcjami koloru i ikon

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 funkcji Android Notification, kolor określa się w formacie #rrggbb, a obraz musi być zasobem ikony z możliwością rysowania i lokalnie w aplikacji na Androida.

Oto szacowany efekt wizualny na urządzenie 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();

Python

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

Go

oneHour := time.Duration(1) * time.Hour
badge := 42
message := &messaging.Message{
	Notification: &messaging.Notification{
		Title: "$GOOG up 1.43% on the day",
		Body:  "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
	},
	Android: &messaging.AndroidConfig{
		TTL: &oneHour,
		Notification: &messaging.AndroidNotification{
			Icon:  "stock_ticker_update",
			Color: "#f45342",
		},
	},
	APNS: &messaging.APNSConfig{
		Payload: &messaging.APNSPayload{
			Aps: &messaging.Aps{
				Badge: &badge,
			},
		},
	},
	Topic: "industry-tech",
}

C#

var message = new Message
{
    Notification = new Notification()
    {
        Title = "$GOOG up 1.43% on the day",
        Body = "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
    },
    Android = new AndroidConfig()
    {
        TimeToLive = TimeSpan.FromHours(1),
        Notification = new AndroidNotification()
        {
            Icon = "stock_ticker_update",
            Color = "#f45342",
        },
    },
    Apns = new ApnsConfig()
    {
        Aps = new Aps()
        {
            Badge = 42,
        },
    },
    Topic = "industry-tech",
};

REST

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

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

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 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 szacowany wpływ wrażenia wizualnego na urządzenie 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: powiadomienie 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 szacowany efekt wizualny na urządzenie 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"
      }
    ]
   }
}

Pamiętaj, że obie wiadomości mają ten sam kod i ten sam stan, ale tablica details zawiera wartości różnych typów. Pierwszy przykład zawiera typ type.googleapis.com/google.rpc.BadRequest, który wskazuje błąd w wartościach żądań. W drugim przykładzie typu type.googleapis.com/google.firebase.fcm.v1.FcmError występuje błąd związany z FCM. W przypadku wielu błędów tablica details zawiera informacje, które trzeba debugować i znaleźć rozwiązanie.

W tabeli poniżej znajdziesz kody błędów interfejsu API REST FCM w wersji 1 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 on zgodny z tokenem rejestracji, który aplikacja kliencka otrzymuje po 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ą właściwą nazwę i typ.
UNREGISTERED (kod błędu HTTP = 404) Wystąpienie aplikacji zostało wyrejestrowane z FCM. Zwykle oznacza to, że użyty token stracił ważność i trzeba 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.
Nie zarejestrowano: istniejący token rejestracji może przestać być ważny w wielu sytuacjach, między innymi:
– jeśli aplikacja kliencka wyrejestruje się z FCM;
– jeśli aplikacja kliencka została automatycznie wyrejestrowana, co może nastąpić po odinstalowaniu aplikacji przez użytkownika. Na przykład w systemie iOS, jeśli usługa opinii APNs zgłosiła token APNs jako nieprawidłowy.
– jeśli token rejestracji wygaśnie (np. Google może odświeżyć tokeny rejestracji lub token APNs wygasł w przypadku urządzeń z iOS).
– Jeśli aplikacja kliencka jest zaktualizowana, ale nowa wersja nie jest skonfigurowana do odbierania wiadomości.
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 dla tokena rejestracji. Token rejestracji jest powiązany z określoną grupą nadawców. Gdy aplikacja kliencka 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 w przypadku celu 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.
Przekroczono liczbę wiadomości: częstotliwość wysyłania wiadomości jest za 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 do tego urządzenia i użyj wykładniczego ponawiania, aby spróbować ponownie wysłać pocztę.
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 tym temacie i użyj wykładniczego czasu do ponowienia z minimalnym opóźnieniem początkowym wynoszącym 1 minutę, aby spróbować ponownie 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 ponowić tę samą prośbę zgodnie z sugestiami w sekcji 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) nie ma certyfikatu APNs lub klucza uwierzytelniania push push, Nie udało się wysłać wiadomości kierowanej na urządzenie z iOS ani rejestracji push. 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 FCM API Firebase dla administratora i 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 z danymi zawiera nieprawidłowy klucz. Informacje o kluczach z ograniczeniami znajdziesz w dokumentacji referencyjnej DataMessagePayload.
messaging/payload-size-limit-exceeded Podany ładunek wiadomości przekracza limity rozmiaru w FCM. Limit dla większości wiadomości to 4096 bajtów. Limit wiadomości wysyłanych do tematów 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 go ani nie dodawaj do niego dodatkowych znaków.
messaging/registration-token-not-registered Podany token rejestracji nie został zarejestrowany. Token rejestracji, który wcześniej był prawidłowy, może zostać wyrejestrowany z różnych powodów. Oto niektóre z nich:
  • Aplikacja kliencka wyrejestrowała się z FCM.
  • Aplikacja kliencka została automatycznie wyrejestrowana. Może się tak zdarzyć, jeśli użytkownik odinstaluje aplikację lub, na platformach Apple, gdy usługa opinii APNs zgłosi token APNs jako 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 Odsetek wiadomości do określonego celu jest zbyt duży. Zmniejsz liczbę wiadomości wysyłanych do tego urządzenia lub tematu i nie ponawiaj próby wysłania go do tego miejsca docelowego.
messaging/device-message-rate-exceeded Częstotliwość wiadomości do konkretnego urządzenia jest za duża. Zmniejsz liczbę wiadomości wysyłanych do tego urządzenia i nie ponawiaj próby wysłania na to urządzenie.
messaging/topics-message-rate-exceeded Częstotliwość wiadomości do subskrybentów określonego tematu jest zbyt duża. Zmniejsz liczbę wiadomości wysyłanych w tym temacie i nie ponawiaj próby wysłania wiadomości do tego tematu.
messaging/too-many-topics Token rejestracji zasubskrybował maksymalną liczbę 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 komunikatów do urządzenia odpowiadającego 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 pakietów SDK Firebase Admin.
messaging/authentication-error Pakiet SDK nie mógł uwierzytelnić się na serwerach FCM. Pamiętaj, aby uwierzytelnić pakiet SDK Firebase Admin za pomocą danych logowania, które mają odpowiednie uprawnienia do wysyłania wiadomości w FCM. Przeczytaj artykuł Dodawanie Firebase do aplikacji, aby zapoznać się z dokumentacją dotyczącą uwierzytelniania pakietów SDK Firebase Admin.
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 jest on zawarty w odpowiedzi serwera połączenia FCM.
  • Wdróż wykładniczy czas ponowienia w mechanizmie ponawiania. Jeśli na przykład upłynęło 1 sekundę przed pierwszą próbą, poczekaj co najmniej 2 sekundy przed kolejną próbą, potem 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.
Nadawcy, którzy powodują problemy, mogą zostać umieszczone na czarnej liście.
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 Został zwrócony nieznany błąd serwera. Więcej informacji znajdziesz w nieprzetworzonej 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 związanego z raportem o błędzie.

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

Jeśli korzystasz obecnie ze starszych protokołów, utwórz żądania wiadomości w sposób pokazany w tej sekcji. Pamiętaj, że jeśli wysyłasz wiadomości na wiele platform przez 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 dotyczącej Twojej platformy.

Żądanie HTTP POST

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{ "data": {
    "score": "5x1",
    "time": "15:10"
  },
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}

Odpowiedź HTTP

{ "multicast_id": 108,
  "success": 1,
  "failure": 0,
  "results": [
    { "message_id": "1:08" }
  ]
}

Komunikat XMPP

<message id="">
  <gcm xmlns="google:mobile:data">
    { "data": {
      "score": "5x1",
      "time": "15:10"
    },
    "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  }
  </gcm>
</message>

Odpowiedź XMPP

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "from":"REGID",
      "message_id":"m-1366082849205"
      "message_type":"ack"
  }
  </gcm>
</message>

Serwer połączenia XMPP oferuje inne opcje odpowiedzi. Zobacz Format odpowiedzi serwera.

Pełną listę opcji komunikatów dostępnych podczas wysyłania kolejnych wiadomości do aplikacji klienckich znajdziesz w informacjach referencyjnych dotyczących wybranego protokołu serwera połączenia, czyli HTTP lub XMPP.

Wysyłaj wiadomości do tematów

Wysyłanie wiadomości do tematu Komunikacji w chmurze Firebase (FCM) jest bardzo podobne do wysyłania wiadomości na poszczególne urządzenia lub do grupy użytkowników. Serwer aplikacji ustawia klucz to na wartość taką jak /topics/yourTopic. Deweloperzy 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)

FCM najpierw ocenia 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. Efekt:

  • Tematy A i B
  • Tematy A i TopicC

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

Żądanie HTTP POST tematu

Wyślij 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 dotycząca tematu

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

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

Komunikat XMPP z tematu

Wyślij 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>

Temat – odpowiedź XMPP

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

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

Po pomyślnym lub niepowodzeniu odpowiedzi serwera FCM na żądania wysyłane przez temat może upłynąć do 30 sekund. 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ą wycofanych starszych interfejsów API jest bardzo podobne do wysyłania wiadomości na pojedyncze urządzenia. Ustaw parametr to na unikalny klucz powiadomień dla grupy urządzeń. 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 powodzenia – z notification_key powiązane są 2 tokeny rejestracji i do obu z nich została wysłana wiadomość:

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

Oto przykład „częściowego sukcesu” – z notification_key powiązane są 3 tokeny rejestracji. Komunikat został wysłany tylko na 1 z tokenów rejestracji. Komunikat 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 ponawiać próby w kolejnych próbach.

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

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

Komunikat XMPP grupy urządzeń

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to": "aUniqueKey",
      "message_id": "m-1366082849205" ,
      "data": {
          "hello":"This is a Firebase Cloud Messaging Device Group Message!"
      }
  }
  </gcm>
</message>

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 nie powiodą się wszystkie komunikaty wysłane do wszystkich urządzeń w grupie, serwer połączenia XMPP zwróci odpowiedź 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. Komunikat został wysłany tylko na 1 z tokenów rejestracji. Komunikat 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łączeń FCM nie może dostarczyć wiadomości do wszystkich urządzeń w grupie. Serwer aplikacji otrzyma odpowiedź nack.

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

Starsze metody wysyłania w pakiecie Firebase Admin SDK

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

Wysyłaj na poszczególne urządzenia

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

Node.js

// This registration token comes from the client FCM SDKs.
const registrationToken = 'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...';

// See the "Defining the message payload" section below for details
// on how to define a message payload.
const payload = {
  data: {
    score: '850',
    time: '2:45'
  }
};

// Send a message to the device corresponding to the provided
// registration token.
getMessaging().sendToDevice(registrationToken, payload)
  .then((response) => {
    // See the MessagingDevicesResponse reference documentation for
    // the contents of response.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Metoda sendToDevice() może też 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ę rozstrzygniętą za pomocą obiektu MessagingDevicesResponse zawierającego odpowiedź z FCM. Zwracany typ ma ten sam format podczas przekazywania pojedynczego tokena rejestracji lub tablicy tokenów rejestracji.

Niektóre przypadki, takie jak błąd uwierzytelniania lub ograniczenie liczby żądań, powodują niepowodzenie przetworzenia całej wiadomości. W takich przypadkach obietnica zwrócona przez funkcję sendToDevice() 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 w interfejsie FCM API w interfejsie 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ę rozstrzygniętą za pomocą obiektu MessagingDevicesResponse zawierającego odpowiedź z FCM.

Niektóre przypadki, takie jak błąd uwierzytelniania lub ograniczenie liczby żądań, powodują niepowodzenie przetworzenia 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 w interfejsie FCM API w interfejsie 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 powiadomienia, jak i wiadomości z danymi. Możesz określić jeden lub oba typy wiadomości, tworząc obiekt za pomocą kluczy data i / lub notification. 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.'
  }
};

Wiadomość z danymi

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 dokumentacji referencyjnej DataMessagePayload.

Definiowanie opcji wiadomości

Powyższe metody oparte na starszych protokołach FCM akceptują opcjonalny trzeci argument określający opcje wiadomości. Na przykład w tym przykładzie wysyła się wiadomość o wysokim priorytecie do urządzenia, które wygasa po 24 godzinach:

Node.js

// This registration token comes from the client FCM SDKs.
const registrationToken = 'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...';

// See the "Defining the message payload" section above for details
// on how to define a message payload.
const payload = {
  notification: {
    title: 'Urgent action needed!',
    body: 'Urgent action is needed to prevent your account from being disabled!'
  }
};

// Set the message as high priority and have it expire after 24 hours.
const options = {
  priority: 'high',
  timeToLive: 60 * 60 * 24
};

// Send a message to the device corresponding to the provided
// registration token with the provided options.
getMessaging().sendToDevice(registrationToken, payload, options)
  .then((response) => {
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Pełną listę dostępnych opcji znajdziesz w dokumentacji referencyjnej MessagingOptions.