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ć.

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 dotknie powiadomienia.
  • 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"
    }
  }
}

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.

Ustawianie priorytetu wiadomości

Możesz przypisać priorytet dostarczania wiadomościom wysyłanym do dalszych odbiorców na 2 sposoby: normalny i wysoki. Chociaż działanie różni się nieco w zależności od platformy, dostarczanie wiadomości o normalnym i wysokim priorytecie wygląda tak:

  • 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.

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:

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 systemy podtrzymywania życia). 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 Dewelopera lub jego 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ż FCM celowo opóźniać wiadomości, aby zapobiec nadmiernemu zużyciu zasobów przez aplikację i negatywnemu wpływowi na czas pracy baterii.

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 jego zakończeniu.

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 wysyłaniu powiadomień.

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 identyfikator wiadomości, nie oznacza to, że wiadomość została już dostarczona na urządzenie. Oznacza to, że została zaakceptowana do wyświetlania. 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 FCMpamięci. 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ą skutkować błędem NotRegistered.

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 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 v1. 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.