Ten dokument zawiera informacje na temat składni XMPP używanej do przekazywania komunikatów między serwerem aplikacji, aplikacjami klienckimi i Firebase Cloud Messaging (FCM). Twój serwer aplikacji musi łączyć się z tymi punktami końcowymi:
// Production fcm-xmpp.googleapis.com:5235 // Testing fcm-xmpp.googleapis.com:5236
Dostępne parametry i opcje dzielą się na następujące kategorie:
- Składnia wiadomości niższej
- Kody odpowiedzi na błędy komunikatów dalszych
- Składnia wiadomości nadrzędnej
- Komunikaty sterujące FCM
Składnia wiadomości niższej
W tej sekcji przedstawiono składnię wysyłania komunikatów podrzędnych.
Dalsze wiadomości XMPP (JSON)
W poniższej tabeli wymieniono elementy docelowe, opcje i ładunek komunikatów XMPP JSON.
Parametr | Stosowanie | Opis | |
---|---|---|---|
Cel | |||
to | Opcjonalnie, ciąg | Ten parametr określa odbiorcę wiadomości. Wartością może być token rejestracji urządzenia, klucz powiadomienia grupy urządzeń lub pojedynczy temat (poprzedzony prefiksem | |
condition | Opcjonalnie, ciąg | Ten parametr określa logiczne wyrażenie warunków, które określają cel komunikatu. Obsługiwany warunek: temat w formacie „twój temat” w tematach. W tej wartości wielkość liter nie jest uwzględniana. Obsługiwane operatory: | |
Opcje | |||
message_id | Wymagane, ciąg | Ten parametr jednoznacznie identyfikuje komunikat w połączeniu XMPP. | |
collapse_key | Opcjonalnie, ciąg | Ten parametr identyfikuje grupę wiadomości (np. z Nie ma gwarancji kolejności wysyłania wiadomości. Uwaga: w danym momencie dozwolone są maksymalnie 4 różne klawisze zwijania. Oznacza to, że FCM może jednocześnie przechowywać 4 różne komunikaty na aplikację kliencką. Jeśli przekroczysz tę liczbę, nie ma gwarancji, które 4 klucze zwinięcia FCM zachowa. | |
priority | Opcjonalnie, ciąg | Ustawia priorytet wiadomości. Prawidłowe wartości to „normalny” i „wysoki”. Na platformach Apple odpowiadają one priorytetom APN 5 i 10. Domyślnie powiadomienia są wysyłane z wysokim priorytetem, a wiadomości z danymi są wysyłane z normalnym priorytetem. Priorytet normalny optymalizuje zużycie baterii aplikacji klienckiej i powinien być używany, chyba że wymagana jest natychmiastowa dostawa. W przypadku wiadomości o normalnym priorytecie aplikacja może odebrać wiadomość z nieokreślonym opóźnieniem. Jeśli wiadomość ma wysoki priorytet, zostanie wysłana natychmiast, a aplikacja może wyświetlić powiadomienie. | |
content_available | Opcjonalnie, wartość logiczna | Na platformach Apple użyj tego pola, aby przedstawić | |
mutable_content | Opcjonalnie wartość logiczna JSON | Na platformach Apple użyj tego pola, aby reprezentować | |
time_to_live | Opcjonalnie, liczba | Ten parametr określa, jak długo (w sekundach) wiadomość powinna być przechowywana w pamięci FCM, jeśli urządzenie jest w trybie offline. Maksymalny obsługiwany czas życia wynosi 4 tygodnie, a wartość domyślna to 4 tygodnie. Aby uzyskać więcej informacji, zobacz Ustawianie czasu życia wiadomości . | |
dry_run | Opcjonalnie, wartość logiczna | Ten parametr, gdy jest ustawiony na Wartość domyślna to | |
Ładunek | |||
data | Opcjonalnie, obiekt | Ten parametr określa pary klucz-wartość ładunku wiadomości. Na przykład z Na platformach Apple, jeśli wiadomość jest dostarczana przez APN, reprezentuje niestandardowe pola danych. Jeśli jest dostarczany przez FCM, jest reprezentowany jako słownik wartości klucza w W systemie Android skutkuje to dodatkowym nazwanym Klucz nie powinien być słowem zastrzeżonym („from”, „typ_wiadomości” ani żadnym słowem zaczynającym się od „google” lub „gcm”). Nie używaj żadnych słów zdefiniowanych w tej tabeli (takich jak Zalecane są wartości w typach łańcuchowych. Musisz przekonwertować wartości w obiektach lub innych typach danych niebędących ciągami znaków (np. liczby całkowite lub wartości logiczne) na ciąg znaków. | |
notification | Opcjonalnie, obiekt | Ten parametr określa wstępnie zdefiniowane, widoczne dla użytkownika pary klucz-wartość ładunku powiadomienia. Aby uzyskać szczegółowe informacje, zobacz Obsługa ładunku powiadomień. Aby uzyskać więcej informacji na temat opcji wiadomości powiadamiających i wiadomości z danymi, zobacz Typy wiadomości . Jeśli dostarczono ładunek powiadomienia lub opcja content_available jest ustawiona na true dla wiadomości kierowanej do urządzenia Apple, wiadomość jest wysyłana za pośrednictwem APN , w przeciwnym razie jest wysyłana za pośrednictwem FCM. |
Obsługa ładunku powiadomień
W poniższych tabelach wymieniono predefiniowane klucze dostępne do tworzenia komunikatów powiadomień dla platform Apple i Android.
Parametr | Stosowanie | Opis |
---|---|---|
title | Opcjonalnie, ciąg | Tytuł powiadomienia. To pole nie jest widoczne na telefonach i tabletach. |
body | Opcjonalnie, ciąg | Treść powiadomienia. |
sound | Opcjonalnie, ciąg | Dźwięk odtwarzany, gdy urządzenie odbierze powiadomienie. Ciąg określający pliki dźwiękowe w głównym pakiecie aplikacji klienckiej lub w folderze |
badge | Opcjonalnie, ciąg | Wartość odznaki na ikonie aplikacji na ekranie głównym. Jeśli nie określono inaczej, odznaka nie ulega zmianie. Jeśli ustawione na |
click_action | Opcjonalnie, ciąg | Akcja powiązana z kliknięciem przez użytkownika powiadomienia. Odpowiada |
subtitle | Opcjonalnie, ciąg | Podtytuł powiadomienia. |
body_loc_key | Opcjonalnie, ciąg | Klucz do ciągu treści w zasobach ciągu aplikacji, który ma być używany do lokalizowania tekstu treści w bieżącej lokalizacji użytkownika. Odpowiada Aby uzyskać więcej informacji, zobacz Informacje o kluczu ładunku i Lokalizowanie zawartości zdalnych powiadomień . |
body_loc_args | Opcjonalnie tablica JSON jako ciąg znaków | Zmienne wartości ciągu, które mają być używane zamiast specyfikatorów formatu w Odpowiada Aby uzyskać więcej informacji, zobacz Informacje o kluczu ładunku i Lokalizowanie zawartości zdalnych powiadomień . |
title_loc_key | Opcjonalnie, ciąg | Klucz do ciągu tytułu w zasobach ciągu aplikacji, który ma być używany do lokalizowania tekstu tytułu w bieżącej lokalizacji użytkownika. Odpowiada Aby uzyskać więcej informacji, zobacz Informacje o kluczu ładunku i Lokalizowanie zawartości zdalnych powiadomień . |
title_loc_args | Opcjonalnie tablica JSON jako ciąg znaków | Zmienne wartości ciągów, które mają być używane zamiast specyfikatorów formatu w Odpowiada Aby uzyskać więcej informacji, zobacz Informacje o kluczu ładunku i Lokalizowanie zawartości zdalnych powiadomień . |
Parametr | Stosowanie | Opis |
---|---|---|
title | Opcjonalnie, ciąg | Tytuł powiadomienia. |
body | Opcjonalnie, ciąg | Treść powiadomienia. |
android_channel_id | Opcjonalnie, ciąg | Identyfikator kanału powiadomienia (nowość w Androidzie O). Aplikacja musi utworzyć kanał z tym identyfikatorem kanału, zanim otrzymane zostanie powiadomienie z tym identyfikatorem kanału. Jeśli nie wyślesz tego identyfikatora kanału w żądaniu lub jeśli podany identyfikator kanału nie został jeszcze utworzony przez aplikację, FCM użyje identyfikatora kanału określonego w manifeście aplikacji. |
icon | Opcjonalnie, ciąg | Ikona powiadomienia. Ustawia ikonę powiadomienia na |
sound | Opcjonalnie, ciąg | Dźwięk odtwarzany, gdy urządzenie odbierze powiadomienie. Obsługuje |
tag | Opcjonalnie, ciąg | Identyfikator używany do zastąpienia istniejących powiadomień w szufladzie powiadomień. Jeśli nie określono, każde żądanie tworzy nowe powiadomienie. Jeśli zostało to określone, a powiadomienie z tym samym tagiem jest już wyświetlane, nowe powiadomienie zastępuje istniejące w szufladzie powiadomień. |
color | Opcjonalnie, ciąg | Kolor ikony powiadomienia wyrażony w formacie |
click_action | Opcjonalnie, ciąg | Akcja powiązana z kliknięciem przez użytkownika powiadomienia. Jeśli określono, działanie z pasującym filtrem intencji zostanie uruchomione, gdy użytkownik kliknie powiadomienie. |
body_loc_key | Opcjonalnie, ciąg | Klucz do ciągu treści w zasobach ciągu aplikacji, który ma być używany do lokalizowania tekstu treści w bieżącej lokalizacji użytkownika. Aby uzyskać więcej informacji, zobacz Zasoby ciągów . |
body_loc_args | Opcjonalnie tablica JSON jako ciąg znaków | Zmienne wartości ciągu, które mają być używane zamiast specyfikatorów formatu w Aby uzyskać więcej informacji, zobacz Formatowanie i stylizacja . |
title_loc_key | Opcjonalnie, ciąg | Klucz do ciągu tytułu w zasobach ciągu aplikacji, który ma być używany do lokalizowania tekstu tytułu w bieżącej lokalizacji użytkownika. Aby uzyskać więcej informacji, zobacz Zasoby ciągów . |
title_loc_args | Opcjonalnie tablica JSON jako ciąg znaków | Zmienne wartości ciągów, które mają być używane zamiast specyfikatorów formatu w Aby uzyskać więcej informacji, zobacz Formatowanie i stylizacja . |
Parametr | Stosowanie | Opis |
---|---|---|
title | Opcjonalnie, ciąg | Tytuł powiadomienia. |
body | Opcjonalnie, ciąg | Treść powiadomienia. |
icon | Opcjonalnie, ciąg | Adres URL ikony powiadomienia. |
click_action | Opcjonalnie, ciąg | Akcja powiązana z kliknięciem przez użytkownika powiadomienia. W przypadku wszystkich wartości adresów URL wymagany jest protokół HTTPS. |
Zinterpretuj odpowiedź na dalszy komunikat XMPP
W poniższej tabeli wymieniono pola, które pojawiają się w odpowiedzi na komunikat XMPP.
Parametr | Stosowanie | Opis |
---|---|---|
from | Wymagane, ciąg | Ten parametr określa, kto wysłał tę odpowiedź. Wartością jest token rejestracji aplikacji klienckiej. |
message_id | Wymagane, ciąg | Ten parametr jednoznacznie identyfikuje komunikat w połączeniu XMPP. Wartość jest ciągiem znaków, który jednoznacznie identyfikuje powiązany komunikat. |
message_type | Wymagane, ciąg | Ten parametr określa wiadomość Jeśli wartość jest ustawiona na |
error | Opcjonalnie, ciąg | Ten parametr określa błąd związany z komunikatem końcowym. Jest ustawiany, gdy message_type ma nack . Szczegółowe informacje można znaleźć w tabeli 4 . |
error_description | Opcjonalnie, ciąg | Ten parametr zawiera informacje opisowe dotyczące błędu. Jest ustawiany, gdy message_type ma nack . |
Kody odpowiedzi na błędy komunikatów dalszych
W poniższej tabeli wymieniono kody odpowiedzi na błędy dla komunikatów dalszych.
Błąd | Kod XMPP | Rekomendowane działanie |
---|---|---|
Brak tokena rejestracyjnego | INVALID_JSON | Sprawdź, czy żądanie zawiera token rejestracji (w polu registration_id w wiadomości tekstowej lub w polu to lub registration_ids w formacie JSON). |
Nieprawidłowa rejestracja APN | INVALID_JSON | W przypadku rejestracji w systemie iOS sprawdź, czy żądanie rejestracji od klienta zawiera prawidłowy token APNs i identyfikator aplikacji. |
Nieprawidłowy token rejestracyjny | BAD_REGISTRATION | Sprawdź format tokena rejestracyjnego przekazywanego do serwera. Upewnij się, że jest zgodny z tokenem rejestracji, który aplikacja kliencka otrzymuje podczas rejestracji w FCM. Nie obcinaj ani nie dodawaj dodatkowych znaków. |
Niezarejestrowane urządzenie | DEVICE_UNREGISTERED | Istniejący token rejestracyjny może utracić ważność w wielu scenariuszach, w tym:
|
Niedopasowany nadawca | SENDER_ID_MISMATCH | Token rejestracyjny 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. Podczas wysyłania wiadomości do aplikacji klienckiej należy używać jednego z tych identyfikatorów nadawcy. Jeśli zmienisz nadawcę, istniejące tokeny rejestracyjne przestaną działać. |
Nieprawidłowy JSON | INVALID_JSON | Sprawdź, czy wiadomość JSON jest poprawnie sformatowana i zawiera prawidłowe pola (np. upewnij się, że przekazywany jest właściwy typ danych). |
Wiadomość jest zbyt duża | INVALID_JSON | Sprawdź, czy całkowity rozmiar danych zawartych w wiadomości nie przekracza limitów FCM: 4096 bajtów dla 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 | INVALID_JSON | Sprawdź, czy dane ładunku nie zawierają klucza (takiego jak from , gcm lub jakakolwiek wartość poprzedzona przez google ) używanego wewnętrznie przez FCM. Należy zauważyć, że niektóre słowa (takie jak collapse_key ) są również używane przez FCM, ale są dozwolone w ładunku, w którym to przypadku wartość ładunku zostaje zastąpiona wartością FCM. |
Nieprawidłowy czas życia | INVALID_JSON | Sprawdź, czy wartość użyta w time_to_live jest liczbą całkowitą reprezentującą czas trwania w sekundach z zakresu od 0 do 2 419 200 (4 tygodnie). |
Zła wiadomość ACK | BAD_ACK | Przed ponowną próbą sprawdź, czy wiadomość ack jest prawidłowo sformatowana. Szczegółowe informacje można znaleźć w tabeli 6 . |
Koniec czasu | SERVICE_UNAVAILABLE | Serwer nie mógł przetworzyć żądania na czas. Ponów tę samą prośbę, ale musisz:
Uwaga: nadawcy powodujący problemy mogą zostać umieszczeni na czarnej liście. |
Wewnętrzny błąd serwera | INTERNAL_SERVER_ | Serwer napotkał błąd podczas próby przetworzenia żądania. Możesz ponowić tę samą prośbę, spełniając wymagania wymienione w „Limicie czasu” (patrz wiersz powyżej). |
Przekroczono częstotliwość komunikatów urządzenia | DEVICE_MESSAGE_RATE | Szybkość wysyłania wiadomości do określonego urządzenia jest zbyt wysoka. Zmniejsz liczbę wiadomości wysyłanych na to urządzenie i nie próbuj natychmiast wysyłać wiadomości na to urządzenie. |
Przekroczono częstotliwość wiadomości w tematach | TOPICS_MESSAGE_RATE | Liczba wiadomości do subskrybentów na dany temat jest zbyt wysoka. Zmniejsz liczbę wiadomości wysyłanych w tym temacie i nie próbuj od razu wysyłać ponownie. |
Opróżnianie połączenia | CONNECTION_DRAINING | Nie można przetworzyć wiadomości, ponieważ połączenie się wyczerpuje. Dzieje się tak, ponieważ okresowo FCM musi zamknąć połączenie, aby przeprowadzić równoważenie obciążenia. Spróbuj ponownie wysłać wiadomość przez inne połączenie XMPP. |
Nieprawidłowe dane uwierzytelniające APN | INVALID_APNS_CREDENTIAL | Nie można wysłać wiadomości kierowanej do urządzenia z systemem iOS, ponieważ wymagany klucz uwierzytelniający APN nie został przesłany lub wygasł. Sprawdź ważność swoich uprawnień programistycznych i produkcyjnych. |
Uwierzytelnianie nie powiodło się | AUTHENTICATION_FAILED | Nie udało się uwierzytelnić w zewnętrznych usługach push. Sprawdź, czy korzystasz z właściwych certyfikatów web push. |
Składnia wiadomości nadrzędnej
Komunikat nadrzędny to komunikat wysyłany przez aplikację kliencką do serwera aplikacji. Obecnie tylko XMPP obsługuje przesyłanie wiadomości typu upstream. Więcej informacji na temat wysyłania wiadomości z aplikacji klienckich można znaleźć w dokumentacji swojej platformy.
Interpretowanie nadrzędnego komunikatu XMPP
W poniższej tabeli opisano pola w sekcji XMPP wygenerowane przez FCM w odpowiedzi na żądania komunikatów nadrzędnych z aplikacji klienckich.
Parametr | Stosowanie | Opis |
---|---|---|
from | Wymagane, ciąg | Ten parametr określa, kto wysłał wiadomość. Wartością jest token rejestracji aplikacji klienckiej. |
category | Wymagane, ciąg | Ten parametr określa nazwę pakietu aplikacji klienckiej, która wysłała wiadomość. |
message_id | Wymagane, ciąg | Ten parametr określa unikalny identyfikator wiadomości. |
data | Opcjonalnie, ciąg | Ten parametr określa pary klucz-wartość ładunku wiadomości. |
Wysyłanie wiadomości ACK
W poniższej tabeli opisano odpowiedź ACK, którą serwer aplikacji ma wysłać do FCM w odpowiedzi na komunikat nadrzędny odebrany przez serwer aplikacji.
Parametr | Stosowanie | Opis |
---|---|---|
to | Wymagane, ciąg | Ten parametr określa odbiorcę wiadomości zwrotnej. Wartość musi być tokenem rejestracji aplikacji klienckiej, która wysłała komunikat nadrzędny. |
message_id | Wymagane, ciąg | Ten parametr określa, do jakiego komunikatu przeznaczona jest odpowiedź. Wartość musi być wartością message_id z odpowiedniego komunikatu nadrzędnego. |
message_type | Wymagane, ciąg | Ten parametr określa wiadomość ack z serwera aplikacji do CCS. W przypadku wiadomości nadrzędnych należy zawsze ustawić opcję ack . |
Komunikaty serwera FCM (XMPP)
To jest wiadomość wysłana z FCM do serwera aplikacji. Oto podstawowe typy komunikatów wysyłanych przez FCM do serwera aplikacji:
- Kontrola: te komunikaty generowane przez CCS wskazują, że wymagane jest działanie ze strony serwera aplikacji.
W poniższej tabeli opisano pola zawarte w komunikatach wysyłanych przez usługę CCS do serwera aplikacji.
Parametr | Stosowanie | Opis |
---|---|---|
Wspólne pole | ||
message_type | Wymagane, ciąg | Parametr ten określa typ komunikatu: control. Gdy jest ustawiony na |
control_type | Opcjonalnie, ciąg | Ten parametr określa typ komunikatu sterującego wysyłanego z FCM. Obecnie obsługiwane jest tylko |