Ten dokument zawiera informacje na temat składni HTTP używanej do przekazywania wiadomości z serwera aplikacji do aplikacji klienckich za pośrednictwem 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 można podzielić na następujące szerokie kategorie:
Składnia wiadomości niższej
W tej sekcji przedstawiono składnię wysyłania wiadomości podrzędnych i interpretowania odpowiedzi HTTP z Firebase Cloud Messaging.
Podrzędne wiadomości HTTP (JSON)
W poniższej tabeli wymieniono elementy docelowe, opcje i ładunek komunikatów HTTP JSON.
Parametr | Stosowanie | Opis | |
---|---|---|---|
Cele | |||
to | Opcjonalnie, ciąg | Ten parametr określa odbiorcę wiadomości. Wartością może być token rejestracji urządzenia, klucz powiadomienia grupy urządzeń lub pojedynczy temat (poprzedzony prefiksem | |
registration_ids | Opcjonalnie tablica ciągów | Parametr ten określa odbiorcę wiadomości multicast, czyli wiadomości wysyłanej do więcej niż jednego tokena rejestracyjnego. Wartość powinna być tablicą tokenów rejestracji, do których ma zostać wysłany komunikat multiemisji. Tablica musi zawierać co najmniej 1 i maksymalnie 1000 tokenów rejestracyjnych. Aby wysłać wiadomość do pojedynczego urządzenia, użyj parametru Wiadomości multiemisji są dozwolone wyłącznie w formacie HTTP JSON. | |
condition | Opcjonalnie, ciąg | Ten parametr określa logiczne wyrażenie warunków określających miejsce docelowe komunikatu. Obsługiwany warunek: temat w formacie „twój temat” w tematach. W tej wartości wielkość liter nie jest uwzględniana. Obsługiwane operatory: | |
notification_key Przestarzałe | Opcjonalnie, ciąg | Ten parametr jest przestarzały. Zamiast tego użyj | |
Opcje | |||
collapse_key | Opcjonalnie, ciąg | Ten parametr identyfikuje grupę wiadomości (np. z Pamiętaj, że nie ma gwarancji kolejności wysyłania wiadomości. Uwaga: w danym momencie dozwolone są maksymalnie 4 różne klawisze 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 zwinięcia FCM zachowa. | |
priority | Opcjonalnie, ciąg | Ustawia priorytet wiadomości. Prawidłowe wartości to „normalny” i „wysoki”. Na platformach Apple odpowiadają one priorytetom APN 5 i 10. Domyślnie powiadomienia są wysyłane z wysokim priorytetem, a wiadomości z danymi są wysyłane z normalnym priorytetem. Priorytet normalny optymalizuje zużycie baterii aplikacji klienckiej i powinien być używany, chyba że wymagana jest natychmiastowa dostawa. W przypadku wiadomości o normalnym priorytecie aplikacja może odebrać wiadomość z nieokreślonym opóźnieniem. Jeśli wiadomość ma wysoki priorytet, zostanie wysłana natychmiast, a aplikacja może wyświetlić powiadomienie. | |
content_available | Opcjonalnie, wartość logiczna | Na platformach Apple użyj tego pola, aby przedstawić | |
mutable_content | Opcjonalnie wartość logiczna JSON | Na platformach Apple użyj tego pola, aby reprezentować | |
time_to_live | Opcjonalnie, liczba | Ten parametr określa, jak długo (w sekundach) wiadomość powinna być przechowywana w pamięci FCM, jeśli urządzenie jest w trybie offline. Maksymalny obsługiwany czas życia wynosi 4 tygodnie, a wartość domyślna to 4 tygodnie. Aby uzyskać więcej informacji, zobacz Ustawianie czasu życia wiadomości . | |
restricted_package_ (tylko Android) | Opcjonalnie, ciąg | Ten parametr określa nazwę pakietu aplikacji, do którego muszą pasować tokeny rejestracji, aby otrzymać wiadomość. | |
dry_run | Opcjonalnie, wartość logiczna | Ten parametr, gdy jest ustawiony na Wartość domyślna to | |
Ładunek | |||
data | Opcjonalnie, obiekt | Ten parametr określa niestandardowe pary klucz-wartość ładunku wiadomości. Na przykład z Na platformach Apple, jeśli wiadomość jest wysyłana za pośrednictwem APN, reprezentuje niestandardowe pola danych. Jeśli zostanie wysłany przez FCM, będzie reprezentowany jako słownik wartości klucza w W systemie Android spowodowałoby to dodatkowy, nazwany Klucz nie powinien być słowem zastrzeżonym („from”, „typ_wiadomości” ani żadnym słowem zaczynającym się od „google” lub „gcm”). Nie używaj żadnych słów zdefiniowanych w tej tabeli (takich jak Zalecane są wartości w typach łańcuchowych. 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 | Opcjonalnie, obiekt | Ten parametr określa wstępnie zdefiniowane, widoczne dla użytkownika pary klucz-wartość ładunku powiadomienia. Aby uzyskać szczegółowe informacje, zobacz Obsługa ładunku powiadomień. Aby uzyskać więcej informacji na temat opcji wiadomości powiadamiających i wiadomości z danymi, zobacz Typy wiadomości . Jeśli dostarczono ładunek powiadomienia lub opcja content_available jest ustawiona na true dla wiadomości kierowanej do urządzenia Apple, wiadomość jest wysyłana za pośrednictwem APN , w przeciwnym razie jest wysyłana za pośrednictwem FCM. |
Obsługa ładunku powiadomień
W poniższych tabelach wymieniono predefiniowane klucze dostępne do tworzenia komunikatów powiadomień dla systemów iOS i Android.
Parametr | Stosowanie | Opis |
---|---|---|
title | Opcjonalnie, ciąg | Tytuł powiadomienia. To pole nie jest widoczne na telefonach i tabletach. |
body | Opcjonalnie, ciąg | Treść powiadomienia. |
sound | Opcjonalnie, ciąg | Dźwięk odtwarzany, gdy urządzenie odbierze powiadomienie. Ciąg określający pliki dźwiękowe w głównym pakiecie aplikacji klienckiej lub w folderze |
badge | Opcjonalnie, ciąg | Wartość odznaki na ikonie aplikacji na ekranie głównym. Jeśli nie określono inaczej, odznaka nie ulega zmianie. Jeśli ustawione na |
click_action | Opcjonalnie, ciąg | Akcja powiązana z kliknięciem przez użytkownika powiadomienia. Odpowiada |
subtitle | Opcjonalnie, ciąg | Podtytuł powiadomienia. |
body_loc_key | Opcjonalnie, ciąg | Klucz do ciągu treści w zasobach ciągu aplikacji, który ma być używany do lokalizowania tekstu treści w bieżącej lokalizacji użytkownika. Odpowiada Aby uzyskać więcej informacji, zobacz Informacje o kluczu ładunku i Lokalizowanie zawartości zdalnych powiadomień . |
body_loc_args | Opcjonalnie tablica JSON jako ciąg znaków | Zmienne wartości ciągu, które mają być używane zamiast specyfikatorów formatu w Odpowiada Aby uzyskać więcej informacji, zobacz Informacje o kluczu ładunku i Lokalizowanie zawartości zdalnych powiadomień . |
title_loc_key | Opcjonalnie, ciąg | Klucz do ciągu tytułu w zasobach ciągu aplikacji, który ma być używany do lokalizowania tekstu tytułu w bieżącej lokalizacji użytkownika. Odpowiada Aby uzyskać więcej informacji, zobacz Informacje o kluczu ładunku i Lokalizowanie zawartości zdalnych powiadomień . |
title_loc_args | Opcjonalnie tablica JSON jako ciąg znaków | Zmienne wartości ciągów, które mają być używane zamiast specyfikatorów formatu w Odpowiada Aby uzyskać więcej informacji, zobacz Informacje o kluczu ładunku i Lokalizowanie zawartości zdalnych powiadomień . |
Parametr | Stosowanie | Opis |
---|---|---|
title | Opcjonalnie, ciąg | Tytuł powiadomienia. |
body | Opcjonalnie, ciąg | Treść powiadomienia. |
android_channel_id | Opcjonalnie, ciąg | Identyfikator kanału powiadomienia (nowość w Androidzie O). Aplikacja musi utworzyć kanał z tym identyfikatorem kanału, zanim otrzymane zostanie powiadomienie z tym identyfikatorem kanału. 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 | Ikona powiadomienia. Ustawia ikonę powiadomienia na |
sound | Opcjonalnie, ciąg | Dźwięk odtwarzany, gdy urządzenie odbierze powiadomienie. Obsługuje |
tag | Opcjonalnie, ciąg | Identyfikator używany do zastąpienia istniejących powiadomień w szufladzie powiadomień. Jeśli nie określono, każde żądanie tworzy nowe powiadomienie. Jeśli zostało to określone, a powiadomienie z tym samym tagiem jest już wyświetlane, nowe powiadomienie zastępuje istniejące w szufladzie powiadomień. |
color | Opcjonalnie, ciąg | Kolor ikony powiadomienia wyrażony w formacie |
click_action | Opcjonalnie, ciąg | Akcja powiązana z kliknięciem przez użytkownika powiadomienia. Jeśli określono, działanie z pasującym filtrem intencji zostanie uruchomione, gdy użytkownik kliknie powiadomienie. |
body_loc_key | Opcjonalnie, ciąg | Klucz do ciągu treści w zasobach ciągu aplikacji, który ma być używany do lokalizowania tekstu treści w bieżącej lokalizacji użytkownika. Aby uzyskać więcej informacji, zobacz Zasoby ciągów . |
body_loc_args | Opcjonalnie tablica JSON jako ciąg znaków | Zmienne wartości ciągu, które mają być używane zamiast specyfikatorów formatu w Aby uzyskać więcej informacji, zobacz Formatowanie i stylizacja . |
title_loc_key | Opcjonalnie, ciąg | Klucz do ciągu tytułu w zasobach ciągu aplikacji, który ma być używany do lokalizowania tekstu tytułu w bieżącej lokalizacji użytkownika. Aby uzyskać więcej informacji, zobacz Zasoby ciągów . |
title_loc_args | Opcjonalnie tablica JSON jako ciąg znaków | Zmienne wartości ciągów, które mają być używane zamiast specyfikatorów formatu w Aby uzyskać więcej informacji, zobacz Formatowanie i stylizacja . |
Parametr | Stosowanie | Opis |
---|---|---|
title | Opcjonalnie, ciąg | Tytuł powiadomienia. |
body | Opcjonalnie, ciąg | Treść powiadomienia. |
icon | Opcjonalnie, ciąg | Adres URL ikony powiadomienia. |
click_action | Opcjonalnie, ciąg | Akcja powiązana z kliknięciem przez użytkownika powiadomienia. W przypadku wszystkich wartości adresów URL wymagany jest protokół HTTPS. |
Dalsze wiadomości HTTP (zwykły tekst)
W poniższej tabeli wymieniono składnię elementów docelowych, opcji i ładunku w postaci zwykłego tekstu w komunikatach HTTP.
Parametr | Stosowanie | Opis |
---|---|---|
Cele | ||
registration_id | Wymagane, ciąg | Ten parametr określa aplikacje klienckie (token rejestracji) odbierające wiadomość. Przesyłanie wiadomości multiemisji (wysyłanie do więcej niż jednego tokenu rejestracyjnego) jest dozwolone wyłącznie przy użyciu formatu HTTP JSON. |
Opcje | ||
collapse_key | Opcjonalnie, ciąg | Szczegółowe informacje można znaleźć w tabeli 1 . |
time_to_live | Opcjonalnie, liczba | Szczegółowe informacje można znaleźć w tabeli 1 . |
restricted_package_name | Opcjonalnie, ciąg | Szczegółowe informacje można znaleźć w tabeli 1 . |
dry_run | Opcjonalnie, wartość logiczna | Szczegółowe informacje można znaleźć w tabeli 1 . |
Ładunek | ||
data.<key> | Opcjonalnie, ciąg | Ten parametr określa pary klucz-wartość ładunku wiadomości. Nie ma ograniczenia liczby parametrów klucz-wartość, ale całkowity rozmiar wiadomości wynosi 4000 bajtów. Na przykład w systemie Android Klucz nie powinien być słowem zastrzeżonym („from”, „typ_wiadomości” ani żadnym słowem zaczynającym się od „google” lub „gcm”). Nie używaj żadnych słów zdefiniowanych w tej tabeli (takich jak |
Interpretowanie dalszej odpowiedzi na komunikat
Serwer aplikacji powinien ocenić zarówno nagłówek odpowiedzi na wiadomość, jak i treść, aby zinterpretować odpowiedź na wiadomość wysłaną z FCM. W poniższej tabeli opisano możliwe odpowiedzi.
Odpowiedź | Opis |
---|---|
200 | Wiadomość została pomyślnie przetworzona. Treść odpowiedzi będzie zawierać więcej szczegółów na temat statusu 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 szczegółów można znaleźć w tabeli 5 . |
400 | Dotyczy tylko żądań JSON. Wskazuje, że żądania nie można było przeanalizować jako JSON lub zawierało nieprawidłowe pola (na przykład przekazanie ciągu znaków w miejscu, w którym oczekiwano liczby). Dokładna przyczyna niepowodzenia jest opisana w odpowiedzi, a problem należy rozwiązać, zanim będzie można ponowić żądanie. |
401 | Wystąpił błąd podczas uwierzytelniania konta nadawcy. |
5xx | Błędy w zakresie 500–599 (takie jak 500 lub 503) wskazują, że podczas próby przetworzenia żądania wystąpił błąd wewnętrzny w zapleczu FCM lub że serwer jest tymczasowo niedostępny (na przykład z powodu przekroczenia limitu czasu). Nadawca musi ponowić próbę później, uwzględniając nagłówek Retry-After zawarty w odpowiedzi. Serwery aplikacji muszą implementować wykładnicze wycofywanie. |
W poniższej tabeli wymieniono pola w treści odpowiedzi na komunikat podrzędny (JSON).
Parametr | Stosowanie | Opis |
---|---|---|
multicast_id | Wymagane, numer | Unikalny identyfikator (numer) identyfikujący wiadomość multiemisji. |
success | Wymagane, numer | Liczba wiadomości, które zostały przetworzone bez błędu. |
failure | Wymagane, numer | Liczba wiadomości, których nie można przetworzyć. |
results | Wymagane, tablica obiektów | Tablica obiektów reprezentujących status przetworzonych wiadomości. Obiekty są wymienione w tej samej kolejności, co żądanie (tj. dla każdego identyfikatora rejestracji w żądaniu jego wynik znajduje się w tym samym indeksie w odpowiedzi).
|
Parametr | Stosowanie | Opis |
---|---|---|
message_id | Opcjonalnie, liczba | Identyfikator wiadomości tematu, gdy FCM pomyślnie odbierze żądanie i podejmie próbę dostarczenia go do wszystkich subskrybowanych urządzeń. |
error | Opcjonalnie, ciąg | Błąd, który wystąpił podczas przetwarzania wiadomości. Możliwe wartości można znaleźć w tabeli 9 . |
Parametr | Stosowanie | Opis |
---|---|---|
id | Wymagane, ciąg | Ten parametr określa unikalny identyfikator komunikatu FCM, który został pomyślnie przetworzony. |
registration_id | Opcjonalnie, ciąg | Ten parametr określa token rejestracji dla aplikacji klienckiej, do której wiadomość została przetworzona i wysłana. |
Parametr | Stosowanie | Opis |
---|---|---|
Error | Wymagane, ciąg | Parametr ten określa wartość błędu podczas przetwarzania wiadomości dla odbiorcy. Szczegółowe informacje można znaleźć w tabeli 9 . |
Kody odpowiedzi na błędy komunikatów dalszych
W poniższej tabeli wymieniono kody odpowiedzi na błędy dla komunikatów dalszych.
Błąd | Kod HTTP | Rekomendowane działanie |
---|---|---|
Brak tokena rejestracyjnego | 200 + błąd: Brak rejestracji | Sprawdź, czy żądanie zawiera token rejestracji (w polu registration_id w wiadomości tekstowej lub w polu to lub registration_ids w formacie JSON). |
Nieprawidłowy token rejestracyjny | 200 + błąd: Nieprawidłowa rejestracja | Sprawdź format tokena rejestracyjnego przekazywanego do serwera. Upewnij się, że jest zgodny z tokenem rejestracji, który aplikacja kliencka otrzymuje podczas rejestracji w Firebase Notifications. Nie obcinaj ani nie dodawaj dodatkowych znaków. |
Niezarejestrowane urządzenie | 200 + błąd: Niezarejestrowany | Istniejący token rejestracyjny może utracić ważność w wielu scenariuszach, w tym:
|
Nieprawidłowa nazwa pakietu | 200 + błąd: InvalidPackageName | Upewnij się, że wiadomość została zaadresowana do tokena rejestracyjnego, którego nazwa pakietu odpowiada wartości przekazanej w żądaniu. |
Błąd autoryzacji | 401 | Nie można uwierzytelnić konta nadawcy użytego do wysłania wiadomości. Możliwe przyczyny to:
|
Niedopasowany nadawca | 200 + błąd: MismatchSenderId | Token rejestracyjny 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. Podczas wysyłania wiadomości do aplikacji klienckiej należy używać jednego z tych identyfikatorów nadawcy. Jeśli zmienisz nadawcę, istniejące tokeny rejestracyjne przestaną działać. |
Nieprawidłowy JSON | 400 | Sprawdź, czy wiadomość JSON jest poprawnie sformatowana i zawiera prawidłowe pola (np. upewnij się, że przekazywany jest właściwy typ danych). |
Niepoprawne parametry | 400 + błąd: Nieprawidłowe parametry | Sprawdź, czy podane parametry mają właściwą nazwę i typ. |
Wiadomość jest zbyt duża | 200 + błąd: WiadomośćTooBig | Sprawdź, czy całkowity rozmiar danych zawartych w wiadomości nie przekracza limitów FCM: 4096 bajtów dla 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: Nieprawidłowy klucz danych | Sprawdź, czy dane ładunku nie zawierają klucza (takiego jak from lub gcm lub jakakolwiek wartość poprzedzona przez google ), który jest używany wewnętrznie przez FCM. Należy zauważyć, że niektóre słowa (takie jak 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żyta w time_to_live jest liczbą całkowitą reprezentującą czas trwania w sekundach z zakresu od 0 do 2 419 200 (4 tygodnie). |
Koniec czasu | Błąd 5xx lub 200 +: Niedostępny | Serwer nie mógł przetworzyć żądania na czas. Ponów tę samą prośbę, ale musisz:
Nadawcy powodujący problemy mogą zostać umieszczeni na czarnej liście. |
Wewnętrzny błąd serwera | 500 lub 200 + błąd:InternalServerError | Serwer napotkał błąd podczas próby przetworzenia żądania. Możesz ponowić tę samą prośbę, spełniając wymagania wymienione w „Limicie czasu” (patrz wiersz powyżej). Jeśli błąd będzie się powtarzał, skontaktuj się z pomocą techniczną Firebase . |
Przekroczono częstotliwość komunikatów urządzenia | 200 + błąd: Szybkość wiadomości urządzenia Przekroczono | Szybkość wysyłania wiadomości do określonego urządzenia jest zbyt wysoka. Jeśli aplikacja Apple wysyła wiadomości z szybkością przekraczającą limity APN, może pojawić się ten komunikat o błędzie Zmniejsz liczbę wiadomości wysyłanych na to urządzenie i użyj wykładniczego wycofywania, aby ponowić próbę wysłania. |
Przekroczono częstotliwość wiadomości w tematach | 200 + błąd: TematyWiadomośćStawka Przekroczono | Liczba wiadomości do subskrybentów na dany temat jest zbyt wysoka. Zmniejsz liczbę wiadomości wysyłanych w tym temacie i użyj wykładniczego wycofywania, aby ponowić próbę wysłania. |
Nieprawidłowe poświadczenia APN | 200 + błąd: Nieprawidłowe poświadczenie Apns | Nie można wysłać wiadomości kierowanej do urządzenia Apple, ponieważ wymagany klucz uwierzytelniający APN nie został przesłany lub wygasł. Sprawdź ważność swoich uprawnień programistycznych i produkcyjnych. |
Zarządzanie grupą urządzeń
W poniższej tabeli wymieniono klawisze służące do tworzenia grup urządzeń oraz dodawania i usuwania członków. Więcej informacji znajdziesz w przewodniku dla Twojej platformy, iOS+ lub Androida .
Parametr | Stosowanie | Opis |
---|---|---|
operation | Wymagane, ciąg | Operacja do uruchomienia. Prawidłowe wartości to: create , add i remove . |
notification_key_name | Wymagane, ciąg | Zdefiniowana przez użytkownika nazwa grupy urządzeń, która ma zostać utworzona lub zmodyfikowana. |
notification_key | Wymagane (z wyjątkiem operacji create , string | Unikalny identyfikator grupy urządzeń. Ta wartość jest zwracana w odpowiedzi na pomyślną operację create i jest wymagana dla wszystkich kolejnych operacji na grupie urządzeń. |
registration_ids | Wymagane, tablica ciągów | Tokeny urządzeń do dodania lub usunięcia. Jeśli usuniesz wszystkie istniejące tokeny rejestracji z grupy urządzeń, FCM usunie tę grupę urządzeń. |