Protokół XMPP Firebase Cloud Messaging

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

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.

Tabela 1 Cele, opcje i ładunek dla dalszych 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 /topics/ ). Aby wysłać do wielu tematów, użyj parametru condition .

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: && , || . Obsługiwane są maksymalnie dwa operatory na wiadomość tematyczną.

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 collapse_key: "Updates Available" ), którą można zwinąć w taki sposób, że po wznowieniu dostarczania zostanie wysłana tylko ostatnia wiadomość. Ma to na celu uniknięcie wysyłania zbyt wielu takich samych wiadomości, gdy urządzenie wróci do trybu online lub wyjdzie z drzemki.

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ć content-available w ładunku APN. Po wysłaniu powiadomienia lub wiadomości i ustawieniu tej opcji na true , nieaktywna aplikacja kliencka zostanie obudzona, a wiadomość zostanie wysłana przez usługi APN jako ciche powiadomienie, a nie przez FCM. Pamiętaj, że ciche powiadomienia w nazwach APN nie są gwarantowane i mogą zależeć od takich czynników, jak włączenie przez użytkownika trybu niskiego zużycia energii, wymuszenie zamknięcia aplikacji itp. W systemie Android wiadomości dotyczące danych domyślnie budzą aplikację. W przeglądarce Chrome obecnie nie jest obsługiwane.

mutable_content Opcjonalnie wartość logiczna JSON

Na platformach Apple użyj tego pola, aby reprezentować mutable-content w ładunku APN. Po wysłaniu powiadomienia i ustawieniu tej opcji na true treść powiadomienia można zmodyfikować przed jego wyświetleniem, korzystając z rozszerzenia aplikacji Notification Service . Ten parametr będzie ignorowany w przypadku Androida i Internetu.

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 true , umożliwia programistom testowanie żądania bez wysyłania wiadomości.

Wartość domyślna to false .

Ładunek
data Opcjonalnie, obiekt

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

Na przykład z data:{"score":"3x1"}:

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 AppDelegate application:didReceiveRemoteNotification: .

W systemie Android skutkuje to dodatkowym nazwanym score o wartości ciągu 3x1 .

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 collapse_key ).

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.

Tabela 2a. Apple — klawisze powiadomień

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 Library/Sounds w kontenerze danych aplikacji. Aby uzyskać więcej informacji, zobacz Bibliotekę programistów iOS .

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 0 , odznaka zostanie usunięta.

click_action Opcjonalnie, ciąg

Akcja powiązana z kliknięciem przez użytkownika powiadomienia.

Odpowiada category w ładunku APNs.

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 loc-key w ładunku APN.

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 body_loc_key w celu zlokalizowania tekstu treści w bieżącej lokalizacji użytkownika.

Odpowiada loc-args w ładunku APN.

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 title-loc-key w ładunku APN.

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 title_loc_key w celu zlokalizowania tekstu tytułu w bieżącej lokalizacji użytkownika.

Odpowiada title-loc-args w ładunku APN.

Aby uzyskać więcej informacji, zobacz Informacje o kluczu ładunku i Lokalizowanie zawartości zdalnych powiadomień .

Tabela 2b. Android — klawisze 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 myicon dla zasobu do rysowania myicon . Jeśli nie wyślesz tego klucza w żądaniu, FCM wyświetli ikonę programu uruchamiającego określoną w manifeście aplikacji.

sound Opcjonalnie, ciąg

Dźwięk odtwarzany, gdy urządzenie odbierze powiadomienie.

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

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 #rrggbb .

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 body_loc_key w celu zlokalizowania tekstu treści w bieżącej lokalizacji użytkownika.

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 title_loc_key w celu zlokalizowania tekstu tytułu w bieżącej lokalizacji użytkownika.

Aby uzyskać więcej informacji, zobacz Formatowanie i stylizacja .

Tabela 2c. Web (JavaScript) — klucze powiadomień

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.

Tabela 3 Treść odpowiedzi XMPP na komunikat dalszy.

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ść ack lub nack z FCM do serwera aplikacji.

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

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.

Tabela 4 Kody odpowiedzi na błędy 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:
  • Jeśli aplikacja kliencka wyrejestruje się z FCM.
  • Jeśli aplikacja kliencka zostanie automatycznie wyrejestrowana, co może się zdarzyć, jeśli użytkownik odinstaluje aplikację. Na przykład w systemie iOS, jeśli APNs zgłosiło, że token APNs jest nieprawidłowy.
  • Jeśli token rejestracji wygaśnie (na przykład Google może podjąć decyzję o odświeżeniu tokenów 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.
We wszystkich tych przypadkach usuń ten token rejestracji z serwera aplikacji i przestań go używać do wysyłania wiadomości.
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:

  • Zaimplementuj wykładnicze wycofywanie w mechanizmie ponawiania prób. (np. jeśli odczekałeś jedną sekundę przed pierwszą ponowną próbą, odczekaj co najmniej dwie sekundy przed następną, potem cztery sekundy i tak dalej). Jeśli wysyłasz wiele wiadomości, opóźnij każdą z nich niezależnie o dodatkową losową kwotę, aby uniknąć jednoczesnego wysyłania nowego żądania dla wszystkich wiadomości.
  • Początkowe opóźnienie ponownej próby powinno być ustawione na jedną sekundę.

Uwaga: nadawcy powodujący problemy mogą zostać umieszczeni na czarnej liście.

Wewnętrzny błąd serwera INTERNAL_SERVER_
ERROR
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
_EXCEEDED
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
_EXCEEDED
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.

Tabela 5 Upstreamowe komunikaty XMPP.

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.

Tabela 6 Odpowiedź na komunikat XMPP przesyłany dalej.

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.

Tabela 7 Komunikaty sterujące FCM (XMPP).

Parametr Stosowanie Opis
Wspólne pole
message_type Wymagane, ciąg

Parametr ten określa typ komunikatu: control.

Gdy jest ustawiony na control , komunikat zawiera control_type , aby wskazać typ komunikatu sterującego.

control_type Opcjonalnie, ciąg

Ten parametr określa typ komunikatu sterującego wysyłanego z FCM.

Obecnie obsługiwane jest tylko CONNECTION_DRAINING . FCM wysyła ten komunikat kontrolny przed zamknięciem połączenia w celu równoważenia obciążenia. W miarę wyczerpywania się połączenia nie można do niego wysyłać więcej komunikatów, ale istniejące komunikaty w potoku są nadal przetwarzane.