Ten dokument zawiera omówienie składni HTTP używanej do przekazywania wiadomości z serwera aplikacji do aplikacji klienckich przez Firebase Cloud Messaging.
W przypadku 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 dzielą się na następujące ogólne 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 kolejnych komunikatów
W tej sekcji znajdziesz składnię służącą do wysyłania kolejnych wiadomości i interpretowania odpowiedzi HTTP z Komunikacji w chmurze Firebase (FCM).
Dodatkowe komunikaty HTTP (JSON)
W tabeli poniżej znajdziesz cele, opcje i ładunek dla wiadomości HTTP JSON.
Parametr | Wykorzystanie | Opis | |
---|---|---|---|
Cele | |||
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 |
|
registration_ids | Opcjonalny, tablica ciągów znaków |
Ten parametr określa adresata wiadomości multicast, czyli wiadomości wysłanej do więcej niż jednego tokena rejestracji.
Wartość powinna być tablicą tokenów rejestracji, do której ma zostać wysłany komunikat multicast. Tablica musi zawierać od 1 do 1000 tokenów rejestracji. Aby wysłać wiadomość na jedno urządzenie, użyj parametru Komunikaty multicast są dozwolone tylko w formacie HTTP JSON. |
|
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: |
|
notification_key Wycofano |
Opcjonalnie: ciąg znaków | Ten parametr został wycofany. Zamiast tego do określenia adresatów wiadomości użyj właściwości |
|
Opcje | |||
collapse_key |
Opcjonalnie: ciąg znaków | Ten parametr określa grupę wiadomości (np. Pamiętaj, że 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 |
|
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. |
|
restricted_package_
(tylko Android) |
Opcjonalnie: ciąg znaków | Ten parametr określa nazwę pakietu aplikacji, w której muszą pasować tokeny rejestracji, aby otrzymać wiadomość. | |
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 niestandardowe pary klucz-wartość ładunku wiadomości. Przykład: Na platformach Apple wiadomość jest wysyłana przez APN, czyli reprezentuje niestandardowe pola danych. Jeśli jest wysyłana przez FCM, w W przypadku Androida spowoduje 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 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 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. |
Dodatkowe komunikaty HTTP (zwykły tekst)
W tabeli poniżej znajdziesz składnię celów, opcji i ładunku w pobieranych wiadomościach HTTP w postaci zwykłego tekstu.
Parametr | Wykorzystanie | Opis |
---|---|---|
Cele | ||
registration_id |
Wymagany, ciąg znaków | Ten parametr określa aplikacje klienckie (tokeny rejestracji), które otrzymują wiadomość. Przesyłanie zbiorcze (na więcej niż 1 token rejestracji) jest dozwolone tylko przy użyciu formatu JSON HTTP. |
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 w postaci par klucz-wartość, ale obowiązuje limit łącznego rozmiaru wiadomości do 4096 bajtów. Na przykład w Androidzie użycie funkcji 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. |
Interpretowanie odpowiedzi wiadomości na dalszym etapie
Serwer aplikacji powinien ocenić nagłówek i treść wiadomości, by zinterpretować odpowiedź wysłaną z FCM. W tabeli poniżej opisujemy możliwe odpowiedzi.
Odpowiedź | Opis |
---|---|
200 | Wiadomość została przetworzona. Treść odpowiedzi zawiera więcej informacji o stanie wiadomości, ale jej format zależy od tego, czy żądanie było w formacie JSON, czy zwykłym tekstem. Więcej informacji znajdziesz w tabeli 5. |
400 | Dotyczy tylko żądań JSON. Wskazuje, że nie udało się przeanalizować żądania w formacie JSON lub zawierało ono nieprawidłowe pola (np. przekazano ciąg znaków z oczekiwaną liczbą). Dokładna przyczyna niepowodzenia jest podana w odpowiedzi, a problem należy rozwiązać, zanim będzie można ponowić próbę. |
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 FCM lub serwer jest tymczasowo niedostępny (np. z powodu przekroczenia limitu czasu oczekiwania). Nadawca musi spróbować ponownie później, uwzględniając wszystkie nagłówki Retry-After zawarte w odpowiedzi. Serwery aplikacji muszą implementować wykładniczy czas ponowienia. |
Poniższa tabela zawiera pola w treści odpowiedzi na wiadomość (JSON).
Parametr | Wykorzystanie | Opis |
---|---|---|
multicast_id |
Wymagany, liczba | Unikalny identyfikator (liczba) identyfikujący wiadomość w trybie multicast. |
success |
Wymagany, liczba | Liczba wiadomości przetworzonych bez błędu. |
failure |
Wymagany, 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ą wymienione w tej samej kolejności co żądanie (tzn. dla każdego identyfikatora rejestracji w żądaniu jego wynik jest wymieniony w odpowiedzi w tym samym indeksie).
|
Parametr | Wykorzystanie | Opis |
---|---|---|
message_id |
Opcjonalnie, liczba | Identyfikator wiadomości tematu, gdy FCM otrzyma żądanie i spróbuje przesłać ją na wszystkie subskrybowane urządzenia. |
error |
Opcjonalnie: ciąg znaków | Podczas przetwarzania wiadomości wystąpił błąd. Możliwe wartości znajdziesz w tabeli 9. |
Parametr | Wykorzystanie | Opis |
---|---|---|
id |
Wymagany, ciąg znaków | Ten parametr określa unikalny identyfikator wiadomości, który został przetworzony przez FCM. |
registration_id |
Opcjonalnie: ciąg znaków | Ten parametr określa token rejestracji aplikacji klienckiej, do której została przetworzona i wysłana wiadomość. |
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 w kolejnych komunikatach
Tabela poniżej zawiera kody odpowiedzi na błędy w kolejnych komunikatach.
Błąd | Kod HTTP | Zalecane działanie |
---|---|---|
Brak tokena rejestracji | Błąd 200 i brak rejestracji | 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łowy token rejestracji | 200 + błąd:nieprawidłowa rejestracja | Sprawdź format tokena rejestracji, który przekazujesz do serwera. Sprawdź, czy jest zgodny z tokenem rejestracji, który aplikacja kliencka otrzymuje po zarejestrowaniu się w Powiadomieniach Firebase. Nie skracaj ich ani nie dodawaj dodatkowych znaków. |
Niezarejestrowane urządzenie | 200+ błąd:Nie zarejestrowano | Dotychczasowy token rejestracji może stracić ważność w wielu sytuacjach, w tym:
|
Nieprawidłowa nazwa pakietu | 200 + błąd:InvalidPackageName | Sprawdź, czy wiadomość była zaadresowana na token rejestracji, którego nazwa pakietu pasuje do 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 i błąd:MismatchSenderId | 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 | 400 | Sprawdź, czy wiadomość JSON jest poprawnie sformatowana i zawiera prawidłowe pola (np. czy przekazujesz właściwy typ danych). |
Nieprawidłowe parametry | 400 + błąd:NieprawidłoweParametry | Sprawdź, czy podane parametry mają właściwą 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 do tematów. Dotyczy to zarówno kluczy, jak i wartości. |
Nieprawidłowy klucz danych | 200 + błąd:
InvalidDataKey |
Sprawdź, czy dane ładunku nie zawierają klucza (takiego jak from lub 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 zostanie zastąpiona wartością FCM. |
Nieprawidłowy czas życia | 200 + błąd:InvalidTtl | 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). |
Czas oczekiwania | 5xx lub 200 + błąd:niedostępne | Serwer nie mógł przetworzyć żądania na czas. Ponów tę samą prośbę, ale musisz:
Nadawcy, którzy powodują problemy, mogą zostać umieszczone 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 ponowić 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 częstotliwość wiadomości z urządzenia | 200 + błąd:
DeviceMessageRate Przekroczono limit |
Częstotliwość wiadomości do konkretnego urządzenia jest za 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 do tego urządzenia i użyj wykładniczego ponawiania w celu ponowienia próby wysłania. |
Przekroczono częstotliwość wiadomości z tematów | 200 + błąd:
TopicsMessageRate Przekroczono limit |
Częstotliwość wiadomości do subskrybentów określonego tematu jest zbyt duża. Zmniejsz liczbę wiadomości wysyłanych w tym temacie i użyj wykładniczego czasu ponowienia, aby ponowić próbę wysłania. |
Nieprawidłowe dane logowania APNs | 200 i błąd:
InvalidApnsCredential |
Nie można wysłać wiadomości kierowanej na urządzenie Apple, ponieważ wymagany klucz uwierzytelniania APNs nie został przesłany lub wygasł. Sprawdź poprawność danych logowania do środowiska programistycznego i produkcyjnego. |
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 Twojej platformy, iOS+ lub Androida.
Parametr | Wykorzystanie | Opis |
---|---|---|
operation |
Wymagany, ciąg znaków | Operacja do uruchomienia.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 |
Wymagany (oprócz operacji create , ciąg znaków) |
Unikalny identyfikator grupy urządzeń. Ta wartość jest zwracana w odpowiedzi dla udanej operacji create i jest wymagana przy wszystkich kolejnych operacjach na grupie urządzeń. |
registration_ids |
Wymagana tablica ciągów znaków | Tokeny urządzeń, które chcesz dodać lub usunąć. Jeśli usuniesz wszystkie istniejące tokeny rejestracji z grupy urządzeń, FCM usunie tę grupę. |