Informacje o wiadomościach w FCM

Firebase Cloud Messaging (FCM) oferuje szeroki zakres opcji i funkcji przesyłania wiadomości. Informacje na tej stronie mają pomóc Ci zrozumieć różne typy FCM wiadomości i dowiedzieć się, co możesz z nimi zrobić.

Rodzaje wiadomości

Za pomocą FCM możesz wysyłać do klientów 2 rodzaje wiadomości:

• Wiadomości z powiadomieniami, czasami nazywane „wiadomościami wyświetlanymi”. Są one obsługiwane automatycznie przez pakiet FCM SDK.
• Wiadomości z danymi, które są obsługiwane przez aplikację kliencką.

Powiadomienia zawierają wstępnie zdefiniowany zestaw kluczy widocznych dla użytkownika. Wiadomości z danymi zawierają natomiast tylko zdefiniowane przez Ciebie niestandardowe pary klucz-wartość. Wiadomości z powiadomieniami mogą zawierać opcjonalny ładunek danych. Maksymalny rozmiar ładunku w przypadku obu typów wiadomości to 4096 bajtów, z wyjątkiem wysyłania wiadomości z Firebase konsoli, w której obowiązuje limit 1000 znaków.

	Scenariusz użycia	Jak wysłać
Treść powiadomienia	FCM Pakiet SDK wyświetla wiadomość na urządzeniach użytkowników w imieniu aplikacji klienckiej, gdy działa ona w tle. W przeciwnym razie, jeśli aplikacja działa na pierwszym planie w momencie otrzymania powiadomienia, jej kod określa zachowanie. Wiadomości z powiadomieniami mają wstępnie zdefiniowany zestaw kluczy widocznych dla użytkownika i opcjonalny ładunek danych w postaci niestandardowych par klucz-wartość.	W zaufanym środowisku, np. Cloud Functions lub na serwerze aplikacji, użyj pakietu Admin SDK lub interfejsu HTTP v1 API. Ustaw klucz notification. Może zawierać opcjonalny ładunek danych. Zawsze można je zwinąć. Zobacz kilka przykładów powiadomień displayowych i ładunków żądań wysyłania. Użyj kompozytora powiadomień: wpisz tekst wiadomości, tytuł itp. i wyślij. Dodaj opcjonalny ładunek danych, podając dane niestandardowe.
Wiadomość z danymi	Za przetwarzanie wiadomości z danymi odpowiada aplikacja klienta. Wiadomości z danymi zawierają tylko niestandardowe pary klucz-wartość bez zarezerwowanych nazw kluczy (patrz poniżej).	W zaufanym środowisku, takim jak Cloud Functions lub serwer aplikacji, użyj pakietu Admin SDK lub protokołów serwera FCM. W żądaniu wysyłania ustaw klucz data.

Używaj wiadomości z powiadomieniami, gdy chcesz, aby pakiet SDK FCMautomatycznie wyświetlał powiadomienieFCM, gdy aplikacja działa w tle. Wiadomości z danymi stosuje się, gdy chcesz przetwarzać wiadomości za pomocą własnego kodu aplikacji klienckiej.

FCM może wysłać powiadomienie zawierające opcjonalny ładunek danych. W takich przypadkach FCM wyświetla ładunek powiadomienia, a aplikacja kliencka obsługuje ładunek danych.

Wiadomości z powiadomieniami

Na potrzeby testowania lub marketingu i ponownego angażowania użytkowników możesz wysyłać wiadomości z powiadomieniami za pomocą Firebasekonsoli. Firebase Konsola udostępnia oparte na analizach testy A/B, które pomagają udoskonalać i ulepszać komunikaty marketingowe.

Aby programowo wysyłać wiadomości z powiadomieniami za pomocą pakietu Admin SDK lub protokołów FCM, ustaw klucz notification z niezbędnym predefiniowanym zestawem opcji klucz-wartość dla widocznej dla użytkownika części wiadomości z powiadomieniem. Oto przykład wiadomości z powiadomieniem w formacie JSON w aplikacji do przesyłania wiadomości. Użytkownik może zobaczyć na urządzeniu wiadomość z tytułem „Portugalia vs. Dania” i tekstem „świetny mecz!”:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    }
  }
}

Gdy aplikacja działa w tle, wiadomości z powiadomieniami są dostarczane do obszaru powiadomień. W przypadku aplikacji działających na pierwszym planie wiadomości są obsługiwane przez funkcję wywołania zwrotnego.

Pełną listę wstępnie zdefiniowanych kluczy dostępnych do tworzenia wiadomości z powiadomieniami znajdziesz w dokumentacji referencyjnej obiektu powiadomienia protokołu HTTP w wersji 1.

Wiadomości z danymi

Ustaw odpowiedni klucz z niestandardowymi parami klucz-wartość, aby wysłać do aplikacji klienta ładunek danych.

Upewnij się, że w niestandardowych parach klucz-wartość nie używasz żadnych słów zastrzeżonych. Zastrzeżone słowa to m.in. „from”, „notification”, „message_type” oraz wszystkie słowa zaczynające się od „google” lub „gcm”.

Oto przykład wiadomości w formacie JSON w tej samej aplikacji do przesyłania wiadomości co powyżej, w której informacje są zamknięte w kluczu data, a aplikacja kliencka ma interpretować treść:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    }
  }
}

Powyższy przykład pokazuje użycie pola najwyższego poziomu lub wspólnego pola data, które jest interpretowane przez klientów na wszystkich platformach odbierających wiadomość. Na każdej platformie aplikacja kliencka otrzymuje ładunek danych w funkcji wywołania zwrotnego.

Szyfrowanie wiadomości z danymi

Warstwa transportowa Androida (patrz FCM architektura) korzysta z szyfrowania typu punkt-punkt. W zależności od potrzeb możesz dodać do wiadomości z danymi szyfrowanie end-to-end. FCM nie zapewnia kompleksowego rozwiązania. Dostępne są jednak rozwiązania zewnętrzne, takie jak Capillary czy DTLS.

Wiadomości z powiadomieniami z opcjonalnym ładunkiem danych

Możesz wysyłać wiadomości z powiadomieniami, które zawierają opcjonalny ładunek niestandardowych par klucz-wartość. Możesz to robić programowo lub za pomocą Firebasekonsoli. W  edytorze powiadomień użyj pól Dane niestandardowe w sekcji Opcje zaawansowane.

Zachowanie aplikacji podczas odbierania wiadomości zawierających zarówno powiadomienia, jak i ładunki danych, zależy od tego, czy aplikacja działa w tle, czy na pierwszym planie – czyli czy jest aktywna w momencie otrzymania wiadomości.

• Gdy aplikacja działa w tle, otrzymuje ładunek powiadomienia w obszarze powiadomień i przetwarza ładunek danych tylko wtedy, gdy użytkownik kliknie powiadomienie.
• Gdy aplikacja działa na pierwszym planie, otrzymuje obiekt wiadomości z dostępnymi obydwoma ładunkami.

Oto wiadomość w formacie JSON zawierająca klucze notification i data:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    },
    "data" : {
      "Nick" : "Mario",
      "Room" : "PortugalVSDenmark"
    }
  }
}

Dostosowywanie wiadomości na różnych platformach

Zarówno interfejs Firebase Admin SDK, jak i protokół HTTP FCM w wersji 1 umożliwiają ustawianie w żądaniach wiadomości wszystkich pól dostępnych w obiekcie message. Obejmuje to m.in.:

• wspólny zestaw pól, które mają być interpretowane przez wszystkie instancje aplikacji otrzymujące wiadomość.
• zestawy pól specyficzne dla platformy, np. AndroidConfig i WebpushConfig, które są interpretowane tylko przez instancje aplikacji działające na określonej platformie.

Bloki specyficzne dla platformy zapewniają elastyczność w dostosowywaniu wiadomości do różnych platform, dzięki czemu są one prawidłowo obsługiwane po odebraniu. Backend FCM uwzględni wszystkie określone parametry i dostosuje wiadomość do każdej platformy.

Kiedy używać wspólnych pól

Używaj wspólnych pól, gdy:

• Kierowanie na instancje aplikacji na wszystkich platformach – Apple, Android i internet
• Wysyłanie wiadomości do tematów

Wszystkie instancje aplikacji, niezależnie od platformy, mogą interpretować te wspólne pola:

• message.notification.title
• message.notification.body
• message.data

Kiedy używać pól specyficznych dla platformy

Używaj pól specyficznych dla platformy, jeśli chcesz:

• Wysyłanie pól tylko na określone platformy
• Wysyłanie pól specyficznych dla platformy oprócz pól wspólnych

Jeśli chcesz wysyłać wartości tylko na określone platformy, nie używaj pól wspólnych, tylko pól specyficznych dla platformy. Jeśli na przykład chcesz wysłać powiadomienie tylko na platformy Apple i do internetu, ale nie na Androida, musisz użyć 2 osobnych zestawów pól – jednego dla Apple i jednego dla internetu.

Jeśli wysyłasz wiadomości z określonymi opcjami dostarczania, użyj pól specyficznych dla platformy, aby je ustawić. W razie potrzeby możesz określić różne wartości dla poszczególnych platform. Nawet jeśli chcesz ustawić zasadniczo tę samą wartość na różnych platformach, musisz użyć pól specyficznych dla platformy. Dzieje się tak, ponieważ każda platforma może interpretować tę wartość nieco inaczej. Na przykład na Androidzie czas życia jest ustawiany jako czas wygaśnięcia w sekundach, a na urządzeniach Apple jako data wygaśnięcia.

Przykład: wiadomość z powiadomieniem z opcjami dostawy na poszczególnych platformach

Poniższe żądanie wysyłania w wersji 1 wysyła wspólny tytuł powiadomienia i treść na wszystkie platformy, ale także niektóre zastąpienia specyficzne dla platformy. W szczególności żądanie:

• ustawia długi czas życia na platformach Android i w internecie, a priorytet wiadomości APNs (platformy Apple) na niski.
• ustawia odpowiednie klucze, aby zdefiniować wynik kliknięcia powiadomienia przez użytkownika na urządzeniach z Androidem i Apple – odpowiednio click_action i category.

{
  "message":{
     "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
     "notification":{
       "title":"Match update",
       "body":"Arsenal goal in added time, score is now 3-0"
     },
     "android":{
       "ttl":"86400s",
       "notification"{
         "click_action":"OPEN_ACTIVITY_1"
       }
     },
     "apns": {
       "headers": {
         "apns-priority": "5",
       },
       "payload": {
         "aps": {
           "category": "NEW_MESSAGE_CATEGORY"
         }
       }
     },
     "webpush":{
       "headers":{
         "TTL":"86400"
       }
     }
   }
 }

Szczegółowe informacje o kluczach dostępnych w blokach specyficznych dla platformy w treści wiadomości znajdziesz w dokumentacji referencyjnej HTTP w wersji 1. Więcej informacji o tworzeniu żądań wysyłania zawierających treść wiadomości znajdziesz w artykule Tworzenie żądań wysyłania.

Opcje dostawy

FCM udostępnia określony zestaw opcji dostarczania wiadomości wysyłanych na urządzenia z Androidem i umożliwia korzystanie z podobnych opcji na platformach Apple i w internecie. Na przykład zachowanie „zwijanej” wiadomości jest obsługiwane na Androidzie za pomocą FCMcollapse_key, na urządzeniach Apple za pomocą apns-collapse-id, a w przypadku JavaScriptu i internetu za pomocą Topic. Szczegółowe informacje znajdziesz w opisach w tej sekcji i w powiązanej dokumentacji.

Wiadomości, których nie można zwinąć, i wiadomości, które można zwinąć

Niezwijalna wiadomość oznacza, że każda pojedyncza wiadomość jest dostarczana na urządzenie. Wiadomość, której nie można zwinąć, zawiera przydatne treści, w przeciwieństwie do wiadomości, którą można zwinąć, np. „pinga” bez treści wysyłanego do aplikacji mobilnej w celu skontaktowania się z serwerem i pobrania danych.

FCM nie gwarantuje kolejności dostawy.

Typowe przypadki użycia wiadomości, których nie można zwinąć, to wiadomości na czacie lub wiadomości krytyczne. Na przykład w aplikacji do obsługi komunikatorów internetowych chcesz dostarczać każdą wiadomość, ponieważ każda z nich ma inną treść.

W przypadku Androida można przechowywać maksymalnie 100 wiadomości bez zwijania. Jeśli limit zostanie osiągnięty, wszystkie zapisane wiadomości zostaną odrzucone. Gdy urządzenie ponownie połączy się z internetem, otrzyma specjalną wiadomość z informacją, że limit został osiągnięty. Aplikacja może wtedy odpowiednio zareagować, zwykle przez wysłanie do serwera aplikacji żądania pełnej synchronizacji.

Wiadomość zwijalna to wiadomość, która może zostać zastąpiona nową wiadomością, jeśli nie została jeszcze dostarczona na urządzenie.

Typowym przypadkiem użycia zwijalnych wiadomości są wiadomości służące do informowania aplikacji mobilnej o konieczności zsynchronizowania danych z serwerem. Przykładem może być aplikacja sportowa, która informuje użytkowników o najnowszych wynikach. Tylko najnowsza wiadomość jest istotna.

Aby oznaczyć wiadomość jako zwijalną na urządzeniach z Androidem, w ładunku wiadomości umieść parametr collapse_key. Domyślnie kluczem zwijania jest nazwa pakietu aplikacji zarejestrowanej w konsoli Firebase. FCM Serwer może jednocześnie przechowywać 4 różne zwijalne wiadomości na urządzenie, z których każda ma inny klucz zwijania. Jeśli przekroczysz tę liczbę, usługa FCM zachowa tylko 4 klucze zwijania, bez gwarancji, które z nich zostaną zachowane.

Wiadomości dotyczące tematu bez ładunku są domyślnie zwijalne. Wiadomości z powiadomieniami zawsze można zwinąć i ignorują one parametr collapse_key.

Którego mam użyć?

Z punktu widzenia wydajności lepszym wyborem są zwijalne wiadomości, o ile aplikacja nie musi używać wiadomości niezwijalnych. Jeśli jednak używasz zwijanych wiadomości, pamiętaj, że FCM zezwala na używanie maksymalnie 4 różnych kluczy zwijania przez FCM na token rejestracji w danym momencie. Nie wolno przekraczać tej liczby, ponieważ może to mieć nieprzewidywalne konsekwencje.

	Scenariusz użycia	Jak wysłać
Nie można zwinąć	Każda wiadomość jest ważna dla aplikacji klienta i musi zostać dostarczona.	Z wyjątkiem wiadomości z powiadomieniami wszystkie wiadomości są domyślnie nierozwijane.
Zwijana	Gdy pojawi się nowsza wiadomość, która sprawia, że starsza, powiązana z nią wiadomość staje się nieistotna dla aplikacji klienta, FCM zastępuje starszą wiadomość. Na przykład: wiadomości używane do inicjowania synchronizacji danych z serwera lub nieaktualne wiadomości z powiadomieniami.	Ustaw odpowiedni parametr w żądaniu wiadomości: collapseKey na Androidzie apns-collapse-id w Apple Topic w przeglądarce collapse_key w protokołach starszego typu (wszystkie platformy);

Ustawianie priorytetu wiadomości

Możesz przypisać priorytet dostarczania wiadomościom podrzędnym na 2 sposoby: normalny i wysoki. Chociaż zachowanie różni się nieco w zależności od platformy, dostarczanie wiadomości o normalnym i wysokim priorytecie działa w ten sposób:

• Normalny priorytet Wiadomości o normalnym priorytecie są dostarczane natychmiast, gdy aplikacja działa na pierwszym planie. W przypadku aplikacji działających w tle dostarczanie może być opóźnione. W przypadku mniej pilnych wiadomości, takich jak powiadomienia o nowych e-mailach, synchronizacja interfejsu czy synchronizacja danych aplikacji w tle, wybierz normalny priorytet dostawy.

• Wysoki priorytet. FCM próbuje natychmiast dostarczyć wiadomości o wysokim priorytecie, nawet jeśli urządzenie jest w trybie uśpienia. Wiadomości o wysokim priorytecie są przeznaczone dla treści pilnych i widocznych dla użytkownika.

Podczas wysyłania wiadomości z danymi na urządzenia Apple priorytetmusi być ustawiony na 5 lub normalny. Wiadomości wysłane z wysokim priorytetem są odrzucane przez backend FCM z błędem INVALID_ARGUMENT.

Oto przykład wiadomości o normalnym priorytecie wysłanej za pomocą protokołu FCMHTTP v1, aby powiadomić subskrybenta magazynu, że nowe treści są dostępne do pobrania:

{
  "message":{
    "topic":"subscriber-updates",
    "notification":{
      "body" : "This week's edition is now available.",
      "title" : "NewsMagazine.com",
    },
    "data" : {
      "volume" : "3.21.15",
      "contents" : "http://www.news-magazine.com/world-week/21659772"
    },
    "android":{
      "priority":"normal"
    },
    "apns":{
      "headers":{
        "apns-priority":"5"
      }
    },
    "webpush": {
      "headers": {
        "Urgency": "high"
      }
    }
  }
}

Więcej informacji o ustawianiu priorytetu wiadomości na poszczególnych platformach:

• Dokumentacja APNs
• Ustawianie priorytetu wiadomości i zarządzanie nim (Android)
• Pilność wiadomości push w przeglądarce

Krytyczne przypadki użycia

Interfejsy FCM nie są przeznaczone do alertów alarmowych ani innych działań wysokiego ryzyka, w przypadku których użycie lub awaria interfejsów API może doprowadzić do śmierci, obrażeń ciała lub szkód dla środowiska (np. obsługa obiektów jądrowych, kontrola lotów lub aparatury podtrzymującej życie). Takie użycie jest wyraźnie zabronione na mocy sekcji 4. a. 7 Warunków korzystania z usługi. Ponosisz wyłączną odpowiedzialność za zapewnienie zgodności aplikacji z Warunkami i za wszelkie szkody wynikające z nieprzestrzegania tych Warunków. Google udostępnia interfejsy API w stanie „takim, jakim są” i zastrzega sobie prawo do zaprzestania oferowania interfejsów API albo dowolnej ich funkcji lub części oraz dostępu do nich z dowolnego powodu i w dowolnej chwili, bez żadnej odpowiedzialności lub innych zobowiązań wobec Ciebie lub Twoich użytkowników.

Ustawianie okresu ważności wiadomości

FCM zwykle dostarcza wiadomości natychmiast po ich wysłaniu. Nie zawsze jest to jednak możliwe. Jeśli na przykład platformą jest Android, urządzenie może być wyłączone, offline lub niedostępne z innego powodu. Może też celowo opóźniać wiadomości, aby zapobiec nadmiernemu zużyciu zasobów przez aplikację i negatywnemu wpływowi na czas pracy baterii.FCM

W takiej sytuacji FCM zapisuje wiadomość i dostarcza ją, gdy tylko będzie to możliwe. W większości przypadków nie ma to znaczenia, ale w przypadku niektórych aplikacji opóźniona wiadomość może nigdy nie zostać dostarczona. Jeśli na przykład wiadomość jest powiadomieniem o połączeniu przychodzącym lub rozmowie wideo, ma znaczenie tylko przez krótki czas przed zakończeniem połączenia. Jeśli wiadomość jest zaproszeniem na wydarzenie, jest bezużyteczna, jeśli zostanie odebrana po zakończeniu wydarzenia.

Na Androidzie i w przypadku internetu/JavaScriptu możesz określić maksymalny czas życia wiadomości. Wartość musi być czasem trwania od 0 do 2 419 200 sekund (28 dni) i odpowiada maksymalnemu okresowi, przez który FCM przechowuje i próbuje dostarczyć wiadomość. W przypadku żądań, które nie zawierają tego pola, domyślnie ustawiany jest maksymalny okres 4 tygodni.

Oto kilka możliwych zastosowań tej funkcji:

• Odbieranie przychodzących połączeń wideo
• Wygasające wydarzenia z zaproszeniami
• Wydarzenia w kalendarzu

Kolejną zaletą określania czasu życia wiadomości jest to, że FCM nie stosuje ograniczenia liczby zwijanych wiadomości do wiadomości z wartością czasu życia wynoszącą 0 sekund. FCM zapewnia obsługę wiadomości, które muszą zostać dostarczone „natychmiast lub nigdy”. Pamiętaj, że wartość time_to_live równa 0 oznacza, że wiadomości, których nie można dostarczyć od razu, są odrzucane. Jednak ponieważ takie wiadomości nigdy nie są przechowywane, zapewnia to najmniejsze opóźnienie w przypadku wysyłania wiadomości z powiadomieniami.

Oto przykład żądania, które zawiera TTL:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    },
    "apns":{
      "headers":{
        "apns-expiration":"1604750400"
      }
    },
    "android":{
      "ttl":"4500s"
    },
    "webpush":{
      "headers":{
        "TTL":"4500"
      }
    }
  }
}

Cykl życia wiadomości

Gdy serwer aplikacji opublikuje wiadomość w FCM i otrzyma z powrotem identyfikator wiadomości, nie oznacza to, że wiadomość została już dostarczona na urządzenie. Oznacza to, że została zaakceptowana do dostarczenia. Co się stanie z wiadomością po jej zaakceptowaniu, zależy od wielu czynników.

W najlepszym przypadku, jeśli urządzenie jest podłączone do FCM, ekran jest włączony i nie ma ograniczeń przepustowości, wiadomość jest dostarczana od razu.

Jeśli urządzenie jest połączone, ale w trybie uśpienia, wiadomość o niskim priorytecie jest przechowywana przez FCM do momentu, aż urządzenie wyjdzie z tego trybu. W tym przypadku flaga collapse_key odgrywa ważną rolę: jeśli jest już zapisana i oczekuje na dostarczenie wiadomość z tym samym kluczem zwijania (i tokenem rejestracji), stara wiadomość jest odrzucana, a nowa zajmuje jej miejsce (czyli stara wiadomość jest zwijana przez nową). Jeśli jednak klucz zwijania nie jest ustawiony, zarówno nowa, jak i stara wiadomość są przechowywane do późniejszego dostarczenia.

Jeśli urządzenie nie jest połączone z FCM, wiadomość jest przechowywana do momentu nawiązania połączenia (z zachowaniem reguł klucza zwijania). Po nawiązaniu połączenia usługa FCM dostarcza wszystkie oczekujące wiadomości na urządzenie. Jeśli urządzenie nigdy nie zostanie ponownie połączone (np. po przywróceniu ustawień fabrycznych), komunikat w końcu wygaśnie i zostanie usunięty z pamięci FCM. Domyślny czas oczekiwania to 4 tygodnie, o ile nie jest ustawiona flaga time_to_live.

Aby uzyskać więcej informacji o dostarczeniu wiadomości:

Aby uzyskać więcej informacji o dostarczaniu wiadomości na platformach Android i Apple, zapoznaj się z  FCM panelem raportowania, który rejestruje liczbę wysłanych i otwartych wiadomości na urządzeniach z Androidem i Apple, a także dane dotyczące „wyświetleń” (powiadomień widocznych dla użytkowników) w przypadku aplikacji na Androida.

W przypadku urządzeń z Androidem, na których włączono bezpośrednie przesyłanie wiadomości do kanału, jeśli urządzenie nie połączyło się z FCM przez ponad miesiąc, FCM nadal akceptuje wiadomość, ale natychmiast ją odrzuca. Jeśli urządzenie połączy się w ciągu 4 tygodni od wysłania ostatniej wiadomości z danymi, klient otrzyma wywołanie zwrotne onDeletedMessages(). Aplikacja może wtedy odpowiednio zareagować, zwykle przez wysłanie do serwera aplikacji żądania pełnej synchronizacji.

Gdy FCM próbuje dostarczyć wiadomość na urządzenie, a aplikacja została odinstalowana, FCM odrzuca tę wiadomość i unieważnia token rejestracji. Kolejne próby wysłania wiadomości na to urządzenie będą powodować błąd NotRegistered.

Ograniczanie liczby żądań i limity

Naszym celem jest zawsze dostarczanie wszystkich wiadomości wysyłanych za pomocą FCM. Jednak dostarczanie każdej wiadomości może czasami pogorszyć ogólne wrażenia użytkowników. W innych przypadkach musimy wyznaczyć granice, aby FCM zapewniał skalowalną usługę wszystkim nadawcom. Rodzaje limitów i kwot opisane w tej sekcji pomagają nam zachować równowagę między tymi ważnymi czynnikami.

Uwaga: limity omówione w tej sekcji mogą ulec zmianie.

Ograniczanie liczby wiadomości wysyłanych do klienta

W interfejsie HTTP v1 API wprowadziliśmy limity minutowe dla każdego projektu w przypadku przesyłania wiadomości do urządzeń. Domyślny limit 600 tys. wiadomości na minutę obejmuje ponad 99% FCM deweloperów, a jednocześnie chroni stabilność systemu i minimalizuje wpływ projektów o dużych skokach aktywności.

Nagłe skoki natężenia ruchu mogą powodować błędy przekroczenia limitu. W przypadku przekroczenia limitu system wyświetla kod stanu HTTP 429 (QUOTA_EXCEEDED), dopóki limit nie zostanie uzupełniony w następnej minucie. Odpowiedzi 429 mogą być też zwracane w sytuacjach przeciążenia, dlatego zdecydowanie zalecamy obsługę odpowiedzi 429 zgodnie z opublikowanymi rekomendacjami.

Uwaga:

• Limit dotyczący wysyłania danych do klienta mierzy wiadomości, a nie żądania.
• Błędy klienta (kody stanu HTTP 400–499) są zliczane (z wyjątkiem kodów 429).
• Limity są określane na minutę, ale te minuty nie są zsynchronizowane z zegarem.

Limit monitorowania

Limity, wykorzystanie i błędy możesz wyświetlić w konsoli Google Cloud:

1. Otwórz Google Cloudkonsolę
2. Kliknij Interfejsy API i usługi.
3. Na liście tabel wybierz Firebase Cloud Messaging API.
4. Kliknij LIMITY PRZYDZIAŁU I LIMITY SYSTEMU.

UWAGA: te wykresy nie są dokładnie zsynchronizowane z czasem wykorzystania limitu minut, co oznacza, że mogą pojawiać się odpowiedzi 429, gdy natężenie ruchu wydaje się niższe niż limit.

Wysyłanie prośby o zwiększenie limitu

Zanim poprosisz o zwiększenie limitu, upewnij się, że:

• Wykorzystanie regularnie wynosi co najmniej 80% limitu przez co najmniej 5 minut z rzędu dziennie.
• Współczynnik błędów klienta jest mniejszy niż 5%, zwłaszcza w okresach największego natężenia ruchu.
• Stosujesz sprawdzone metody wysyłania wiadomości na dużą skalę.

Jeśli spełniasz te kryteria, możesz przesłać prośbę o zwiększenie limitu maksymalnie o 25%, a FCM dołoży wszelkich starań, aby ją spełnić (nie możemy zagwarantować zwiększenia limitu).

Jeśli potrzebujesz większego limitu wiadomości wysyłanych do użytkowników ze względu na zbliżające się wprowadzenie usługi lub tymczasowe wydarzenie, poproś o zwiększenie limitu z co najmniej 15-dniowym wyprzedzeniem, aby mieć wystarczająco dużo czasu na rozpatrzenie prośby. W przypadku dużych żądań (ponad 18 mln wiadomości na minutę) wymagane jest powiadomienie z co najmniej 30-dniowym wyprzedzeniem. Żądania dotyczące premier i wydarzeń specjalnych nadal podlegają wymaganiom dotyczącym współczynnika błędów klienta i sprawdzonych metod.

Zobacz też najczęstsze pytania dotyczące FCM limitów.

Limit wiadomości związanych z tematem

Szybkość dodawania i usuwania subskrypcji tematu jest ograniczona do 3000 zapytań na sekundę na projekt.

Informacje o szybkości wysyłania wiadomości znajdziesz w artykule Ograniczanie rozsyłania.

Ograniczanie zwielokrotnienia wyjściowego

Rozsyłanie wiadomości to proces wysyłania wiadomości na wiele urządzeń, np. gdy kierujesz reklamy na tematy i grupy lub gdy używasz kompozytora powiadomień do kierowania reklam na grupy odbiorców lub segmenty użytkowników.

Rozsyłanie wiadomości nie jest natychmiastowe, więc czasami kilka rozsyłań jest w toku jednocześnie. Ograniczamy liczbę równoczesnych rozsyłań wiadomości na projekt do 1000. Następnie możemy odrzucić dodatkowe żądania rozsyłania lub odłożyć rozsyłanie żądań do czasu zakończenia niektórych z już trwających rozsyłań.

Na rzeczywistą osiągalną szybkość rozsyłania ma wpływ liczba projektów, które w tym samym czasie wysyłają żądania rozsyłania. Szybkość rozsyłania 10 000 zapytań na sekundę w przypadku pojedynczego projektu nie jest niczym niezwykłym, ale nie jest gwarantowana i zależy od całkowitego obciążenia systemu. Pamiętaj, że dostępna pojemność rozgłaszania jest dzielona między projekty, a nie między żądania rozgłaszania. Jeśli w projekcie są 2 rozsyłania w toku, każde z nich będzie miało tylko połowę dostępnej szybkości rozsyłania. Zalecany sposób na zmaksymalizowanie szybkości rozsyłania to posiadanie tylko jednego aktywnego rozsyłania w danym momencie.

Ograniczanie liczby zwijanych wiadomości

Jak opisano powyżej, zwijalne wiadomości to powiadomienia bez treści, które mają się zwijać, nakładając się na siebie. Jeśli deweloper zbyt często wysyła tę samą wiadomość do aplikacji, opóźniamy (ograniczamy) wysyłanie wiadomości, aby zmniejszyć wpływ na baterię użytkownika.

Jeśli na przykład wyślesz dużą liczbę nowych żądań synchronizacji e-maili na jedno urządzenie, możemy opóźnić kolejne żądanie synchronizacji o kilka minut, aby urządzenie mogło synchronizować dane ze średnią niższą częstotliwością. Ograniczenie to jest stosowane wyłącznie w celu ograniczenia wpływu na baterię, jaki odczuwa użytkownik.

Jeśli Twój przypadek użycia wymaga wysyłania dużej liczby wiadomości w krótkim czasie, wiadomości niezwijalne mogą być odpowiednim wyborem. W przypadku takich wiadomości zadbaj o to, aby zawierały one treści, co pozwoli zmniejszyć zużycie baterii.

Ograniczamy zwijane wiadomości do 20 wiadomości na aplikację na urządzenie, a następnie co 3 minuty dodajemy 1 wiadomość.

Maksymalna częstotliwość wysyłania wiadomości na jedno urządzenie

W przypadku Androida możesz wysłać maksymalnie 240 wiadomości na minutę i 5000 wiadomości na godzinę na jedno urządzenie. Ten wysoki próg ma na celu umożliwienie krótkotrwałych wzrostów ruchu, np. gdy użytkownicy szybko ze sobą rozmawiają na czacie. Ten limit zapobiega przypadkowemu wyczerpaniu baterii urządzenia przez błędy w logice wysyłania.

W przypadku iOS zwracamy błąd, gdy liczba żądań przekracza limity APNs.

Uwaga: nie wysyłaj regularnie wiadomości z szybkością zbliżoną do tej maksymalnej. Może to marnować zasoby użytkowników, a Twoja aplikacja może zostać oznaczona jako stosująca nadużycia.

FCM porty i zapora sieciowa

Jeśli Twoja organizacja ma zaporę sieciową, która ogranicza ruch do lub z internetu, musisz ją skonfigurować tak, aby zezwalała urządzeniom mobilnym na łączenie się z FCM. Dzięki temu urządzenia w Twojej sieci będą mogły odbierać wiadomości. FCM zwykle używa portu 5228, ale czasami korzysta też z portów 443, 5229 i 5230.

W przypadku urządzeń łączących się z Twoją siecią FCM nie podaje konkretnych adresów IP, ponieważ nasz zakres adresów IP zmienia się zbyt często, a reguły zapory sieciowej mogą się zdezaktualizować, co wpłynie na komfort użytkowników. Najlepiej zezwolić na porty 5228–5230 i 443 bez ograniczeń dotyczących adresów IP. Jeśli jednak musisz zastosować ograniczenie IP, dodaj do listy dozwolonych wszystkie adresy IP wymienione w pliku goog.json. Ta długa lista jest regularnie aktualizowana, dlatego zalecamy comiesięczne aktualizowanie reguł. Problemy spowodowane ograniczeniami adresów IP zapory sieciowej często występują sporadycznie i trudno je zdiagnozować.

Oferujemy zestaw nazw domen, które można dodać do listy dozwolonych zamiast adresów IP. Nazwy hostów znajdziesz poniżej. Jeśli zaczniemy używać dodatkowych nazw hostów, zaktualizujemy tę listę. Używanie nazw domen w regule zapory sieciowej może, ale nie musi działać na Twoim urządzeniu.

Porty TCP do otwarcia:

• 5228
• 5229
• 5230
• 443

Nazwy hostów do otwarcia:

• mtalk.google.com
• mtalk4.google.com
• mtalk-staging.google.com
• mtalk-dev.google.com
• alt1-mtalk.google.com
• alt2-mtalk.google.com
• alt3-mtalk.google.com
• alt4-mtalk.google.com
• alt5-mtalk.google.com
• alt6-mtalk.google.com
• alt7-mtalk.google.com
• alt8-mtalk.google.com
• android.apis.google.com
• device-provisioning.googleapis.com
• firebaseinstallations.googleapis.com

Zapory sieciowe z NAT lub SPI:

Jeśli w Twojej sieci jest wdrożone tłumaczenie adresów sieciowych (NAT) lub kontrola pakietów ze stanem (SPI), ustaw dla naszych połączeń na portach 5228–5230 limit czasu wynoszący co najmniej 30 minut. Dzięki temu możemy zapewnić niezawodne połączenie, jednocześnie zmniejszając zużycie baterii urządzeń mobilnych użytkowników.

Uwaga: jeśli otrzymujesz powiadomienia za pomocą APNs, upewnij się, że masz też otwarte porty określone przez Apple.

Interakcje z VPN i możliwość obejścia

Firebase Cloud Messaging podejmuje różne działania, aby połączenie wiadomości push z telefonu na serwer było niezawodne i dostępne tak często, jak to możliwe. Korzystanie z sieci VPN utrudnia to zadanie.

Sieci VPN maskują podstawowe informacje, których FCM potrzebuje do dostosowania połączenia w celu zmaksymalizowania niezawodności i wydłużenia czasu pracy baterii. W niektórych przypadkach sieci VPN aktywnie przerywają długotrwałe połączenia, co powoduje problemy z użytkowaniem, ponieważ wiadomości są pomijane lub opóźnione, a bateria szybko się wyczerpuje. Gdy sieć VPN jest skonfigurowana tak, aby nam na to zezwalać, omijamy ją za pomocą szyfrowanego połączenia (przez podstawową sieć Wi-Fi lub LTE), aby zapewnić niezawodne działanie i oszczędność baterii. FCMKorzystanie z sieci VPN, które można pominąć, dotyczy tylko kanału powiadomień push.FCM Inny ruch FCM, np. ruch rejestracyjny, korzysta z sieci VPN, jeśli jest ona aktywna. Gdy FCMpołączenie omija sieć VPN, traci dodatkowe korzyści, jakie może ona zapewniać, takie jak maskowanie adresu IP.

Różne sieci VPN mają różne metody kontrolowania, czy można je obejść. Instrukcje znajdziesz w dokumentacji konkretnej sieci VPN.

Jeśli sieć VPN nie jest skonfigurowana tak, aby można było ją pominąć, usługa Firebase Cloud Messaging będzie używać sieci VPN do łączenia się z serwerem. Może to powodować opóźnienia w dostarczaniu wiadomości i większe zużycie baterii, ponieważ Cloud Messaging będzie utrzymywać połączenie przez sieć VPN.

Dane logowania

W zależności od tego, które funkcje FCM wdrożysz, możesz potrzebować tych danych logowania z projektu Firebase:

Identyfikator projektu	Unikalny identyfikator Twojego projektu Firebase używany w żądaniach wysyłanych do punktu końcowego HTTP FCM w wersji 1. Ta wartość jest dostępna w panelu Firebase konsoli Ustawienia.
Token rejestracji	Unikalny ciąg znaków tokena, który identyfikuje każdą instancję aplikacji klienta. Token rejestracji jest wymagany w przypadku wysyłania wiadomości do jednego urządzenia i do grupy urządzeń. Pamiętaj, że tokeny rejestracji muszą być przechowywane w tajemnicy.
Identyfikator nadawcy	Unikalna wartość liczbowa utworzona podczas tworzenia projektu Firebase, dostępna na karcie Cloud Messaging w panelu Ustawienia w konsoli Firebase. Identyfikator nadawcy służy do identyfikowania każdego nadawcy, który może wysyłać wiadomości do aplikacji klienta.
Token dostępu	Krótkotrwały token OAuth 2.0, który autoryzuje żądania do interfejsu HTTP API w wersji 1. Ten token jest powiązany z kontem usługi należącym do Twojego projektu Firebase. Aby utworzyć i obracać tokeny dostępu, wykonaj czynności opisane w artykule Autoryzowanie żądań wysyłania.
Klucz serwera (w przypadku **wycofanych** starszych protokołów)	Klucz serwera, który autoryzuje serwer aplikacji do uzyskiwania dostępu do usług Google, w tym do wysyłania wiadomości za pomocą wycofanych Firebase Cloud Messaging protokołów starszego typu. Ważne: nie umieszczaj klucza serwera w kodzie klienta. Pamiętaj też, aby do autoryzacji serwera aplikacji używać tylko kluczy serwera. Klucze Androida, platformy Apple i przeglądarki są odrzucane przez FCM.