Ten dokument zawiera informacje na temat składni XMPP używanej do przekazywania wiadomości między serwerem aplikacji, aplikacjami klienckimi i Firebase Cloud Messaging (FCM). 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 są podzielone na te kategorie:
- Składnia wiadomości przesyłanych dalej
- Kody odpowiedzi na błędy wiadomości przesyłanych dalej
- Składnia wiadomości przesyłanych do usługi
- FCM wiadomości kontrolnych
Składnia wiadomości przesyłanych dalej
Ta sekcja zawiera składnię wysyłania wiadomości do kolejnych węzłów.
komunikaty XMPP w dół łańcucha (JSON);
Tabela poniżej zawiera listę docelowych, opcji i danych w wiadomościach XMPP JSON.
Parametr | Wykorzystanie | Opis | |
---|---|---|---|
Cel | |||
to |
Opcjonalny, ciąg znaków |
Ten parametr określa odbiorcę wiadomości.
Wartość może być tokenem rejestracji urządzenia, kluczem powiadomienia grupy urządzeń lub pojedynczym tematem (z przedrostkiem |
|
condition |
Opcjonalny, ciąg znaków | Ten parametr określa wyrażenie logiczne warunków, które określają docelowego odbiorcę wiadomości. Obsługiwany warunek: temat, sformatowany jako „temat w sekcji Tematy”. Wielkość liter w tej wartości nie ma znaczenia. Obsługiwane operatory: |
|
Opcje | |||
message_id |
Wymagane, ciąg znaków | Ten parametr jednoznacznie identyfikuje wiadomość w połączeniu XMPP. |
|
collapse_key |
Opcjonalny, ciąg znaków | Ten parametr identyfikuje grupę wiadomości (np. z Nie ma gwarancji kolejności wysyłania wiadomości. Uwaga: w danym momencie można użyć maksymalnie 4 różne klucze zwijania. Oznacza to, że FCM może jednocześnie przechowywać 4 różne wiadomości na aplikację klienta. Jeśli przekroczysz tę liczbę, nie będziesz mieć pewności, które 4 klucze FCM zostaną zachowane. |
|
priority |
Opcjonalny, ciąg znaków | Określa priorytet wiadomości. Prawidłowe wartości to „normal” i „high”. Na platformach Apple odpowiadają one priorytetom APN 5 i 10. Domyślnie wiadomości z powiadomieniami są wysyłane z wysokim priorytetem, a wiadomości z danymi – z normalnym priorytetem. Priorytet normalny optymalizuje zużycie baterii przez aplikację kliencką i powinien być używany, chyba że wymagana jest natychmiastowa dostawa. W przypadku wiadomości o normalnym priorytecie aplikacja może otrzymać wiadomość z nieokreślonym opóźnieniem. Gdy wiadomość jest wysyłana z wysokim priorytetem, jest wysyłana natychmiast, a aplikacja może wyświetlić powiadomienie. |
|
content_available |
Opcjonalna, logiczna | Na platformach Apple to pole reprezentuje wartość |
|
mutable_content |
Opcjonalny, logiczny element JSON | Na platformach Apple to pole reprezentuje wartość |
|
time_to_live |
Opcjonalnie, liczba | Ten parametr określa, jak długo (w sekundach) wiadomość powinna być przechowywana w magazynie FCM, jeśli urządzenie jest offline. Maksymalny czas w przypadku obsługiwanego okresu ważności to 4 tygodnie, a wartość domyślna to 4 tygodnie. Więcej informacji znajdziesz w artykule Ustawianie czasu trwania wiadomości. |
|
dry_run |
Opcjonalna, logiczna | Gdy ten parametr ma wartość Wartością domyślną jest |
|
Ładunek | |||
data |
Opcjonalnie, obiekt | Ten parametr określa pary klucz-wartość ładunku wiadomości. Na przykład Na platformach Apple, jeśli wiadomość jest dostarczana przez APN, reprezentuje ona pola danych niestandardowych. Jeśli jest dostarczana przez FCM, jest reprezentowana jako słownik klucz-wartość w W przypadku Androida powoduje to utworzenie dodatkowego parametru o nazwie Klucz nie powinien być słowem zastrzeżonym (np. „from”, „message_type” ani żadnym słowem rozpoczynającym się od „google” lub „gcm”). Nie używaj żadnych słów zdefiniowanych w tej tabeli (np. Zalecamy stosowanie wartości typu ciąg tekstowy. Musisz przekonwertować wartości w obiektach lub innych typach danych innych niż ciąg 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ść w danych powiadomienia. Szczegółowe informacje znajdziesz w sekcji dotyczącej obsługi ładunku powiadomienia. Więcej informacji o opcjach wiadomości z powiadomieniem i wiadomości danych znajdziesz w artykule
Typy wiadomości. Jeśli podano dane payload powiadomienia lub opcja content_available jest ustawiona na true w przypadku wiadomości wysyłanej na urządzenie Apple, wiadomość jest wysyłana przez APN, w przeciwnym razie jest wysyłana przez FCM.
|
Obsługa danych powiadomienia
W poniższych tabelach znajdziesz listę wstępnie zdefiniowanych kluczy, które możesz wykorzystać do tworzenia wiadomości powiadomień na platformach Apple i Android.
Parametr | Wykorzystanie | Opis |
---|---|---|
title |
Opcjonalny, ciąg znaków |
Tytuł powiadomienia. To pole jest niewidoczne na telefonach i tabletach. |
body |
Opcjonalny, ciąg znaków |
Treść powiadomienia. |
sound |
Opcjonalny, ciąg znaków |
Dźwięk odtwarzany, gdy urządzenie otrzyma powiadomienie.
Ciąg znaków określający pliki dźwiękowe w głównym pakiecie aplikacji klienckiej lub w folderze
|
badge |
Opcjonalny, ciąg znaków |
Wartość plakietki na ikonie aplikacji na ekranie głównym. Jeśli nie określisz tu żadnej wartości, plakietka nie ulegnie zmianie.
Jeśli ma wartość |
click_action |
Opcjonalny, ciąg znaków |
Działanie powiązane z kliknięciem powiadomienia przez użytkownika.
Odpowiada wartości |
subtitle |
Opcjonalny, ciąg znaków |
Podtytuł powiadomienia. |
body_loc_key |
Opcjonalny, ciąg znaków |
Klucz do ciągu tekstowego w zasobach ciągów tekstowych aplikacji, który służy do zlokalizowania tekstu w ramach bieżącej lokalizacji użytkownika.
Odpowiada wartości Więcej informacji znajdziesz w artykule Referencje dotyczące klucza danych payload i Lokalizacja treści powiadomień zdalnych. |
body_loc_args |
Opcjonalnie tablica JSON jako ciąg znaków |
Wartości zmiennych tekstowych, które mają być używane zamiast specyfikatorów formatu w elemencie
Odpowiada wartości Więcej informacji znajdziesz w artykule Referencje dotyczące klucza danych payload i Lokalizacja treści powiadomień zdalnych. |
title_loc_key |
Opcjonalny, ciąg znaków |
Klucz do ciągu znaków tytułu w zasobach ciągu znaków aplikacji, który służy do zlokalizowania tekstu tytułu w zależności od bieżącej lokalizacji użytkownika.
Odpowiada wartości Więcej informacji znajdziesz w artykule Referencje dotyczące klucza danych payload i Tłumaczenie treści powiadomień zdalnych. |
title_loc_args |
Opcjonalnie tablica JSON jako ciąg znaków |
zmienne wartości ciągu znaków, które mają być używane zamiast specyfikatorów formatu w elementach
Odpowiada wartości Więcej informacji znajdziesz w artykule Referencje dotyczące klucza danych payload i Lokalizacja treści powiadomień zdalnych. |
Parametr | Wykorzystanie | Opis |
---|---|---|
title |
Opcjonalny, ciąg znaków |
Tytuł powiadomienia. |
body |
Opcjonalny, ciąg znaków |
Treść powiadomienia. |
android_channel_id |
Opcjonalny, ciąg znaków |
Identyfikator kanału powiadomienia (nowy w Androidzie O). Aplikacja musi utworzyć kanał z tym identyfikatorem, zanim zostanie odebrane jakiekolwiek powiadomienie z tym identyfikatorem. Jeśli nie prześlesz tego identyfikatora kanału w żądaniu lub jeśli aplikacja nie utworzyła jeszcze podanego identyfikatora, FCMużyje identyfikatora kanału określonego w pliku manifestu aplikacji. |
icon |
Opcjonalny, ciąg znaków |
Ikona powiadomienia.
Ustawia ikonę powiadomienia na |
sound |
Opcjonalny, ciąg znaków |
Dźwięk odtwarzany, gdy urządzenie otrzyma powiadomienie.
Obsługuje |
tag |
Opcjonalny, ciąg znaków |
Identyfikator używany do zastępowania istniejących powiadomień w panelu powiadomień. Jeśli nie zostanie określone inaczej, każda prośba powoduje utworzenie nowego powiadomienia. Jeśli jest ono określone i powiadomienie z tym samym tagiem jest już wyświetlane, nowe powiadomienie zastąpi dotychczasowe w schowku powiadomień. |
color |
Opcjonalny, ciąg znaków |
Kolor ikony powiadomienia wyrażony w formacie |
click_action |
Opcjonalny, ciąg znaków |
Działanie powiązane z kliknięciem powiadomienia przez użytkownika. Jeśli to możliwe, po kliknięciu powiadomienia uruchamiana jest aktywność z odpowiednim filtrem intencji. |
body_loc_key |
Opcjonalny, ciąg znaków |
Klucz do ciągu tekstowego w zasobach ciągów tekstowych aplikacji, który służy do zlokalizowania tekstu w ramach bieżącej lokalizacji użytkownika. Więcej informacji znajdziesz w zasobach napisów. |
body_loc_args |
Opcjonalnie tablica JSON jako ciąg znaków |
Wartości zmiennych tekstowych, które mają być używane zamiast specyfikatorów formatu w elemencie Więcej informacji znajdziesz w sekcji Formatowanie i stylowanie. |
title_loc_key |
Opcjonalny, ciąg znaków |
Klucz do ciągu znaków tytułu w zasobach ciągu znaków aplikacji, który służy do zlokalizowania tekstu tytułu w zależności od bieżącej lokalizacji użytkownika. Więcej informacji znajdziesz w zasobach napisów. |
title_loc_args |
Opcjonalnie tablica JSON jako ciąg znaków |
zmienne wartości ciągu znaków, które mają być używane zamiast specyfikatorów formatu w elementach Więcej informacji znajdziesz w sekcji Formatowanie i stylowanie. |
Parametr | Wykorzystanie | Opis |
---|---|---|
title |
Opcjonalny, ciąg znaków |
Tytuł powiadomienia. |
body |
Opcjonalny, ciąg znaków |
Treść powiadomienia. |
icon |
Opcjonalny, ciąg znaków |
Adres URL ikony powiadomienia. |
click_action |
Opcjonalny, ciąg znaków |
Działanie powiązane z kliknięciem powiadomienia przez użytkownika. W przypadku wszystkich wartości adresów URL wymagany jest protokół HTTPS. |
Interpretowanie odpowiedzi na wiadomość XMPP z wyższego poziomu
W tabeli poniżej wymieniono pola, które pojawiają się w odpowiedzi na wiadomość XMPP.
Parametr | Wykorzystanie | Opis |
---|---|---|
from |
Wymagane, ciąg znaków | Ten parametr określa, kto wysłał tę odpowiedź. Wartość to token rejestracji aplikacji klienta. |
message_id |
Wymagane, ciąg znaków | Ten parametr jednoznacznie identyfikuje wiadomość w połączeniu XMPP. Wartość to ciąg znaków jednoznacznie identyfikujący powiązaną wiadomość. |
message_type |
Wymagane, ciąg znaków | Ten parametr określa wiadomość Jeśli wartość jest ustawiona na |
error |
Opcjonalny, ciąg znaków | Ten parametr określa błąd związany z komunikatem przekazywanym dalej. Jest ona ustawiana, gdy message_type ma wartość nack . Szczegółowe informacje znajdziesz w tabeli 4. |
error_description |
Opcjonalny, ciąg znaków | Ten parametr zawiera opis błędu. Jest ona ustawiana, gdy message_type to nack . |
Kody odpowiedzi na błędy wiadomości przesyłanych dalej
Tabela poniżej zawiera kody odpowiedzi błędów w przypadku wiadomości przesyłanych dalej.
Błąd | Kod XMPP | Zalecane działanie |
---|---|---|
Brak tokena rejestracji | 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 w APNs | INVALID_JSON |
W przypadku rejestracji na iOS sprawdź, czy żądanie rejestracji wysłane przez klienta zawiera prawidłowy token APN i identyfikator aplikacji. |
Nieprawidłowy token rejestracji | BAD_REGISTRATION |
Sprawdź format tokena rejestracji przekazywanego na serwer. Upewnij się, że token rejestracji jest zgodny z tokenem rejestracji, który aplikacja klienta otrzymuje podczas rejestracji w usłudze FCM. Nie skracaj ani nie dodawaj dodatkowych znaków. |
Niezarejestrowane urządzenie | DEVICE_UNREGISTERED |
Dotychczasowy token rejestracji może przestać być ważny w kilku sytuacjach, między innymi:
|
Niezgodny nadawca | SENDER_ID_MISMATCH |
Token rejestracji jest powiązany z określoną grupą nadawców. Gdy aplikacja kliencka rejestruje się w usłudze 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ę, istniejące tokeny rejestracji nie będą działać. |
Nieprawidłowy plik JSON | INVALID_JSON |
Sprawdź, czy wiadomość JSON jest prawidłowo sformatowana i zawiera prawidłowe pola (np. czy przekazano prawidłowy typ danych). |
Wiadomość jest za duża | INVALID_JSON |
Sprawdź, czy łączny rozmiar danych w Payload 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 | INVALID_JSON |
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 ładunku. W takim przypadku wartość ładunku jest zastępowana wartością FCM. |
Nieprawidłowy czas życia | INVALID_JSON |
Sprawdź, czy wartość użyta w parametrye time_to_live jest liczbą całkowitą reprezentującą czas trwania w sekundach z zakresu od 0 do 2 419 200 (4 tygodnie). |
Nieprawidłowa wiadomość potwierdzenia | BAD_ACK |
Zanim spróbujesz ponownie, sprawdź, czy wiadomość ack jest prawidłowo sformatowana. Szczegółowe informacje znajdziesz w tabeli 6. |
Czas oczekiwania | SERVICE_UNAVAILABLE |
Serwer nie mógł przetworzyć żądania w czasie. Ponownie wyślij to samo żądanie, ale musisz:
Uwaga: nadawcy, którzy powodują problemy, mogą zostać umieszczeni na liście zablokowanych. |
Wewnętrzny błąd serwera | INTERNAL_SERVER_
|
Podczas próby przetworzenia żądania serwer napotkał błąd. Możesz ponownie przesłać tę samą prośbę, przestrzegając wymagań podanych w sekcji „Limit czasu” (patrz wiersz powyżej). |
Przekroczono częstotliwość wysyłania wiadomości z urządzenia | DEVICE_MESSAGE_RATE |
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ć na nie kolejnych wiadomości. |
Przekroczono limit częstotliwości wysyłania wiadomości o tematach | TOPICS_MESSAGE_RATE |
Liczba wiadomości wysyłanych do subskrybentów danego tematu jest zbyt duża. Zmniejsz liczbę wiadomości wysyłanych w ramach tego tematu i nie próbuj ponownie wysyłać wiadomości od razu. |
Zamykanie połączenia | CONNECTION_DRAINING |
Nie udało się przetworzyć wiadomości, ponieważ połączenie jest słabe. Dzieje się tak, ponieważ FCM musi okresowo zamykać połączenie, aby wykonać równoważenie obciążenia. Ponownie wyślij wiadomość przez inne połączenie XMPP. |
Nieprawidłowe dane logowania do APNs | INVALID_APNS_CREDENTIAL |
Nie udało się wysłać wiadomości kierowanej na urządzenie z iOS, ponieważ wymagany klucz uwierzytelniający APN nie został przesłany lub wygasł. Sprawdź poprawność danych logowania do wersji deweloperskiej i produkcyjnej. |
Uwierzytelnianie się nie powiodło się | AUTHENTICATION_FAILED |
Nie udało się uwierzytelnić w zewnętrznych usługach push. Sprawdź, czy używasz prawidłowych certyfikatów web push. |
Składnia wiadomości przesyłanych w górę
Wiadomość w górę to wiadomość wysyłana przez aplikację kliencką do serwera aplikacji. Obecnie tylko XMPP obsługuje wiadomości upstream. Więcej informacji o wysyłaniu wiadomości z aplikacji klienckich znajdziesz w dokumentacji platformy.
Interpretowanie przychodzącej wiadomości XMPP
W tabeli poniżej opisano pola w stanzach XMPP generowanych przez FCM w odpowiedzi na żądania wiadomości od aplikacji klienckich.
Parametr | Wykorzystanie | Opis |
---|---|---|
from |
Wymagane, ciąg znaków | Ten parametr określa, kto wysłał wiadomość. Wartość to token rejestracji aplikacji klienta. |
category |
Wymagane, ciąg znaków | Ten parametr określa nazwę pakietu aplikacji klienta, który wysłał wiadomość. |
message_id |
Wymagane, ciąg znaków | Ten parametr określa unikalny identyfikator wiadomości. |
data |
Opcjonalny, ciąg znaków | Ten parametr określa pary klucz-wartość ładunku wiadomości. |
Wysyłanie wiadomości potwierdzenia
W tabeli poniżej opisano odpowiedź ACK, którą serwer aplikacji powinien wysłać do FCM w odpowiedzi na otrzymaną od niego wiadomość.
Parametr | Wykorzystanie | Opis |
---|---|---|
to |
Wymagane, ciąg znaków | Ten parametr określa odbiorcę wiadomości z odpowiedzią. Wartość musi być tokenem rejestracji aplikacji klienta, która wysłała wiadomość na wyższy poziom. |
message_id |
Wymagane, ciąg znaków | Ten parametr określa, do którego komunikatu ma być wysłana odpowiedź. Wartość musi być wartością message_id z odpowiedniego przesyłanego w górę komunikatu. |
message_type |
Wymagane, ciąg znaków | Ten parametr określa wiadomość ack wysyłaną z serwera aplikacji do CCS.
W przypadku wiadomości przesyłanych w górę zawsze powinna być ustawiona wartość ack . |
FCM wiadomości serwera (XMPP)
To wiadomość wysłana z FCM na serwer aplikacji. Oto podstawowe typy wiadomości, które FCMwysyła do serwera aplikacji:
- Kontrólowanie: te komunikaty generowane przez CCS wskazują, że serwer aplikacji musi podjąć działanie.
W tabeli poniżej opisano pola zawarte w wiadomościach wysyłanych przez CCS do serwera aplikacji.
Parametr | Wykorzystanie | Opis |
---|---|---|
Pole wspólne | ||
message_type |
Wymagane, ciąg znaków | Ten parametr określa typ wiadomości: kontrola. Gdy jest ustawiona wartość |
control_type |
Opcjonalny, ciąg znaków | Ten parametr określa typ wiadomości kontrolnej wysyłanej z FCM. Obecnie obsługiwana jest tylko forma |