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 się łączyć 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 w dalszej części
- Kody odpowiedzi na błędy w komunikatach wyświetlanych w dalszej części wiadomości
- Składnia wiadomości przesyłanych do usługi
- FCM komunikaty kontrolne
Składnia wiadomości przesyłanych dalej
W tej sekcji znajdziesz składnię służącą do wysyłania kolejnych wiadomości.
Kolejne komunikaty XMPP (JSON)
W poniższej tabeli znajdziesz cele, opcje i ładunek dla kodu JSON XMPP wiadomości.
Parametr | Wykorzystanie | Opis | |
---|---|---|---|
Wartość docelowa | |||
to |
Opcjonalnie: ciąg znaków |
Ten parametr określa adresata wiadomości.
Wartością może być token rejestracji urządzenia, identyfikator grupy urządzeń
klucza powiadomień lub pojedynczego tematu (z przedrostkiem
|
|
condition |
Opcjonalny, ciąg znaków | Ten parametr określa wyrażenie logiczne warunków, które określa cel wiadomości. Obsługiwany warunek: temat, sformatowany jako „TwojTemat” w sekcji „Tematy”. Ten Wielkość liter w wartości nie jest rozróżniana. Obsługiwane operatory: |
|
Opcje | |||
message_id |
Wymagane, ciąg znaków | Ten parametr jednoznacznie identyfikuje komunikat w połączeniu XMPP. |
|
collapse_key |
Opcjonalny, ciąg znaków | Ten parametr identyfikuje grupę wiadomości (np. z Nie ma gwarancji kolejności, w jakiej wiadomości są wysyłane. 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 |
Opcjonalnie: 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 powiadomienia są wysyłane z wysokim priorytetem oraz wiadomościami zawierającymi dane. wysyłane 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ść o wysokim priorytecie jest wysyłana, jest ona wysyłana natychmiast, a aplikacja może wyświetlić powiadomienie. |
|
content_available |
Opcjonalne, wartość logiczna | Na platformach Apple to pole reprezentuje wartość |
|
mutable_content |
Opcjonalny, logiczny typ danych JSON | Na platformach Apple użyj tego pola, aby określić,
|
|
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 |
Opcjonalne, wartość logiczna | Po ustawieniu tego parametru na Wartością domyślną jest |
|
Ładunek | |||
data |
Opcjonalny, obiekt | Ten parametr określa pary klucz-wartość ładunku wiadomości. Na przykład Na platformach Apple wiadomość jest dostarczana przez punkty APN. Przedstawia ona niestandardowe pola danych. 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 („from”, „message_type” lub dowolnym słowem rozpoczynającym się od „google” lub „gcm”). Nie używaj żadnych słów zdefiniowanych w tej tabeli
(np. Zalecane są wartości w typach ciągów znaków. Musisz przekonwertować wartości w obiektach lub innych typach danych niebędących ciągami znaków (np. liczby całkowite lub logiczne) na ciąg znaków. |
|
notification |
Opcjonalny, obiekt | Ten parametr określa wstępnie zdefiniowane, widoczne dla użytkownika pary klucz-wartość w danych powiadomienia. Szczegółowe informacje znajdziesz w artykule dotyczącym obsługi ładunku powiadomień. Więcej informacji
na temat opcji wiadomości dotyczących powiadomień i wiadomości danych można znaleźć w sekcji
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 ładunku powiadomień
W tabelach poniżej znajdziesz listę wstępnie zdefiniowanych dostępne do tworzenia wiadomości z powiadomieniami na platformy Apple i Androida.
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 |
Opcjonalnie: ciąg znaków |
Wartość plakietki na ikonie aplikacji na ekranie głównym. Jeśli go nie podasz, plakietka się nie zmieni.
Jeśli ma wartość |
click_action |
Opcjonalnie: ciąg znaków |
Działanie powiązane z kliknięciem powiadomienia przez użytkownika.
Odpowiada wartości |
subtitle |
Opcjonalnie: ciąg znaków |
Podtytuł powiadomienia. |
body_loc_key |
Opcjonalnie: ciąg znaków |
Klucz do ciągu treści w zasobach ciągu tekstowego aplikacji, który ma być używany do zlokalizuj tekst główny do bieżącej lokalizacji użytkownika.
Odpowiada parametrowi Więcej informacji znajdziesz w artykule Referencje dotyczące klucza danych payload i Tłumaczenie treści powiadomień zdalnych. |
body_loc_args |
Opcjonalnie, tablica JSON jako ciąg znaków |
Ciągi znaków zmiennych, które mają być używane zamiast specyfikatorów formatu w
Odpowiada parametrowi Zobacz Dokumentacja klucza ładunku Lokalizuję zawartość powiadomień zdalnych, aby dowiedzieć się więcej i informacjami o nich. |
title_loc_key |
Opcjonalny, ciąg znaków |
Klucz do ciągu tytułu w zasobach ciągu tekstowego aplikacji, który ma służyć do przetłumaczyć tekst tytułu do bieżącej lokalizacji użytkownika.
Odpowiada parametrowi Więcej informacji znajdziesz w artykule Referencje dotyczące klucza danych payload i Lokalizacja treści powiadomień zdalnych. |
title_loc_args |
Opcjonalnie, tablica JSON jako ciąg znaków |
Ciągi znaków zmiennych, które mają być używane zamiast specyfikatorów formatu w
Odpowiada wartości Zobacz Dokumentacja klucza ładunku Lokalizuję zawartość powiadomień zdalnych, aby dowiedzieć się więcej i informacjami o nich. |
Parametr | Wykorzystanie | Opis |
---|---|---|
title |
Opcjonalny, ciąg znaków |
Tytuł powiadomienia. |
body |
Opcjonalnie: ciąg znaków |
Treść powiadomienia. |
android_channel_id |
Opcjonalnie: ciąg znaków |
Identyfikator kanału powiadomienia (nowy w Androidzie O). Zanim aplikacja otrzyma powiadomienie z tym identyfikatorem kanału, musi utworzyć kanał z tym identyfikatorem. Jeśli nie podasz tego identyfikatora kanału w prośbie lub jeśli podany identyfikator kanału nie został jeszcze utworzona przez aplikację, FCM używa identyfikatora kanału określonego w manifeście 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 pole |
tag |
Opcjonalnie: ciąg znaków |
Identyfikator używany do zastępowania obecnych powiadomień w powiadomieniu szuflady. Jeśli go nie podasz, dla każdego żądania tworzone będzie nowe powiadomienie. 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 |
Opcjonalnie: ciąg znaków |
Działanie powiązane z kliknięciem powiadomienia przez użytkownika. Jeśli określisz działanie z pasującym filtrem intencji, zostanie ono uruchomione, gdy użytkownik klika je. |
body_loc_key |
Opcjonalnie: ciąg znaków |
Klucz do ciągu tekstowego w zasobach ciągu tekstowego aplikacji, który służy do zlokalizowania tekstu w ramach bieżącej lokalizacji użytkownika. Zobacz String Resources. |
body_loc_args |
Opcjonalnie tablica JSON jako ciąg znaków |
Ciągi znaków zmiennych, które mają być używane zamiast specyfikatorów formatu w
Zobacz Formatowanie i styl. |
title_loc_key |
Opcjonalnie: ciąg znaków |
Klucz do ciągu tytułu w zasobach ciągu tekstowego aplikacji, który ma służyć do przetłumaczyć tekst tytułu do bieżącej lokalizacji użytkownika. Zobacz String Resources. |
title_loc_args |
Opcjonalnie tablica JSON jako ciąg znaków |
Ciągi znaków zmiennych, które mają być używane zamiast specyfikatorów formatu w
Więcej informacji znajdziesz w sekcji Formatowanie i stylowanie. |
Parametr | Wykorzystanie | Opis |
---|---|---|
title |
Opcjonalny, ciąg znaków |
Tytuł powiadomienia. |
body |
Opcjonalnie: ciąg znaków |
Treść powiadomienia. |
icon |
Opcjonalny, ciąg znaków |
Adres URL, który ma być używany na potrzeby 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 adresu 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 klienckiej. |
message_id |
Wymagane, ciąg znaków | Ten parametr jednoznacznie identyfikuje komunikat w połączeniu XMPP. Wartość jest ciągiem znaków, który jednoznacznie identyfikuje powiązaną wiadomość. |
message_type |
Wymagane, ciąg znaków | Ten parametr określa wiadomość Jeśli ma wartość |
error |
Opcjonalny, ciąg znaków | Ten parametr określa błąd związany z kolejnym komunikatem. 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 podaje opisowe informacje o błędzie. Jest ona ustawiana, gdy message_type to nack . |
Kody odpowiedzi na błędy wiadomości przesyłanych dalej
Tabela poniżej zawiera kody odpowiedzi na błędy w kolejnych komunikatach.
Błąd | Kod XMPP | Zalecane działanie |
---|---|---|
Brak tokena rejestracji | INVALID_JSON |
Sprawdź, czy żądanie zawiera token rejestracji (w tagu
registration_id w wiadomości tekstowej lub w aplikacji 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 się rejestruje w przypadku FCM, musi określać, 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 ładunku wiadomości nie przekracza limitów FCM: 4096 bajtów w przypadku większości wiadomości lub 2048 bajtów w przypadku wiadomości do tematów. Dotyczy to zarówno kluczy, jak i wartości. |
Nieprawidłowy klucz danych | 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 funkcji time_to_live jest liczbą całkowitą reprezentującą
czas trwania w sekundach z zakresu 0–2 419 200 (4 tygodnie). |
Nieprawidłowa wiadomość potwierdzenia | BAD_ACK |
Zanim spróbujesz ponownie, sprawdź, czy wiadomość w usłudze ack jest prawidłowo sformatowana. Zobacz
tabeli 6. |
Czas oczekiwania | SERVICE_UNAVAILABLE |
Serwer nie mógł przetworzyć żądania na czas. Ponownie wyślij to samo żądanie, ale musisz:
Uwaga: nadawcy, którzy powodują problemy, mogą znaleźć się na czarnej liście. |
Wewnętrzny błąd serwera | INTERNAL_SERVER_
|
Podczas próby przetworzenia żądania serwer napotkał błąd. Możesz spróbować jeszcze raz to samo żądanie zgodnie z wymaganiami wymienionymi w sekcji „Limit czasu” (zobacz 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 wysłanych na to urządzenie i nie próbuj od razu ponawiać próby wysłania na to urządzenie. |
Przekroczono częstotliwość wiadomości z tematów | 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ż trwa zamykanie połączenia. Dzieje się tak, ponieważ okresowo FCM musi zamknąć połączenie, aby przeprowadzić równoważenie obciążenia. Wyślij wiadomość ponownie lub inne połączenie XMPP. |
Nieprawidłowe dane logowania APNs | INVALID_APNS_CREDENTIAL |
Nie można wysłać wiadomości kierowanej na urządzenie z iOS, ponieważ wymagane punkty APN nie przesłano klucza uwierzytelniania lub wygasł. Sprawdź poprawność danych logowania do wersji deweloperskiej i produkcyjnej. |
Nie udało się uwierzytelnić | AUTHENTICATION_FAILED |
Nie udało się uwierzytelnić w zewnętrznych usługach push. Sprawdź, czy używasz tagu prawidłowe certyfikaty Web Push Certificate. |
Składnia komunikatu nadrzędnego
Wiadomość nadrzędna to komunikat, który aplikacja kliencka wysyła do serwera aplikacji. Obecnie tylko XMPP obsługuje wysyłanie wiadomości. Zobacz zapoznaj się z dokumentacją platformy, informacje o wysyłaniu wiadomości z aplikacji klienckich.
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 klienckiej, która wysłała wiadomość. |
message_id |
Wymagane, ciąg znaków | Ten parametr określa unikalny identyfikator wiadomości. |
data |
Opcjonalnie: ciąg znaków | Ten parametr określa pary klucz-wartość ładunku wiadomości. |
Wysyłam wiadomość z potwierdzeniem
W tabeli poniżej opisano odpowiedź ACK, do której ma wysłać serwer aplikacji FCM w odpowiedzi na wiadomość nadaną przez serwer aplikacji.
Parametr | Wykorzystanie | Opis |
---|---|---|
to |
Wymagane, ciąg znaków | Ten parametr określa adresata wiadomości z odpowiedzią. Wartość musi być tokenem rejestracji aplikacji klienckiej, która wysłała wiadomość nadrzędną. |
message_id |
Wymagane, ciąg znaków | Ten parametr określa, do którego komunikatu przeznaczona jest 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 należy ustawić wartość ack . |
FCM wiadomości serwera (XMPP)
Ta wiadomość została wysłana z adresu FCM do serwera aplikacji. Oto główne typy wiadomości, które FCM wysyła do serwera aplikacji:
- Kontrola: komunikaty wygenerowane w panelu CCS wskazują, że wymagane działanie z serwera aplikacji.
W tej tabeli opisano pola zawarte w komunikatach CCS wysyła do serwera aplikacji.
Parametr | Wykorzystanie | Opis |
---|---|---|
Wspólne pole | ||
message_type |
Wymagane, ciąg znaków | Ten parametr określa typ komunikatu: Control. Jeśli zasada ma wartość |
control_type |
Opcjonalnie: ciąg znaków | Ten parametr określa typ wiadomości kontrolnej wysyłanej z FCM. Obecnie obsługiwana jest tylko |