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 wiadomości w dalszej części
- Kody odpowiedzi na błędy w komunikatach wyświetlanych w dalszej części wiadomości
- Składnia komunikatu nadrzędnego
- Komunikaty kontrolne FCM
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.
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 |
|
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: |
|
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. 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 |
|
mutable_content |
Opcjonalnie, wartość logiczna JSON | Na platformach Apple użyj tego pola do reprezentowania |
|
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ść Wartością domyślną jest |
|
Ładunek | |||
data |
Opcjonalny, obiekt | Ten parametr określa pary klucz-wartość ładunku wiadomości. Przykład: Na platformach Apple wiadomość jest dostarczana przez punkty APN. Przedstawia ona niestandardowe pola danych. Jeśli jest dostarczana przez FCM, jest reprezentowana w W przypadku Androida skutkuje to dodatkową intencją o nazwie 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. 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.
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 |
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ść |
click_action |
Opcjonalnie: ciąg znaków |
Działanie powiązane z użytkownikiem kliknie powiadomienie.
Odpowiada parametrowi |
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 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
Odpowiada parametrowi 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 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
Odpowiada parametrowi Więcej informacji znajdziesz w opisie klucza ładunku i lokalizacji zawartości powiadomień zdalnych. |
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 |
sound |
Opcjonalnie: ciąg znaków |
Dźwięk do odtwarzania, gdy urządzenie otrzyma powiadomienie.
Obsługuje wartość |
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 |
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 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 Więcej informacji znajdziesz w sekcji Formatowanie i styl. |
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.
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 Jeśli wartość jest ustawiona na |
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.
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:
|
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:
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 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 |
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 |
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.
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.
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.
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_type |
Opcjonalnie: ciąg znaków | Ten parametr określa typ komunikatu kontrolnego wysyłanego z FCM. Obecnie obsługiwana jest tylko |