Protokół XMPP Firebase Cloud Messaging

Ten dokument zawiera omówienie 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 dzielą się na te kategorie:

Składnia kolejnych komunikatów

W tej sekcji znajdziesz składnię służącą do wysyłania kolejnych wiadomości.

Kolejne komunikaty XMPP (JSON)

W tabeli poniżej znajdziesz cele, opcje i ładunek dla komunikatów JSON XMPP.

Tabela 1 Cele, opcje i ładunek kolejnych komunikatów XMPP (JSON).

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, klucz powiadomień grupy urządzeń lub pojedynczy temat (z prefiksem /topics/). Aby wysyłać wiadomości do wielu tematów, użyj parametru condition.

condition Opcjonalnie: ciąg znaków

Ten parametr określa wyrażenie logiczne warunków określających cel wiadomości.

Obsługiwany warunek: temat w formacie „TwójTemat” w tematach. Wielkość liter w tej wartości nie jest rozróżniana.

Obsługiwane operatory: &&, ||. Obsługiwane są maksymalnie 2 operatory na wiadomość w temacie.
Opcje
message_id Wymagany, ciąg znaków

Ten parametr jednoznacznie identyfikuje komunikat w połączeniu XMPP.
collapse_key Opcjonalnie: ciąg znaków

Ten parametr określa grupę wiadomości (np. collapse_key: "Updates Available"), które można zwinąć, aby po wznowieniu dostarczania była wysyłana tylko ostatnia wiadomość. Pozwala to uniknąć wysyłania zbyt wielu takich samych wiadomości, gdy urządzenie znów jest online lub jest uśpione.

Nie możemy zagwarantować kolejności wysyłania wiadomości.

Uwaga: w danym momencie dozwolone są maksymalnie 4 różne klucze zwijania. Oznacza to, że FCM może jednocześnie przechowywać 4 różne wiadomości w aplikacji klienckiej. Jeśli przekroczysz tę liczbę, nie ma gwarancji, które 4 klucze zwijania zachowa FCM.

priority Opcjonalnie: ciąg znaków

Określa priorytet wiadomości. Prawidłowe wartości to „normal” (normalny) i „high”. Na platformach Apple odpowiadają priorytetom 5 i 10 APNs.

Domyślnie powiadomienia są wysyłane z wysokim priorytetem, a wiadomości z danymi – z normalnym priorytetem. Normalny priorytet optymalizuje zużycie baterii przez aplikację kliencką i powinien być używany, chyba że wymagane jest natychmiastowe dostarczanie. W przypadku wiadomości o normalnym priorytecie aplikacja może otrzymać je z nieokreślonym opóźnieniem.

Wiadomość o wysokim priorytecie jest wysyłana natychmiast, a aplikacja może wyświetlić powiadomienie.

content_available Opcjonalne, wartość logiczna

Na platformach Apple użyj tego pola do reprezentowania elementu content-available w ładunku APNs. Po wysłaniu powiadomienia lub wiadomości z ustawieniem true nieaktywna aplikacja kliencka jest wybudzana, a wiadomość jest wysyłana przez APNs jako ciche powiadomienie, a nie przez FCM. Pamiętaj, że ciche powiadomienia w APN-ach nie są gwarantowane i mogą zależeć od takich czynników jak włączenie przez użytkownika trybu oszczędzania energii czy wymuszenie zamknięcia aplikacji. Na Androidzie wiadomości z danymi uruchamiają aplikację domyślnie. W Chrome. Ta funkcja nie jest obecnie obsługiwana.
mutable_content Opcjonalnie, wartość logiczna JSON

Na platformach Apple użyj tego pola do reprezentowania mutable-content w ładunku APNs. Gdy powiadomienie ma wartość true, treść powiadomienia można modyfikować za pomocą rozszerzenia aplikacji usługi powiadomień, zanim zostanie wyświetlone. W przypadku Androida i internetu ten parametr będzie ignorowany.

time_to_live Opcjonalnie, liczba

Ten parametr określa, jak długo (w sekundach) wiadomość ma być przechowywana w pamięci FCM, gdy urządzenie jest offline. Maksymalny obsługiwany czas życia to 4 tygodnie, a wartość domyślna to 4 tygodnie. Więcej informacji znajdziesz w artykule Ustawianie okresu ważności wiadomości.

dry_run Opcjonalne, wartość logiczna

Gdy ten parametr jest ustawiony na wartość true, deweloperzy mogą testować żądanie bez wysyłania wiadomości.

Wartością domyślną jest false.
Ładunek
data Opcjonalny, obiekt

Ten parametr określa pary klucz-wartość ładunku wiadomości.

Przykład: data:{"score":"3x1"}:

Na platformach Apple wiadomość jest dostarczana przez punkty APN. Przedstawia ona niestandardowe pola danych. Jeśli jest dostarczana przez FCM, jest reprezentowana w AppDelegate application:didReceiveRemoteNotification: jako słownik wartości klucz-wartość.

W przypadku Androida skutkuje to dodatkową intencją o nazwie score z wartością ciągu znaków 3x1.

Klucz nie może być słowem zarezerwowanym („z”, „message_type” ani żadnym słowem rozpoczynającym się od „google” lub „gcm”). Nie używaj żadnych słów zdefiniowanych w tej tabeli (np. collapse_key).

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 wartości logiczne) na ciąg znaków.
notification Opcjonalny, obiekt Ten parametr określa wstępnie zdefiniowane pary klucz-wartość widoczne dla użytkowników w ładunku powiadomień. Szczegółowe informacje znajdziesz w artykule dotyczącym obsługi ładunku powiadomień. Więcej informacji o opcjach wiadomości z powiadomieniami i wiadomości zawierających dane znajdziesz w artykule Typy wiadomości. Jeśli ładunek powiadomień jest podany lub opcja content_available jest ustawiona na true w przypadku wiadomości na urządzeniu Apple, wiadomość jest wysyłana przez APNs. W przeciwnym razie jest wysyłana przez FCM.

Obsługa ładunku powiadomień

W tabelach poniżej znajdziesz wstępnie zdefiniowane klucze dostępne przy tworzeniu wiadomości z powiadomieniami na platformach Apple i Androidzie.

Tabela 2a. Apple – klucze do obsługi powiadomień

Parametr Wykorzystanie Opis
title Opcjonalnie: ciąg znaków

Tytuł powiadomienia.

To pole jest niewidoczne na telefonach i tabletach.

body Opcjonalnie: ciąg znaków

Treść powiadomienia.

sound Opcjonalnie: ciąg znaków

Dźwięk do odtwarzania, 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 Library/Sounds w kontenerze danych aplikacji. Więcej informacji znajdziesz w bibliotece programisty aplikacji na iOS.

badge Opcjonalnie: ciąg znaków

Wartość plakietki na ikonie aplikacji na ekranie głównym.

Jeśli go nie podasz, identyfikator się nie zmieni.

Jeśli ma wartość 0, plakietka zostanie usunięta.

click_action Opcjonalnie: ciąg znaków

Działanie powiązane z użytkownikiem kliknie powiadomienie.

Odpowiada parametrowi category w ładunku APNs.

subtitle Opcjonalnie: ciąg znaków

Podtytuł powiadomienia.

body_loc_key Opcjonalnie: ciąg znaków

Klucz do ciągu tekstowego w zasobach ciągu tekstowego aplikacji, który ma być używany do zlokalizowania tekstu głównego w bieżącej lokalizacji użytkownika.

Odpowiada parametrowi loc-key w ładunku APNs.

Więcej informacji znajdziesz w opisie klucza ładunku i lokalizacji zawartości powiadomień zdalnych.

body_loc_args Opcjonalnie, tablica JSON jako ciąg znaków

Wartości ciągów zmiennych, które mają być używane zamiast specyfikatorów formatu w polu body_loc_key służące do zlokalizowania tekstu głównego w aktualnej lokalizacji użytkownika.

Odpowiada parametrowi loc-args w ładunku APNs.

Więcej informacji znajdziesz w opisie klucza ładunku i lokalizacji zawartości powiadomień zdalnych.

title_loc_key Opcjonalnie: ciąg znaków

Klucz do ciągu tytułu w zasobach ciągu tekstowego aplikacji, który ma być używany do zlokalizowania tekstu tytułu w bieżącej lokalizacji użytkownika.

Odpowiada parametrowi title-loc-key w ładunku APNs.

Więcej informacji znajdziesz w opisie klucza ładunku i lokalizacji zawartości powiadomień zdalnych.

title_loc_args Opcjonalnie, tablica JSON jako ciąg znaków

Wartości ciągów zmiennych, które mają być używane zamiast specyfikatorów formatu w polu title_loc_key służące do zlokalizowania tekstu tytułu w aktualnej lokalizacji użytkownika.

Odpowiada parametrowi title-loc-args w ładunku APNs.

Więcej informacji znajdziesz w opisie klucza ładunku i lokalizacji zawartości powiadomień zdalnych.

Tabela 2b. Android – klucze do obsługi powiadomień

Parametr Wykorzystanie Opis
title Opcjonalnie: 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 (nowość w Androidzie O).

Zanim zostanie odebrane powiadomienie z tym identyfikatorem, aplikacja musi utworzyć kanał z tym identyfikatorem.

Jeśli nie prześlesz 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 pliku manifestu aplikacji.

icon Opcjonalnie: ciąg znaków

Ikona powiadomienia.

Ustawia ikonę powiadomień na myicon dla zasobu rysowalnego myicon. Jeśli nie wyślesz tego klucza w żądaniu, FCM wyświetli ikonę programu uruchamiającego określoną w pliku manifestu aplikacji.

sound Opcjonalnie: ciąg znaków

Dźwięk do odtwarzania, gdy urządzenie otrzyma powiadomienie.

Obsługuje wartość "default" lub nazwę pliku zasobu dźwiękowego zawartego w aplikacji. Pliki dźwiękowe muszą znajdować się w lokalizacji /res/raw/.

tag Opcjonalnie: ciąg znaków

Identyfikator używany do zastępowania obecnych powiadomień w panelu powiadomień.

Jeśli go nie podasz, dla każdego żądania tworzone będzie nowe powiadomienie.

Jeśli określisz je i wyświetli się już powiadomienie z tym samym tagiem, nowe powiadomienie zastąpi dotychczasowe w panelu powiadomień.

color Opcjonalnie: ciąg znaków

Kolor ikony powiadomienia w formacie #rrggbb.

click_action Opcjonalnie: ciąg znaków

Działanie powiązane z użytkownikiem kliknie powiadomienie.

Jeśli określisz działanie z pasującym filtrem intencji, uruchamia się ona, gdy użytkownik kliknie powiadomienie.

body_loc_key Opcjonalnie: ciąg znaków

Klucz do ciągu tekstowego w zasobach ciągu tekstowego aplikacji, który ma być używany do zlokalizowania tekstu głównego w bieżącej lokalizacji użytkownika.

Więcej informacji znajdziesz w artykule na temat zasobów ciągu tekstowego.

body_loc_args Opcjonalnie, tablica JSON jako ciąg znaków

Wartości ciągów zmiennych, które mają być używane zamiast specyfikatorów formatu w polu body_loc_key służące do zlokalizowania tekstu głównego w aktualnej lokalizacji użytkownika.

Więcej informacji znajdziesz w sekcji 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 być używany do zlokalizowania tekstu tytułu w bieżącej lokalizacji użytkownika.

Więcej informacji znajdziesz w artykule na temat zasobów ciągu tekstowego.

title_loc_args Opcjonalnie, tablica JSON jako ciąg znaków

Wartości ciągów zmiennych, które mają być używane zamiast specyfikatorów formatu w polu title_loc_key służące do zlokalizowania tekstu tytułu w aktualnej lokalizacji użytkownika.

Więcej informacji znajdziesz w sekcji Formatowanie i styl.

Tabela 2c. Sieć (JavaScript) – klucze do obsługi powiadomień

Parametr Wykorzystanie Opis
title Opcjonalnie: ciąg znaków

Tytuł powiadomienia.

body Opcjonalnie: ciąg znaków

Treść powiadomienia.

icon Opcjonalnie: ciąg znaków

Adres URL, który ma być używany na potrzeby ikony powiadomienia.

click_action Opcjonalnie: ciąg znaków

Działanie powiązane z użytkownikiem kliknie powiadomienie.

W przypadku wszystkich wartości adresów URL wymagany jest protokół HTTPS.

Interpretowanie odpowiedzi na żądanie wysyłanego komunikatu XMPP

Tabela poniżej zawiera listę pól, które pojawiają się w odpowiedzi na żądanie wiadomości XMPP.

Tabela 3 Treść odpowiedzi XMPP komunikatu źródłowego.

Parametr Wykorzystanie Opis
from Wymagany, ciąg znaków

Ten parametr określa, kto wysłał tę odpowiedź.

Wartość to token rejestracji aplikacji klienckiej.
message_id Wymagany, 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 Wymagany, ciąg znaków

Ten parametr określa komunikat ack lub nack z FCM do serwera aplikacji.

Jeśli wartość jest ustawiona na nack, serwer aplikacji powinien sprawdzać parametry error i error_description, aby uzyskać informacje o błędach.

error Opcjonalnie: 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 Opcjonalnie: ciąg znaków Ten parametr podaje opisowe informacje o błędzie. Jest ustawiany, gdy message_type ma wartość nack.

Kody odpowiedzi na błędy w kolejnych komunikatach

Tabela poniżej zawiera kody odpowiedzi na błędy w kolejnych komunikatach.

Tabela 4 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 polu registration_id w postaci zwykłego tekstu lub w polu to albo registration_ids w pliku JSON).
Nieprawidłowa rejestracja APNs INVALID_JSON W przypadku rejestracji na iOS sprawdź, czy żądanie rejestracji od klienta zawiera prawidłowy token APNs i identyfikator aplikacji.
Nieprawidłowy token rejestracji BAD_REGISTRATION Sprawdź format tokena rejestracji, który przekazujesz do serwera. Upewnij się, że jest on zgodny z tokenem rejestracji, który aplikacja kliencka otrzymuje po rejestracji w FCM. Nie skracaj ani nie dodawaj dodatkowych znaków.
Niezarejestrowane urządzenie DEVICE_UNREGISTERED Dotychczasowy token rejestracji może stracić ważność w wielu sytuacjach, w tym:
  • Jeśli aplikacja kliencka wyrejestruje się z FCM.
  • Jeśli aplikacja kliencka zostanie automatycznie wyrejestrowana, co może nastąpić po odinstalowaniu aplikacji przez użytkownika. Na przykład w systemie iOS, jeśli punkty APNs zgłosiły token APNs jako nieprawidłowy.
  • Gdy token rejestracji wygaśnie (np. Google może odświeżyć tokeny rejestracji lub token APNs wygasł dla urządzeń).
  • Jeśli aplikacja kliencka została 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.
Niezgodny nadawca SENDER_ID_MISMATCH 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 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 poprawnie sformatowana i zawiera prawidłowe pola (np. czy przekazujesz właściwy typ danych).
Wiadomość jest za duża INVALID_JSON 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 INVALID_JSON Sprawdź, czy dane ładunku nie zawierają klucza (takiego jak from, gcm ani żadnej 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ą również używane przez FCM, ale są dozwolone w ładunku. W takim przypadku wartość ładunku zostaje zastąpiona wartością FCM.
Nieprawidłowy czas życia INVALID_JSON Sprawdź, czy wartość używana w polu time_to_live jest liczbą całkowitą reprezentującą czas trwania w sekundach z zakresu od 0 do 2 419 200 (4 tygodni).
Błędny komunikat potwierdzenia BAD_ACK Zanim spróbujesz ponownie, sprawdź, czy wiadomość w usłudze ack jest prawidłowo sformatowana. Szczegółowe informacje znajdziesz w tabeli 6.
Czas oczekiwania SERVICE_UNAVAILABLE

Serwer nie mógł przetworzyć żądania na czas. Ponów tę samą prośbę, ale musisz:

  • Wdróż wykładniczy czas do ponowienia w mechanizmie ponawiania. (np.jeśli czekanie na pierwszą sekundę przed kolejną próbą, odczekaj przynajmniej dwie sekundy przed następną, potem cztery 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.
  • Początkowe opóźnienie ponawiania powinno być ustawione na 1 sekundę.

Uwaga: nadawcy, którzy powodują problemy, mogą znaleźć się na czarnej liście.
Wewnętrzny błąd serwera INTERNAL_SERVER_
ERROR		 Podczas próby przetworzenia żądania serwer napotkał błąd. Możesz ponowić to samo żądanie zgodnie z wymaganiami określonymi w sekcji „Limit czasu” (patrz wiersz powyżej).
Przekroczono częstotliwość wiadomości z urządzenia 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.
Przekroczono częstotliwość wiadomości z tematów 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 od razu.
Opróżniam połączenie 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 komunikat ponownie, używając innego połączenia XMPP.
Nieprawidłowe dane logowania APNs INVALID_APNS_CREDENTIAL Nie można wysłać wiadomości kierowanej na urządzenie z iOS, ponieważ wymagany klucz uwierzytelniania APNs nie został przesłany lub wygasł. Sprawdź poprawność swoich uprawnień programistycznych i produkcyjnych.
Nie udało się uwierzytelnić 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 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. Więcej informacji o wysyłaniu wiadomości z aplikacji klienckich znajdziesz w dokumentacji Twojej platformy.

Interpretowanie nadrzędnego komunikatu XMPP

W tabeli poniżej opisujemy pola w części XMPP wygenerowanej przez FCM w odpowiedzi na żądania wiadomości wysyłane z aplikacji klienckich.

Tabela 5 Nadrzędne komunikaty XMPP.

Parametr Wykorzystanie Opis
from Wymagany, ciąg znaków

Ten parametr określa, kto wysłał wiadomość.

Wartość to token rejestracji aplikacji klienckiej.
category Wymagany, ciąg znaków Ten parametr określa nazwę pakietu aplikacji klienckiej, która wysłała wiadomość.
message_id Wymagany, 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, którą serwer aplikacji powinien wysłać do FCM w odpowiedzi na wiadomość nadrzędną odebraną przez serwer aplikacji.

Tabela 6 Odpowiedź na komunikat XMPP z serwera nadawcy.

Parametr Wykorzystanie Opis
to Wymagany, 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 Wymagany, ciąg znaków Ten parametr określa, do którego komunikatu przeznaczona jest odpowiedź. Wartość musi być wartością message_id odpowiedniego komunikatu nadrzędnego.
message_type Wymagany, ciąg znaków Ten parametr określa komunikat ack z serwera aplikacji do CCS. W przypadku wiadomości nadrzędnych zawsze powinna być ona ustawiona na ack.

Komunikaty serwera FCM (XMPP)

Ta wiadomość została wysłana z FCM na serwer aplikacji. Oto główne typy wiadomości, które FCM wysyła do serwera aplikacji:

  • Kontrola: te komunikaty generowane przez CCS wskazują, że serwer aplikacji wymaga podjęcia działania.

W tabeli poniżej opisano pola zawarte w wiadomościach wysyłanych przez CCS do serwera aplikacji.

Tabela 7 Komunikaty kontrolne FCM (XMPP).

Parametr Wykorzystanie Opis
Wspólne pole
message_type Wymagany, ciąg znaków

Ten parametr określa typ komunikatu: Control.

Jeśli ma wartość control, komunikat zawiera ciąg control_type, który wskazuje typ komunikatu kontrolnego.
control_type Opcjonalnie: ciąg znaków

Ten parametr określa typ komunikatu kontrolnego wysyłanego z FCM.

Obecnie obsługiwana jest tylko CONNECTION_DRAINING. FCM wysyła ten komunikat kontrolny przed zamknięciem połączenia w celu równoważenia obciążenia. W miarę opróżniania połączenia nie można już wysyłać do niego kolejnych wiadomości, ale wiadomości istniejące w potoku będą nadal przetwarzane.