Ten dokument zawiera informacje o składni HTTP używanej do przekazywania wiadomości z serwera aplikacji do aplikacji klienckich za pomocą Komunikacji w chmurze Firebase (FCM).
Podczas korzystania ze starszego protokołu HTTP serwer aplikacji musi kierować wszystkie żądania HTTP do tego punktu końcowego:
https://fcm.googleapis.com/fcm/send
Dostępne parametry i opcje należą do tych ogólnych kategorii:
Składnia komunikatów w dół
W tej sekcji znajdziesz składnię przeznaczoną do wysyłania wiadomości z klienta na serwer i interpretowania odpowiedzi HTTP z Komunikacji w chmurze Firebase (FCM).
Komunikaty HTTP pobierania (JSON)
W tabeli poniżej znajdziesz cele, opcje i ładunek dla wiadomości JSON HTTP.
Parametr | Wykorzystanie | Opis | |
---|---|---|---|
Cele | |||
to |
Opcjonalnie, ciąg znaków |
Ten parametr określa odbiorcę wiadomości.
Może to być token rejestracji urządzenia, klucz powiadomień grupy urządzeń lub pojedynczy temat (z prefiksem |
|
registration_ids | Opcjonalne, tablica ciągów tekstowych |
Ten parametr określa adresata wiadomości multiemisji wysłanej do więcej niż 1 tokenu rejestracji.
Wartość powinna być tablicą tokenów rejestracji, do której ma zostać wysłana wiadomość multiemisji. Tablica musi zawierać od 1 do 1000 tokenów rejestracji. Aby wysłać wiadomość na jedno urządzenie, użyj parametru Wiadomości multiemisji są dozwolone tylko w formacie HTTP JSON. |
|
condition |
Opcjonalnie, ciąg znaków | Ten parametr określa logiczne wyrażenie warunków określających cel wiadomości. Obsługiwany warunek: temat w formacie „Twój temat” w tematach. Wielkość liter w tej wartości nie jest rozróżniana. Obsługiwane operatory: |
|
notification_key Wycofano |
Opcjonalnie, ciąg znaków | Ten parametr został wycofany. Zamiast niego możesz określić adresatów wiadomości za pomocą polecenia |
|
Opcje | |||
collapse_key |
Opcjonalnie, ciąg znaków | Ten parametr identyfikuje grupę wiadomości (np. Pamiętaj, że nie ma gwarancji, w jakiej kolejności będą wysyłane wiadomości. Uwaga: jednocześnie dozwolone są maksymalnie 4 różne klucze zwijania. Oznacza to, że FCM może jednocześnie przechowywać 4 różne wiadomości na aplikację kliencką. 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” (standardowa) i „high” (wysoka). Na platformach Apple odpowiadają one priorytetom 5 i 10 punktów APN. Domyślnie powiadomienia są wysyłane z wysokim priorytetem, a wiadomości z danymi – ze zwykłym priorytetem. Zwykły priorytet optymalizuje wykorzystanie baterii przez aplikację kliencką. Należy go używać, chyba że wymagane jest natychmiastowe dostarczanie. W przypadku wiadomości o normalnym priorytecie aplikacja może otrzymać wiadomość z nieokreślonym opóźnieniem. Gdy wiadomość jest wysyłana z wysokim priorytetem, jest ona wysyłana natychmiast i aplikacja może wyświetlić powiadomienie. |
|
content_available |
Opcjonalne, wartość logiczna | Na platformach Apple używaj tego pola do reprezentowania |
|
mutable_content |
Opcjonalnie, wartość logiczna JSON | Na platformach Apple używaj 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, 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. |
|
restricted_package_
(tylko Android) |
Opcjonalnie, ciąg znaków | Ten parametr określa nazwę pakietu aplikacji, w której tokeny rejestracji muszą się zgadzać, aby otrzymać komunikat. | |
dry_run |
Opcjonalne, wartość logiczna | Gdy ten parametr ma wartość Wartością domyślną jest |
|
Ładunek | |||
data |
Opcjonalnie, obiekt | Ten parametr określa niestandardowe pary klucz-wartość ładunku wiadomości. Na przykład: Na platformach Apple, jeśli wiadomość jest wysyłana przez APN, reprezentuje ona niestandardowe pola danych. Jeśli zostanie wysłana przez FCM, zostanie przedstawiona jako słownik par klucz-wartość w funkcji Na Androidzie spowoduje to utworzenie dodatkowej intencji o nazwie Klucz nie może być słowem zarezerwowanym („from”, „message_type” ani innymi słowami zaczynającymi 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 zawarte w obiektach lub innych typach danych niebędących ciągami (np. liczbach całkowitych lub wartościach logicznych) na ciąg znaków. |
|
notification |
Opcjonalnie, obiekt | Ten parametr określa wstępnie zdefiniowane, widoczne dla użytkownika pary klucz-wartość ładunku powiadomienia. Szczegółowe informacje znajdziesz w sekcji dotyczącej obsługi ładunku powiadomień.
Więcej informacji o opcjach powiadomień i wiadomości z danymi znajdziesz w artykule o
typach wiadomości. Jeśli zostanie podany ładunek powiadomienia lub opcja content_available jest ustawiona na true w przypadku wiadomości wysłanej na urządzenie 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, które są dostępne na potrzeby wiadomości z powiadomieniami kompilacji na iOS 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 odtwarzany, gdy urządzenie otrzyma powiadomienie.
Ciąg tekstowy 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, pozostanie ona bez zmian.
Jeśli ma wartość |
click_action |
Opcjonalnie, ciąg znaków |
Działanie powiązane z kliknięciem powiadomienia przez użytkownika.
Odpowiada wartość |
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 aplikacji w celu zlokalizowania tekstu głównego na bieżącą lokalizację użytkownika.
Odpowiada wartość Więcej informacji znajdziesz w sekcjach Informacje o kluczu ładunku i Lokalizowanie zawartości powiadomień zdalnych. |
body_loc_args |
Opcjonalnie, tablica JSON jako ciąg znaków |
Zmienne wartości ciągu znaków, które mają być używane zamiast specyfikatorów formatu w
Odpowiada wartość Więcej informacji znajdziesz w sekcjach Informacje o kluczu ładunku i Lokalizowanie zawartości powiadomień zdalnych. |
title_loc_key |
Opcjonalnie, ciąg znaków |
Klucz do ciągu znaków tytułu w zasobach tekstowych aplikacji, który służy do zlokalizowania tekstu tytułu na bieżącej lokalizacji użytkownika.
Odpowiada wartość Więcej informacji znajdziesz w sekcjach Informacje o kluczu ładunku i Lokalizowanie zawartości powiadomień zdalnych. |
title_loc_args |
Opcjonalnie, tablica JSON jako ciąg znaków |
Zmienne wartości ciągu znaków, które mają być używane zamiast specyfikacji formatu w
Odpowiada wartość Więcej informacji znajdziesz w sekcjach Informacje o kluczu ładunku i Lokalizowanie 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). Aplikacja musi utworzyć kanał z tym identyfikatorem, zanim otrzymasz powiadomienie z tym identyfikatorem. 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 znaków |
Ikona powiadomienia.
Ustawia ikonę powiadomień na |
sound |
Opcjonalnie, ciąg znaków |
Dźwięk odtwarzany, gdy urządzenie otrzyma powiadomienie.
Obsługuje nazwę |
tag |
Opcjonalnie, ciąg znaków |
Identyfikator używany do zastępowania dotychczasowych powiadomień w panelu powiadomień. Jeśli nie podasz żadnej wartości, każde żądanie spowoduje utworzenie nowego powiadomienia. Jeśli powiadomienie z tym samym tagiem jest już wyświetlane, nowe powiadomienie zastąpi dotychczasowe w szufladzie powiadomień. |
color |
Opcjonalnie, 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 odpowiednim filtrem intencji, w momencie kliknięcia powiadomienia przez użytkownika zostanie uruchomione działanie z odpowiednim filtrem intencji. |
body_loc_key |
Opcjonalnie, ciąg znaków |
Klucz do ciągu tekstowego w zasobach ciągu aplikacji w celu zlokalizowania tekstu głównego na bieżącą lokalizację użytkownika. Więcej informacji znajdziesz w sekcji o zasobach tekstowych. |
body_loc_args |
Opcjonalnie, tablica JSON jako ciąg znaków |
Zmienne wartości ciągu znaków, które mają być używane zamiast specyfikatorów formatu w Więcej informacji znajdziesz w artykule o formatowaniu i stylach. |
title_loc_key |
Opcjonalnie, ciąg znaków |
Klucz do ciągu znaków tytułu w zasobach tekstowych aplikacji, który służy do zlokalizowania tekstu tytułu na bieżącej lokalizacji użytkownika. Więcej informacji znajdziesz w sekcji o zasobach tekstowych. |
title_loc_args |
Opcjonalnie, tablica JSON jako ciąg znaków |
Zmienne wartości ciągu znaków, które mają być używane zamiast specyfikacji formatu w Więcej informacji znajdziesz w artykule o formatowaniu i stylach. |
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 ikony powiadomienia. |
click_action |
Opcjonalnie, ciąg znaków |
Działanie powiązane z kliknięciem powiadomienia przez użytkownika. Dla wszystkich wartości adresów URL wymagany jest protokół HTTPS. |
Wysyłanie wiadomości HTTP (zwykły tekst)
W tabeli poniżej znajdziesz składnię celów, opcji i ładunku w zwykłych tekstowych wiadomościach HTTP.
Parametr | Wykorzystanie | Opis |
---|---|---|
Cele | ||
registration_id |
Wymagany, ciąg znaków | Ten parametr określa aplikacje klienckie (tokeny rejestracji), które dotrą do wiadomości. Przesyłanie wiadomości w trybie multicast (wysyłanie do więcej niż 1 tokenu rejestracji) jest dozwolone tylko w formacie HTTP JSON. |
Opcje | ||
collapse_key |
Opcjonalnie, ciąg znaków | Szczegółowe informacje znajdziesz w tabeli 1. |
time_to_live |
Opcjonalnie, liczba | Szczegółowe informacje znajdziesz w tabeli 1. |
restricted_package_name |
Opcjonalnie, ciąg znaków | Szczegółowe informacje znajdziesz w tabeli 1. |
dry_run |
Opcjonalne, wartość logiczna | Szczegółowe informacje znajdziesz w tabeli 1. |
Ładunek | ||
data.<key> |
Opcjonalnie, ciąg znaków | Ten parametr określa pary klucz-wartość ładunku wiadomości. Nie ma limitu liczby parametrów klucz-wartość, ale łączny rozmiar wiadomości nie może przekraczać 4096 bajtów. Na przykład w Androidzie działanie Klucz nie może być słowem zarezerwowanym („from”, „message_type” ani innymi słowami zaczynającymi się od „google” lub „gcm”). Nie używaj żadnych słów zdefiniowanych w tej tabeli (np. |
Interpretowanie odpowiedzi na wiadomość
Serwer aplikacji powinien ocenić zarówno nagłówek odpowiedzi wiadomości, jak i jej treść, aby zinterpretować odpowiedź na wiadomość wysłaną z FCM. Możliwe odpowiedzi znajdziesz w tabeli poniżej.
Odpowiedź | Opis |
---|---|
200 | Wiadomość została przetworzona. Treść odpowiedzi będzie zawierać więcej informacji o stanie wiadomości, ale jej format będzie zależał od tego, czy żądanie było w formacie JSON, czy w postaci zwykłego tekstu. Więcej informacji znajdziesz w tabeli 5. |
400 | Dotyczy tylko żądań JSON. Wskazuje, że żądania nie udało się przeanalizować jako JSON lub zawierało ono nieprawidłowe pola (na przykład przekazywało ciąg znaków, w którym oczekiwano liczby). Dokładny powód niepowodzenia jest opisany w odpowiedzi, a problem należy rozwiązać przed ponownym wysłaniem żądania. |
401 | Podczas uwierzytelniania konta nadawcy wystąpił błąd. |
5xx | Błędy z zakresu 500–599 (np. 500 lub 503) wskazują, że podczas próby przetworzenia żądania wystąpił błąd wewnętrzny w backendzie FCM lub że serwer jest tymczasowo niedostępny (np. z powodu przekroczenia limitu czasu). Nadawca musi spróbować ponownie później, pamiętając o przestrzeganiu wszystkich nagłówków Retry-After zawartych w odpowiedzi. Serwery aplikacji muszą implementować wykładnicze ponawianie. |
W tabeli poniżej znajdziesz pola w treści odpowiedzi wiadomości (JSON).
Parametr | Wykorzystanie | Opis |
---|---|---|
multicast_id |
Wymagana liczba | Unikalny identyfikator (numer) identyfikujący wiadomość multiemisji. |
success |
Wymagana liczba | Liczba wiadomości przetworzonych bez błędu. |
failure |
Wymagana liczba | Liczba wiadomości, których nie udało się przetworzyć. |
results |
Wymagana, tablica obiektów | Tablica obiektów reprezentujących stan przetworzonych wiadomości. Obiekty są wyświetlane w tej samej kolejności co żądanie (tzn. dla każdego identyfikatora rejestracji w żądaniu jego wynik jest wymieniany w tym samym indeksie w odpowiedzi).
|
Parametr | Wykorzystanie | Opis |
---|---|---|
message_id |
Opcjonalnie, liczba | Identyfikator wiadomości w temacie, gdy usługa FCM odebrała żądanie i spróbuje dostarczyć wiadomość na wszystkie subskrybowane urządzenia. |
error |
Opcjonalnie, ciąg znaków | Podczas przetwarzania wiadomości wystąpił błąd. Możliwe wartości można znaleźć w tabeli 9. |
Parametr | Wykorzystanie | Opis |
---|---|---|
id |
Wymagany, ciąg znaków | Ten parametr określa unikalny identyfikator wiadomości, która została przetworzona przez FCM. |
registration_id |
Opcjonalnie, ciąg znaków | Ten parametr określa token rejestracji aplikacji klienckiej, do której wiadomość została przetworzona i do której wysłano. |
Parametr | Wykorzystanie | Opis |
---|---|---|
Error |
Wymagany, ciąg znaków | Ten parametr określa wartość błędu podczas przetwarzania wiadomości dla odbiorcy. Szczegółowe informacje znajdziesz w tabeli 9. |
Kody odpowiedzi na błędy dotyczące komunikatu na końcu strumienia
W tabeli poniżej znajdziesz kody odpowiedzi na błędy dotyczące kolejnych wiadomości.
Błąd | Kod HTTP | Zalecane działanie |
---|---|---|
Brak tokena rejestracji | Błąd 200 +:brak rejestracji | Sprawdź, czy żądanie zawiera token rejestracji (w polu registration_id w postaci zwykłego tekstu albo w polu to lub registration_ids w formacie JSON). |
Nieprawidłowy token rejestracji | Błąd 200 + błąd:nieprawidłowa rejestracja | Sprawdź format tokena rejestracji przekazywanego do serwera. Upewnij się, że jest zgodny z tokenem rejestracji, który aplikacja kliencka otrzymuje podczas rejestracji w Powiadomieniach Firebase. Nie skracaj tekstu ani nie dodawaj dodatkowych znaków. |
Niezarejestrowane urządzenie | 200 + błąd:niezarejestrowany | Istniejący token rejestracji może przestać działać w różnych sytuacjach, takich jak:
|
Nieprawidłowa nazwa pakietu | 200 + błąd:nieprawidłowa nazwaPakietu | Sprawdź, czy wiadomość została zaadresowana na token rejestracji, którego nazwa pakietu odpowiada wartości przekazanej w żądaniu. |
Błąd uwierzytelniania | 401 | Nie udało się uwierzytelnić konta nadawcy użytego do wysłania wiadomości. Możliwe przyczyny:
|
Niezgodny nadawca | 200 + błąd:MismatchSenderId | Token rejestracji jest powiązany z określoną grupą nadawców. Gdy aplikacja kliencka rejestruje się w FCM, musi określać, którzy nadawcy mogą wysyłać wiadomości. Należy użyć jednego z tych identyfikatorów nadawcy podczas wysyłania wiadomości do aplikacji klienckiej. Jeśli zmienisz nadawcę, istniejące tokeny rejestracji nie będą działać. |
Nieprawidłowy plik JSON | 400 | Sprawdź, czy wiadomość JSON jest prawidłowo sformatowana i zawiera prawidłowe pola (np. czy jest przekazywany odpowiedni typ danych). |
Nieprawidłowe parametry | Błąd 400 + błąd:InvalidParameters | Sprawdź, czy podane parametry mają prawidłową nazwę i typ. |
Wiadomość jest za duża | 200 + błąd:MessageTooBig | 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 wysyłanych do tematów. Dotyczy to zarówno kluczy, jak i wartości. |
Nieprawidłowy klucz danych | Błąd 200 i błąd:
InvalidDataKey |
Sprawdź, czy dane ładunku nie zawierają klucza (np. 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 ) również są używane przez FCM, ale są dozwolone w ładunku. W takim przypadku wartość ładunku zostanie zastąpiona wartością FCM. |
Nieprawidłowy czas życia danych | Błąd 200 + błąd:nieprawidłowy tekst | Sprawdź, czy wartość używana w funkcji time_to_live jest liczbą całkowitą określającą czas trwania w sekundach z zakresu od 0 do 2 419 200 (4 tygodnie). |
Czas oczekiwania | 5xx lub 200 + błąd:niedostępny | Serwer nie mógł przetworzyć żądania na czas. Ponów to samo żądanie, ale musisz:
Nadawca, który powoduje problemy, może zostać umieszczony na czarnej liście. |
Wewnętrzny błąd serwera | 500 lub 200 + błąd:wewnętrzny błąd serwera | Podczas próby przetworzenia żądania serwer napotkał błąd. Możesz spróbować ponownie wysłać to samo żądanie, zgodnie z wymaganiami określonymi w sekcji „Limit czasu” (patrz wiersz powyżej). Jeśli błąd będzie się powtarzał, skontaktuj się z zespołem pomocy Firebase. |
Przekroczono liczbę wiadomości na urządzeniu | Błąd 200 i błąd:
DeviceMessageRate Przekroczono limit |
Ilość wiadomości wysyłanych do danego urządzenia jest zbyt duża. Jeśli aplikacja Apple wysyła wiadomości z częstotliwością przekraczającą limity APNs, może zobaczyć ten komunikat o błędzie Zmniejsz liczbę wiadomości wysyłanych na to urządzenie i ponawiaj próby wysłania za pomocą wykładniczego ponowienia. |
Przekroczony wskaźnik wiadomości z tematów | 200 i błąd:
TopicsMessageRate przekroczono |
Współczynnik wiadomości do subskrybentów danego tematu jest zbyt wysoki. Zmniejsz liczbę wiadomości wysyłanych w tym temacie i użyj wykładniczego ponowienia do ponawiania próby. |
Nieprawidłowe dane logowania APNs | Błąd 200 + błąd:
InvalidApnsCredential |
Nie udało się wysłać wiadomości skierowanej na urządzenie Apple, ponieważ wymagany klucz uwierzytelniania APNs nie został przesłany lub wygasł. Sprawdź poprawność swoich danych uwierzytelniających w programowaniu i produkcji. |
Zarządzanie grupami urządzeń
W tabeli poniżej znajdziesz klucze do tworzenia grup urządzeń oraz dodawania i usuwania użytkowników. Więcej informacji znajdziesz w przewodniku dotyczącym używanej platformy albo iOS+ lub Androida.
Parametr | Wykorzystanie | Opis |
---|---|---|
operation |
Wymagany, ciąg znaków | Operacja do wykonania.Prawidłowe wartości to create , add i remove . |
notification_key_name |
Wymagany, ciąg znaków | Zdefiniowana przez użytkownika nazwa grupy urządzeń, którą chcesz utworzyć lub zmodyfikować. |
notification_key |
Wymagane (oprócz operacji create , ciągu znaków |
Unikalny identyfikator grupy urządzeń. Ta wartość jest zwracana w odpowiedzi w przypadku udanej operacji create i jest wymagana przy wszystkich kolejnych operacjach na grupie urządzeń. |
registration_ids |
Wymagana, tablica ciągów tekstowych | Tokeny urządzeń do dodania lub usunięcia. Jeśli usuniesz z grupy urządzeń wszystkie istniejące tokeny rejestracji, FCM usunie tę grupę. |