Google is committed to advancing racial equity for Black communities. See how.
Questa pagina è stata tradotta dall'API Cloud Translation.
Switch to English

Il tuo ambiente server e FCM

Il lato server di Firebase Cloud Messaging è costituito da due componenti:

  • Il backend FCM fornito da Google.
  • Il tuo server di app o altro ambiente di server fidato in cui viene eseguita la logica del tuo server, ad esempio Funzioni cloud per Firebase o altri ambienti cloud gestiti da Google.

Il server delle app o l'ambiente server attendibile invia richieste di messaggi al back-end FCM, che inoltra i messaggi alle app client in esecuzione sui dispositivi degli utenti.

Requisiti per l'ambiente server attendibile

L'ambiente del server delle app deve soddisfare i seguenti criteri:

  • In grado di inviare richieste di messaggi correttamente formattate al back-end FCM.
  • In grado di gestire le richieste e inviarle di nuovo utilizzando il back-off esponenziale.
  • In grado di archiviare in modo sicuro le credenziali di autorizzazione del server e i token di registrazione del client.
  • Per il protocollo XMPP (se utilizzato), il server deve essere in grado di generare ID messaggio per identificare in modo univoco ogni messaggio inviato (il backend HTTP FCM genera gli ID messaggio e li restituisce nella risposta). Gli ID messaggio XMPP devono essere univoci per ID mittente.

Scelta di un'opzione server

Dovrai decidere come interagire con i server FCM: utilizzando Firebase Admin SDK o i protocolli non elaborati. A causa del suo supporto attraverso i più diffusi linguaggi di programmazione e dei suoi metodi convenienti per la gestione dell'autenticazione e dell'autorizzazione, Firebase Admin SDK è il metodo consigliato.

Le opzioni per l'interazione con i server FCM includono quanto segue:

Firebase Admin SDK per FCM

L'API Admin FCM gestisce l'autenticazione con il back-end e facilita l'invio di messaggi e la gestione delle iscrizioni agli argomenti. Con Firebase Admin SDK, puoi:

  • Invia messaggi a singoli dispositivi
  • Invia messaggi a argomenti e istruzioni condizionali che corrispondono a uno o più argomenti.
  • Sottoscrivi e annulla l'iscrizione di dispositivi ae da argomenti
  • Costruire payload di messaggi su misura per diverse piattaforme di destinazione

L'SDK Node.js di amministrazione fornisce metodi per inviare messaggi a gruppi di dispositivi.

Per configurare l'SDK dell'amministratore di Firebase, consultare Aggiungere l'SDK dell'amministratore di Firebase al server . Se hai già un progetto Firebase, inizia con Aggiungi SDK . Quindi, una volta installato Firebase Admin SDK, è possibile iniziare a scrivere la logica per creare richieste di invio .

Protocolli server FCM

Attualmente FCM fornisce questi protocolli server non elaborati:

Il server delle app può utilizzare questi protocolli separatamente o in tandem. Poiché è la più aggiornata e la più flessibile per l'invio di messaggi a più piattaforme, l'API FCM HTTP v1 è consigliata laddove possibile. Se i tuoi requisiti includono la messaggistica a monte dai dispositivi al server, dovrai implementare il protocollo XMPP.

La messaggistica XMPP differisce dalla messaggistica HTTP per i seguenti modi:

  • Messaggi a monte / a valle
    • HTTP: solo downstream, da cloud a dispositivo.
    • XMPP: upstream e downstream (da dispositivo a cloud, da cloud a dispositivo).
  • Messaggi (sincroni o asincroni)
    • HTTP: sincrono. I server delle app inviano messaggi come richieste POST HTTP e attendono una risposta. Questo meccanismo è sincrono e impedisce al mittente di inviare un altro messaggio fino alla ricezione della risposta.
    • XMPP: asincrono. I server delle app inviano / ricevono messaggi da / verso tutti i loro dispositivi alla massima velocità su connessioni XMPP persistenti. Il server di connessione XMPP invia notifiche di riconoscimento o di errore (sotto forma di messaggi XMPP codificati con ACK e NACK speciali) in modo asincrono.
  • JSON
    • HTTP: messaggi JSON inviati come HTTP POST.
    • XMPP: messaggi JSON incapsulati nei messaggi XMPP.
  • Testo semplice
    • HTTP: messaggi di testo semplice inviati come HTTP POST.
    • XMPP: non supportato.
  • Downstream multicast invia a più token di registrazione.
    • HTTP: supportato nel formato del messaggio JSON.
    • XMPP: non supportato.

Implementazione del protocollo del server HTTP

Per inviare un messaggio, il server delle app emette una richiesta POST con un'intestazione HTTP e un corpo HTTP composto da coppie di valori chiave JSON. Per i dettagli sulle opzioni di intestazione e corpo, vedere Creare richieste di invio del server app

Implementazione del protocollo del server XMPP

Il payload JSON per i messaggi FCM è simile al protocollo HTTP, con queste eccezioni:

  • Non esiste supporto per più destinatari.
  • FCM aggiunge il campo message_id , obbligatorio. Questo ID identifica in modo univoco il messaggio in una connessione XMPP. ACK o NACK di FCM utilizza message_id per identificare un messaggio inviato dai server delle app a FCM. Pertanto, è importante che questo message_id non sia solo univoco (per ID mittente ), ma sempre presente.
  • XMPP utilizza la chiave del server per autorizzare una connessione permanente a FCM. Vedere Autorizza richieste di invio per ulteriori informazioni.

Oltre ai normali messaggi FCM, vengono inviati messaggi di controllo, indicati dal campo message_type nell'oggetto JSON. Il valore può essere "ack" o "nack" o "control" (vedere i formati di seguito). Qualsiasi messaggio FCM con uno sconosciuto message_type può essere ignorato dal server.

Per ogni messaggio del dispositivo che il tuo server app riceve da FCM, deve inviare un messaggio ACK. Non ha mai bisogno di inviare un messaggio NACK. Se non si invia un ACK per un messaggio, FCM lo rinvia la prossima volta che viene stabilita una nuova connessione XMPP, a meno che il messaggio non scada prima.

FCM invia inoltre un ACK o NACK per ciascun messaggio da server a dispositivo. Se non ricevi neanche, significa che la connessione TCP è stata chiusa nel mezzo dell'operazione e il tuo server deve reinviare i messaggi. Vedi Flow Control per i dettagli.

Vedere il Riferimento protocollo per un elenco di tutti i parametri del messaggio.

Formato richiesta

Messaggio con payload - messaggio di notifica

Ecco una stanza XMPP per un messaggio di notifica:

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

Messaggio con payload - messaggio dati

Ecco una stanza XMPP contenente il messaggio JSON da un server di app a 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>

Formato di risposta

Una risposta FCM può avere tre forme possibili. Il primo è un normale messaggio "ack". Ma quando la risposta contiene un errore, ci sono 2 diverse forme che il messaggio può assumere, descritte di seguito.

Messaggio ACK

Ecco una stanza XMPP che contiene il messaggio ACK / NACK da FCM al server app:

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

Messaggio NACK

Un errore NACK è un normale messaggio XMPP in cui il messaggio di stato message_type è "nack". Un messaggio NACK contiene:

  • Un codice di errore NACK.
  • Una descrizione dell'errore NACK.

Di seguito sono riportati alcuni esempi.

Registrazione errata:

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

JSON non valido:

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

Frequenza messaggi dispositivo superata:

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

Consultare il riferimento al server per un elenco completo dei codici di errore NACK. Se non diversamente indicato, un messaggio NACKed non deve essere ripetuto. I codici di errore NACK imprevisti devono essere trattati come INTERNAL_SERVER_ERROR .

Errore stanza

È inoltre possibile ottenere un errore di stanza in alcuni casi. Un errore di stanza contiene:

  • Codice errore stanza.
  • Descrizione dell'errore di stanza (testo libero).

Per esempio:

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

Controlla i messaggi

Periodicamente, FCM deve chiudere una connessione per eseguire il bilanciamento del carico. Prima di chiudere la connessione, FCM invia un messaggio CONNECTION_DRAINING per indicare che la connessione è stata svuotata e verrà chiusa presto. "Svuotamento" si riferisce alla chiusura del flusso di messaggi che entrano in una connessione, ma per consentire a tutto ciò che è già in cantiere di continuare. Quando ricevi un messaggio CONNECTION_DRAINING , dovresti immediatamente iniziare a inviare messaggi a un'altra connessione FCM, aprendo una nuova connessione se necessario. Tuttavia, è necessario mantenere aperta la connessione originale e continuare a ricevere i messaggi che potrebbero arrivare sulla connessione (e ACKing): FCM gestisce l'avvio di una connessione quando è pronta.

Il messaggio CONNECTION_DRAINING è simile al seguente:

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

CONNECTION_DRAINING è attualmente l'unico control_type supportato.

Controllo del flusso

Ogni messaggio inviato a FCM riceve una risposta ACK o NACK. I messaggi che non hanno ricevuto una di queste risposte sono considerati in sospeso. Se il conteggio dei messaggi in sospeso raggiunge 100, l'app server deve interrompere l'invio di nuovi messaggi e attendere che FCM riconosca alcuni dei messaggi in sospeso esistenti, come illustrato nella figura 1:

Figura 1. Flusso di messaggi / ack.

Al contrario, per evitare di sovraccaricare il server delle app, FCM interrompe l'invio se ci sono troppi messaggi non riconosciuti. Pertanto, il server delle app dovrebbe "ACK" i messaggi upstream, ricevuti dall'applicazione client tramite FCM, il più presto possibile per mantenere un flusso costante di messaggi in arrivo. Il suddetto limite di messaggi in sospeso non si applica a questi ACK. Anche se il conteggio dei messaggi in sospeso raggiunge 100, il server delle app dovrebbe continuare a inviare ACK per i messaggi ricevuti da FCM per evitare il blocco della consegna di nuovi messaggi a monte.

Gli ACK sono validi solo nel contesto di una connessione. Se la connessione viene chiusa prima che un messaggio possa essere ACK, il server delle app dovrebbe attendere che FCM rinvii il messaggio a monte prima di riaccenderlo. Allo stesso modo, tutti i messaggi in sospeso per i quali un ACK / NACK non è stato ricevuto da FCM prima della chiusura della connessione dovrebbero essere inviati di nuovo.