Ten dokument zawiera omówienie składni XMPP używanej do przekazywania wiadomości przesyłane 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 opcje zaliczają się do tych kategorii:
- 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
- FCM komunikaty kontrolne
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 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 |
Opcjonalnie: ciąg znaków | Ten parametr określa wyrażenie logiczne warunków, które określa cel wiadomości. Obsługiwany warunek: temat w formacie „TwójTemat” w tematach”. Ten Wielkość liter w 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 W FCM można jednocześnie przechowywać 4 różne wiadomości na aplikację kliencką. Jeśli przekracza tę liczbę, nie ma gwarancji, które 4 klucze zwijania FCM aby zachować. |
|
priority |
Opcjonalnie: ciąg znaków | Określa priorytet wiadomości. Prawidłowe wartości to „normal” i „wysoka”. Na platformach Apple odpowiadają priorytetom 5 i 10 APNs. Domyślnie powiadomienia są wysyłane z wysokim priorytetem oraz wiadomościami zawierającymi dane. wysyłane z normalnym priorytetem. Normalny priorytet optymalizuje zużycia baterii i należy go używać, chyba że wymagane jest natychmiastowe W przypadku wiadomości o normalnym priorytecie aplikacja może otrzymać wiadomość z kodem nieokreślone opóźnienie. 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 używaj tego pola do reprezentowania tego pola ( |
|
mutable_content |
Opcjonalnie, wartość logiczna 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ść ma być przechowywana w pamięci FCM jeśli 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 | Po ustawieniu tego parametru na 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,
w W przypadku Androida skutkuje to dodatkową intencją o nazwie Klucz nie może być słowem zarezerwowanym („z”, „message_type” ani innym 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żytkowników pary klucz-wartość funkcji
ładunek powiadomień. Szczegółowe informacje znajdziesz w artykule dotyczącym obsługi ładunku powiadomień. Więcej informacji na temat konfiguracji
na temat opcji wiadomości dotyczących powiadomień i wiadomości danych można znaleźć w sekcji
Typy wiadomości. Jeśli został podany ładunek powiadomień lub
Opcja content_available ma wartość true w przypadku wiadomości do Apple
na urządzeniu, wiadomość jest wysyłana za pośrednictwem punktów APN, w przeciwnym razie jest wysyłana przez
FCM.
|
Obsługa ładunku powiadomień
W tabelach poniżej znajdziesz listę zdefiniowanych wstępnie dostępne do tworzenia wiadomości z powiadomieniami na platformy Apple i Androida.
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 tekstowy określający pliki dźwiękowe w głównym pakiecie aplikacji klienckiej lub w pliku
Folder |
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 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 Zobacz Dokumentacja klucza ładunku Lokalizuję zawartość powiadomień zdalnych, aby dowiedzieć się więcej i informacjami o nich. |
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 |
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.
Odpowiada parametrowi Zobacz Dokumentacja klucza ładunku Lokalizuję zawartość powiadomień zdalnych, aby dowiedzieć się więcej i informacjami o nich. |
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 parametrowi Zobacz Dokumentacja klucza ładunku Lokalizuję zawartość powiadomień zdalnych, aby dowiedzieć się więcej i informacjami o nich. |
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). Aplikacja musi utworzyć kanał z tym identyfikatorem, zanim powiadomienie z tym identyfikatorem zostanie odebrane. 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 |
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 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 został określony, a powiadomienie z tym samym tagiem jest już wysyłane nowe powiadomienie zastąpi dotychczasowe 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, zostanie ono uruchomione, gdy użytkownik klika je. |
body_loc_key |
Opcjonalnie: ciąg znaków |
Klucz do ciągu treści w zasobach ciągu tekstowego aplikacji, który ma służyć do zlokalizuj tekst główny do 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
Zobacz 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
Obecny stan „message_type ”: nack . Szczegółowe informacje znajdziesz w tabeli 4. |
error_description |
Opcjonalnie: ciąg znaków | Ten parametr podaje opisowe informacje o błędzie. Wartość jest ustawiona
gdy message_type to 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 tagu
registration_id w wiadomości tekstowej lub w aplikacji to
lub registration_ids w formacie JSON). |
Nieprawidłowa rejestracja APNs | INVALID_JSON |
W przypadku rejestracji na iOS sprawdź, czy prośba o rejestrację 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. Sprawdź, czy zgadza się z tokenem rejestracji otrzymywanym przez aplikację kliencką po zarejestrowaniu się za pomocą FCM. Nie wolno je skrócić ani dodać dodatkowych znaków. |
Niezarejestrowane urządzenie | DEVICE_UNREGISTERED |
Istniejący token rejestracji może stracić ważność w wielu sytuacjach, takich jak:
|
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. Należy użyć jednej tych identyfikatorów nadawców podczas wysyłania wiadomości do aplikacji klienckiej. Jeśli przełączysz się na inny Dotychczasowe 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. sprawdzając, czy przekazano odpowiedni typ danych). |
Wiadomość jest za duża | INVALID_JSON |
Sprawdź, czy łączny rozmiar danych ładunku zawartych w wiadomości nie przekroczą limitów FCM: 4096 bajtów w przypadku większości wiadomości lub 2048 bajtów w przypadku wiadomości do tematów. Obejmuje to klucze i wartości. |
Nieprawidłowy klucz danych | INVALID_JSON |
Sprawdź, czy dane ładunku nie zawierają klucza (np. from ,
gcm lub dowolna wartość
poprzedzony google ) używany wewnętrznie przez FCM. Pamiętaj, że niektóre słowa (np. collapse_key )
są również używane przez funkcję FCM, ale są dozwolone w ładunku. W takim przypadku
wartość ładunku zostanie zastąpiona 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). |
Błędny komunikat 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. 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 spróbować jeszcze raz to samo żądanie zgodnie z wymaganiami wymienionymi w sekcji „Limit czasu” (zobacz 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 wysłanych na to urządzenie i nie próbuj od razu ponawiać prób 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 wysłanych dla tego tematu i nie ponawiaj od razu ponownych prób. |
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 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ł. Sprawdzanie poprawności projektu i weryfikacja w środowisku produkcyjnym. |
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 nadrzędnego komunikatu XMPP
W poniższej tabeli opisano pola wygenerowanej stramy XMPP. o 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, do której ma wysłać serwer aplikacji FCM w odpowiedzi na wiadomość nadaną 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ść message_id z 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 . |
FCM komunikatu 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 |
Wymagany, 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 komunikatu kontrolnego wysłanego z FCM. Obecnie obsługiwana jest tylko |