Google 致力于为黑人社区推动种族平等。查看具体举措
Ta strona została przetłumaczona przez Cloud Translation API.
Switch to English

Twoje środowisko serwerowe i FCM

Strona serwera Firebase Cloud Messaging składa się z dwóch komponentów:

  • Backend FCM dostarczony przez Google.
  • Twój serwer aplikacji lub inne zaufane środowisko serwera, w którym działa logika serwera, takie jak Cloud Functions for Firebase lub inne środowiska chmurowe zarządzane przez Google.

Twój serwer aplikacji lub środowisko zaufanego serwera wysyła żądania wiadomości do zaplecza FCM, które następnie kieruje wiadomości do aplikacji klienckich działających na urządzeniach użytkowników.

Wymagania dotyczące zaufanego środowiska serwera

Środowisko serwera aplikacji musi spełniać następujące kryteria:

  • Możliwość wysyłania prawidłowo sformatowanych żądań wiadomości do zaplecza FCM.
  • Potrafi obsługiwać żądania i wysyłać je ponownie za pomocą wykładniczego wycofywania.
  • Może bezpiecznie przechowywać poświadczenia autoryzacji serwera i tokeny rejestracji klienta.
  • W przypadku protokołu XMPP (jeśli jest używany) serwer musi mieć możliwość generowania identyfikatorów wiadomości, aby jednoznacznie identyfikować każdą wysyłaną wiadomość (zaplecze HTTP FCM generuje identyfikatory wiadomości i zwraca je w odpowiedzi). Identyfikatory wiadomości XMPP powinny być unikalne dla każdego identyfikatora nadawcy.

Wybór opcji serwera

Musisz zdecydować o sposobie interakcji z serwerami FCM: albo za pomocą pakietu Firebase Admin SDK, albo protokołów nieprzetworzonych. Ze względu na obsługę wielu popularnych języków programowania oraz wygodne metody obsługi uwierzytelniania i autoryzacji zalecaną metodą jest pakiet Firebase Admin SDK.

Dostępne są następujące opcje interakcji z serwerami FCM:

Firebase Admin SDK dla FCM

Interfejs API Admin FCM obsługuje uwierzytelnianie z zapleczem i ułatwia wysyłanie wiadomości i zarządzanie subskrypcjami tematów. Dzięki pakietowi Firebase Admin SDK możesz:

  • Wysyłaj wiadomości na poszczególne urządzenia
  • Wysyłaj wiadomości do tematów i wyrażeń warunkowych pasujących do co najmniej jednego tematu.
  • Subskrybuj i anuluj subskrypcję urządzeń do i z tematów
  • Konstruuj ładunki wiadomości dostosowane do różnych platform docelowych

Pakiet Admin Node.js SDK zapewnia metody wysyłania wiadomości do grup urządzeń.

Aby skonfigurować pakiet Firebase Admin SDK, zobacz Dodawanie pakietu Firebase Admin SDK do serwera . Jeśli masz już projekt Firebase, zacznij od dodania pakietu SDK . Następnie po zainstalowaniu pakietu Firebase Admin SDK możesz zacząć pisać logikę do tworzenia żądań wysyłania .

Protokoły serwera FCM

Obecnie FCM zapewnia następujące surowe protokoły serwera:

Twój serwer aplikacji może używać tych protokołów oddzielnie lub w tandemie. Ponieważ jest to najbardziej aktualny i najbardziej elastyczny sposób wysyłania wiadomości na wiele platform, zalecany jest interfejs API FCM HTTP v1 wszędzie tam, gdzie to możliwe. Jeśli Twoje wymagania obejmują wysyłanie wiadomości z urządzeń na serwer, musisz zaimplementować protokół XMPP.

Wiadomości XMPP różnią się od wiadomości HTTP pod następującymi względami:

  • Wiadomości wysyłające / odbierane
    • HTTP: tylko podrzędne, z chmury do urządzenia.
    • XMPP: Upstream i downstream (urządzenie do chmury, chmura do urządzenia).
  • Wiadomości (synchroniczne lub asynchroniczne)
    • HTTP: synchroniczne. Serwery aplikacji wysyłają komunikaty jako żądania HTTP POST i czekają na odpowiedź. Mechanizm ten jest synchroniczny i blokuje wysyłanie przez nadawcę kolejnej wiadomości do czasu otrzymania odpowiedzi.
    • XMPP: asynchroniczny. Serwery aplikacji wysyłają / odbierają komunikaty do / ze wszystkich swoich urządzeń przy pełnej szybkości linii przez trwałe połączenia XMPP. Serwer połączeń XMPP wysyła asynchronicznie potwierdzenia lub powiadomienia o błędach (w postaci specjalnych komunikatów XMPP ACK i NACK zakodowanych w formacie JSON).
  • JSON
    • HTTP: wiadomości JSON wysyłane jako HTTP POST.
    • XMPP: wiadomości JSON hermetyzowane w wiadomościach XMPP.
  • Zwykły tekst
    • HTTP: wiadomości tekstowe wysyłane jako HTTP POST.
    • XMPP: nieobsługiwane.
  • Wysyłanie multiemisji w dół do wielu tokenów rejestracji.
    • HTTP: obsługiwane w formacie wiadomości JSON.
    • XMPP: nieobsługiwane.

Implementacja protokołu serwera HTTP

Aby wysłać wiadomość, serwer aplikacji wysyła żądanie POST z nagłówkiem HTTP i treścią HTTP składającą się z par klucz-wartość JSON. Aby uzyskać szczegółowe informacje na temat opcji nagłówka i treści, zobacz Tworzenie żądań wysyłania serwera aplikacji

Implementacja protokołu serwera XMPP

Ładunek JSON dla komunikatów FCM jest podobny do protokołu HTTP, z następującymi wyjątkami:

  • Nie ma obsługi wielu odbiorców.
  • FCM dodaje pole message_id , które jest wymagane. Ten identyfikator jednoznacznie identyfikuje wiadomość w połączeniu XMPP. ACK lub NACK z FCM używa parametru message_id do identyfikowania wiadomości wysłanej z serwerów aplikacji do FCM. Dlatego ważne jest, aby ten komunikat message_id nie tylko unikalny (według identyfikatora nadawcy ), ale był zawsze obecny.
  • XMPP używa klucza serwera do autoryzacji trwałego połączenia z FCM. Aby uzyskać więcej informacji, zobacz Autoryzuj wysyłanie żądań .

Oprócz zwykłych komunikatów FCM wysyłane są komunikaty sterujące, wskazywane przez pole message_type w obiekcie JSON. Wartością może być „ACK”, „NACK” lub „CONTROL” (zobacz formaty poniżej). Każda wiadomość FCM o nieznanym message_type może zostać zignorowana przez Twój serwer.

Dla każdej wiadomości z urządzenia, którą serwer aplikacji otrzymuje z FCM, musi wysłać komunikat ACK. Nigdy nie musi wysyłać wiadomości NACK. Jeśli nie wyślesz potwierdzenia dla wiadomości, FCM wyśle ​​ją ponownie przy następnym ustanowieniu nowego połączenia XMPP, chyba że wiadomość wygaśnie jako pierwsza.

FCM wysyła również ACK lub NACK dla każdej wiadomości od serwera do urządzenia. Jeśli również nie otrzymasz, oznacza to, że połączenie TCP zostało zamknięte w trakcie operacji i serwer musi ponownie wysłać wiadomości. Aby uzyskać szczegółowe informacje, patrz Kontrola przepływu .

Listę wszystkich parametrów wiadomości można znaleźć w Odniesieniu do protokołu .

Format żądania

Wiadomość z ładunkiem - wiadomość powiadamiająca

Oto sekcja XMPP dotycząca wiadomości z powiadomieniem:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to":"REGISTRATION_ID",  // "to" replaces "registration_ids"
     "notification": {
        "title": "Portugal vs. Denmark”,
        "body”: "5 to 1”
      },
      "time_to_live":"600"
}

  }
  </gcm>
</message>

Wiadomość z ładunkiem - wiadomość z danymi

Oto sekcja XMPP zawierająca wiadomość JSON z serwera aplikacji do FCM:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to":"REGISTRATION_ID",  // "to" replaces "registration_ids"
      "message_id":"m-1366082849205" // new required field
      "data":
      {
          "hello":"world",
      }
      "time_to_live":"600",
  }
  </gcm>
</message>

Format odpowiedzi

Odpowiedź FCM może mieć trzy możliwe formy. Pierwsza to zwykła wiadomość „potwierdzenie”. Ale gdy odpowiedź zawiera błąd, istnieją 2 różne formy, które może przyjąć wiadomość, opisane poniżej.

Wiadomość ACK

Oto sekcja XMPP zawierająca komunikat ACK / NACK z FCM do serwera aplikacji:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "from":"REGID",
      "message_id":"m-1366082849205"
      "message_type":"ack"
  }
  </gcm>
</message>

Wiadomość NACK

Błąd NACK to zwykły komunikat XMPP, w którym komunikat o stanie message_type to „nack”. Wiadomość NACK zawiera:

  • Kod błędu NACK.
  • Opis błędu NACK.

Poniżej znajduje się kilka przykładów.

Zła rejestracja:

<message>
  <gcm xmlns="google:mobile:data">
  {
    "message_type":"nack",
    "message_id":"msgId1",
    "from":"SomeInvalidRegistrationId",
    "error":"BAD_REGISTRATION",
    "error_description":"Invalid token on 'to' field: SomeInvalidRegistrationId"
  }
  </gcm>
</message>

Nieprawidłowy JSON:

<message>
 <gcm xmlns="google:mobile:data">
 {
   "message_type":"nack",
   "message_id":"msgId1",
   "from":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
   "error":"INVALID_JSON",
   "error_description":"InvalidJson: JSON_TYPE_ERROR : Field \"time_to_live\" must be a JSON java.lang.Number: abc"
 }
 </gcm>
</message>

Przekroczono szybkość komunikatów urządzenia:

<message id="...">
  <gcm xmlns="google:mobile:data">
  {
    "message_type":"nack",
    "message_id":"msgId1",
    "from":"REGID",
    "error":"DEVICE_MESSAGE_RATE_EXCEEDED",
    "error_description":"Downstream message rate exceeded for this registration id"
  }
  </gcm>
</message>

Pełną listę kodów błędów NACK można znaleźć w dokumentacji serwera . O ile nie wskazano inaczej, nie należy ponawiać próby wiadomości NACKed. Nieoczekiwane kody błędów NACK powinny być traktowane tak samo jak INTERNAL_SERVER_ERROR .

Błąd sekcji

W niektórych przypadkach możesz również otrzymać błąd sekcji. Błąd w sekcji zawiera:

  • Kod błędu Stanza.
  • Opis błędu w sekcji (dowolny tekst).

Na przykład:

<message id="3" type="error" to="123456789@fcm.googleapis.com/ABC">
  <gcm xmlns="google:mobile:data">
     {"random": "text"}
  </gcm>
  <error code="400" type="modify">
    <bad-request xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
    <text xmlns="urn:ietf:params:xml:ns:xmpp-stanzas">
      InvalidJson: JSON_PARSING_ERROR : Missing Required Field: message_id\n
    </text>
  </error>
</message>

Komunikaty kontrolne

Okresowo FCM musi zamykać połączenie, aby przeprowadzić równoważenie obciążenia. Przed zamknięciem połączenia FCM wysyła komunikat CONNECTION_DRAINING aby wskazać, że połączenie jest opróżniane i wkrótce zostanie zamknięte. „Opróżnianie” odnosi się do odcinania przepływu wiadomości przychodzących do połączenia, ale pozwalania na kontynuowanie tego, co jest już w potoku. Po otrzymaniu komunikatu CONNECTION_DRAINING należy natychmiast rozpocząć wysyłanie wiadomości do innego połączenia FCM, otwierając w razie potrzeby nowe połączenie. Powinieneś jednak pozostawić pierwotne połączenie otwarte i kontynuować odbieranie wiadomości, które mogą nadejść przez to połączenie (i potwierdzanie ich) - FCM obsługuje inicjowanie połączenia, które jest zamykane, gdy jest gotowe.

Komunikat CONNECTION_DRAINING wygląda tak:

<message>
  <data:gcm xmlns:data="google:mobile:data">
  {
    "message_type":"control"
    "control_type":"CONNECTION_DRAINING"
  }
  </data:gcm>
</message>

CONNECTION_DRAINING jest obecnie jedynym obsługiwanym control_type .

Kontrola przepływu

Każda wiadomość wysłana do FCM otrzymuje odpowiedź ACK lub NACK. Wiadomości, które nie otrzymały żadnej z tych odpowiedzi, są uważane za oczekujące. Jeśli liczba oczekujących wiadomości osiągnie 100, serwer aplikacji powinien przestać wysyłać nowe wiadomości i czekać, aż FCM potwierdzi niektóre z istniejących oczekujących wiadomości, jak pokazano na rysunku 1:

Rysunek 1. Przepływ wiadomości / potwierdzenia.

Z drugiej strony, aby uniknąć przeciążenia serwera aplikacji, FCM przestaje wysyłać, jeśli jest zbyt wiele niezatwierdzonych komunikatów. W związku z tym serwer aplikacji powinien jak najszybciej „ACK” odbierać komunikaty wysyłane z aplikacji klienckiej za pośrednictwem FCM, aby utrzymać stały przepływ komunikatów przychodzących. Wspomniany powyżej limit oczekujących wiadomości nie dotyczy tych potwierdzeń ACK. Nawet jeśli liczba oczekujących komunikatów osiągnie 100, serwer aplikacji powinien kontynuować wysyłanie potwierdzeń ACK dla komunikatów odebranych z FCM, aby uniknąć blokowania dostarczania nowych komunikatów nadrzędnych.

Potwierdzenia ACK są ważne tylko w kontekście jednego połączenia. Jeśli połączenie zostanie zamknięte przed potwierdzeniem wiadomości, serwer aplikacji powinien poczekać, aż FCM ponownie wyśle ​​wiadomość nadrzędną, zanim ponownie ją potwierdzi. Podobnie, wszystkie oczekujące wiadomości, dla których ACK / NACK nie zostało odebrane z FCM przed zamknięciem połączenia, powinny zostać wysłane ponownie.