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 należą do 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 ich 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, identyfikator grupy urządzeń
klucza powiadomień lub pojedynczego tematu (z przedrostkiem
|
|
registration_ids | Opcjonalny, tablica ciągów znaków |
Ten parametr określa adresata wiadomości multicast, wysłane do więcej niż jednego tokena rejestracji.
Wartość powinna być tablicą tokenów rejestracji, do których ma zostać wysłana
wiadomość grupową. Tablica musi zawierać od 1 do 1000
tokeny rejestracji. Aby wysłać wiadomość na jedno urządzenie, użyj
Komunikaty multicast są dozwolone tylko w formacie HTTP JSON. |
|
condition |
Opcjonalnie: ciąg znaków | Ten parametr określa wyrażenie logiczne warunków, które określić 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: |
|
notification_key Wycofano |
Opcjonalnie: ciąg znaków | Ten parametr został wycofany. Zamiast tego użyj |
|
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 na aplikację kliencką. Jeśli przekracza 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” 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żyj tego pola do reprezentowania tego pola w polu |
|
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 czas (w sekundach), przez jaki 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 aby otrzymać wiadomość, tokeny rejestracji muszą być takie same. | |
dry_run |
Opcjonalne, wartość logiczna | Po ustawieniu tego parametru na 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 spowodowałoby 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ść:
ładunek powiadomień. Szczegółowe informacje znajdziesz w artykule dotyczącym obsługi ładunku powiadomień.
Aby dowiedzieć się więcej o opcjach wiadomości z powiadomieniami i wiadomości zawierających dane,
zobacz
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 klawiszy dostępnych do tworzenia wiadomości z powiadomieniami w iOS 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 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 utworzony 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 być używany 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. |
Dodatkowe komunikaty HTTP (zwykły tekst)
W poniższej tabeli podano wprost składnię celów, opcji i ładunku otrzymywane SMS-y.
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 klucz-wartość, ale obowiązuje limit 4096 bajtów. Na przykład na Androidzie użycie funkcji 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. |
Interpretowanie odpowiedzi wiadomości na dalszym etapie
Serwer aplikacji powinien ocenić zarówno nagłówek odpowiedzi, jak i treść wiadomości interpretowanie odpowiedzi wiadomości wysłanej z FCM. Tabela poniżej opisuje możliwe odpowiedzi.
Odpowiedź | Opis |
---|---|
200 | Wiadomość została przetworzona. Treść odpowiedzi będzie zawierać więcej szczegółowych informacji o stanie wiadomości. Jednak jej format zależy od tego, czy żądanie jest format JSON lub zwykły tekst. Patrz tabela 5 . |
400 | Dotyczy tylko żądań JSON. Wskazuje, że nie udało się przeanalizować żądania jako pliku JSON lub zawierało ono nieprawidłowe dane (np. przez przekazanie ciągu znaków, gdzie oczekiwano liczby). Dokładny przyczyna niepowodzenia jest opisana w odpowiedzi i należy rozwiązać problem przed ponowną próbą przesłania żądania. |
401 | Podczas uwierzytelniania konta nadawcy wystąpił błąd. |
5xx | Błędy z zakresu 500–599 (np. 500 lub 503) wskazują, że został
podczas próby przetworzenia żądania wystąpił błąd wewnętrzny FCM,
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 parametrze
. Serwery aplikacji muszą implementować wykładniczy czas ponowienia. |
Tabela poniżej zawiera listę pól w treści odpowiedzi wiadomości podrzędnej (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 w żądaniu (tzn. dla każdej rejestracji
identyfikator w żądaniu; wynik jest wymieniony w tym samym indeksie w odpowiedzi).
|
Parametr | Wykorzystanie | Opis |
---|---|---|
message_id |
Opcjonalnie, liczba | identyfikator wiadomości dotyczącej tematu, jeśli FCM otrzymało żądanie, oraz spróbuje przesłać reklamę na wszystkie urządzenia objęte subskrypcją. |
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ł wysłany komunikat przetworzone i wysłane do. |
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 tagu
registration_id w wiadomości tekstowej lub w aplikacji to
lub registration_ids w formacie JSON). |
Nieprawidłowy token rejestracji | 200 + błąd:Nieprawidłowa rejestracja | Sprawdź format tokena rejestracji, który przekazujesz do serwera. Sprawdź, czy pasuje do tokena rejestracji, który aplikacja kliencka otrzymuje po rejestracji w Firebase Powiadomienia. Nie skracaj ich ani nie dodawaj dodatkowych znaków. |
Niezarejestrowane urządzenie | 200+ błąd:Nie zarejestrowano | Istniejący token rejestracji może stracić ważność w wielu sytuacjach, takich jak:
|
Nieprawidłowa nazwa pakietu | 200 + błąd:InvalidPackageName | Upewnij się, że wiadomość była zaadresowana na token rejestracji, którego nazwa pakietu pasuje do wartości przekazywanej 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 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 | 400 | Sprawdź, czy wiadomość JSON jest prawidłowo sformatowana i zawiera prawidłowe pola (np. sprawdzając, czy przekazano odpowiedni 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 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 | 200 i błąd:
Nieprawidłowy klucz danych |
Sprawdź, czy dane ładunku nie zawierają klucza (np. from ,
lub 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 FCM, ale są dozwolone w ładunku, gdzie
W takim przypadku wartość ładunku zostanie zastąpiona wartością z FCM. |
Nieprawidłowy czas życia | 200 + błąd:InvalidTtl | 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). |
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 spróbować jeszcze raz to samo żądanie zgodnie z wymaganiami wymienionymi w sekcji „Limit czasu” (zobacz wiersz powyżej). Jeśli błąd skontaktuj się z zespołem pomocy Firebase. |
Przekroczono częstotliwość wiadomości z urządzenia | 200 i błąd:
Częstotliwość wiadomości na urządzeniu 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 wysłanych na to urządzenie oraz użyj wykładniczego ponowienia aby spróbować wysłać ponownie. |
Przekroczono częstotliwość wiadomości z tematów | 200 i błąd:
TopicsMessageRate Przekroczono limit |
Częstotliwość wiadomości do subskrybentów określonego tematu jest zbyt duża. Zmniejsz liczbę wysłanych wiadomości dla tego tematu oraz użyj wykładniczego ponowienia aby spróbować wysłać ponownie. |
Nieprawidłowe dane logowania APNs | 200 i błąd:
Nieprawidłowe dane logowania API |
Nie udało się wysłać wiadomości kierowanej na urządzenie Apple, ponieważ wymagane punkty APN nie przesłano klucza uwierzytelniania lub wygasł. Sprawdzanie poprawności projektu i weryfikacja w środowisku produkcyjnym. |
Zarządzanie grupami urządzeń
W tabeli poniżej znajdziesz listę kluczy do tworzenia grup urządzeń oraz dodawanie i usuwanie członków. Więcej informacji: dla swojej platformy, iOS+ lub na urządzeniu z Androidem.
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 zwracany w odpowiedzi na żądanie create
i jest
wymagane do wszystkich kolejnych operacji w 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ę. |