Informazioni sui messaggi FCM

Firebase Cloud Messaging (FCM) offre un'ampia gamma di opzioni e funzionalità di messaggistica. Le informazioni contenute in questa pagina hanno lo scopo di aiutarti a comprendere i diversi tipi di messaggi FCM e cosa puoi fare con loro.

Messaggi di notifica con payload di dati facoltativo

A livello di programmazione o tramite la console Firebase, puoi inviare messaggi di notifica che contengono un payload facoltativo di coppie chiave/valore personalizzate. Nel composer delle notifiche, utilizza i campi Dati personalizzati nelle Opzioni avanzate.

Il comportamento dell'app quando riceve messaggi che includono payload di notifica e dati dipende dal fatto che l'app sia in background o in primo piano, ovvero se è attiva o meno al momento della ricezione.

  • Quando sono in background, le app ricevono il payload di notifica nella barra delle notifiche e gestiscono il payload di dati solo quando l'utente tocca la notifica.
  • Quando è in primo piano, la tua app riceve un oggetto messaggio con entrambi i payload disponibili.

Ecco un messaggio in formato JSON contenente sia la chiave notification sia la chiave data:

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

Opzioni di consegna

FCM fornisce un insieme specifico di opzioni di recapito per i messaggi inviati a dispositivi Android e consente opzioni simili su piattaforme Apple e sul web. Ad esempio, il comportamento dei messaggi "comprimibili" è supportato su Android tramite FCM's collapse_key, su Apple tramite apns-collapse-id e su JavaScript/web tramite Topic. Per maggiori dettagli, consulta le descrizioni in questa sezione e la documentazione di riferimento correlata.

Impostare la priorità di un messaggio

Hai due opzioni per assegnare la priorità di consegna ai messaggi downstream: priorità normale e alta. Sebbene il comportamento differisca leggermente tra le piattaforme, la distribuzione dei messaggi con priorità normale e alta funziona in questo modo:

  • Priorità normale. I messaggi con priorità normale vengono consegnati immediatamente quando l'app è in primo piano. Per le app in background, la consegna potrebbe subire ritardi. Per i messaggi meno urgenti, ad esempio le notifiche di nuove email, la sincronizzazione dell'interfaccia utente o la sincronizzazione dei dati delle app in background, scegli la priorità di distribuzione normale.

  • Priorità elevata. FCM tenta di recapitare immediatamente i messaggi ad alta priorità anche se il dispositivo è in modalità Doze. I messaggi con priorità elevata sono destinati a contenuti urgenti e visibili agli utenti.

Di seguito è riportato un esempio di messaggio con priorità normale inviato tramite il protocollo HTTP v1 FCM per comunicare a un abbonato a una rivista che sono disponibili nuovi contenuti da scaricare:

{
  "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"
      }
    }
  }
}

Per maggiori dettagli specifici per la piattaforma sull'impostazione della priorità dei messaggi:

Casi d'uso critici per la vita

Le API FCM non sono progettate per avvisi di emergenza o altre attività ad alto rischio in cui l'utilizzo o il malfunzionamento delle API potrebbe causare morte, lesioni personali o danni ambientali (come il funzionamento di impianti nucleari, il controllo del traffico aereo o i sistemi di supporto vitale). Qualsiasi utilizzo di questo tipo è espressamente vietato ai sensi della Sezione 4. a. 7 dei Termini di servizio. Sei l'unico responsabile della gestione della conformità della tua app ai Termini e di eventuali danni derivanti dalla mancata conformità. Google fornisce le API "così come sono" e si riserva il diritto di interrompere le API o qualsiasi parte o funzionalità o il tuo accesso alle stesse, per qualsiasi motivo e in qualsiasi momento, senza responsabilità o altri obblighi nei tuoi confronti o nei confronti dei tuoi utenti.

Impostare la durata di un messaggio

FCM in genere recapita i messaggi immediatamente dopo l'invio. Tuttavia, potrebbe non essere sempre possibile. Ad esempio, se la piattaforma è Android, il dispositivo potrebbe essere spento, offline o non disponibile. In alternativa, FCM potrebbe ritardare intenzionalmente i messaggi per impedire a un'app di consumare risorse eccessive e influire negativamente sulla durata della batteria.

In questi casi, FCM memorizza il messaggio e lo invia non appena è possibile. Sebbene questo vada bene nella maggior parte dei casi, esistono alcune app per le quali un messaggio in ritardo potrebbe non essere mai consegnato. Ad esempio, se il messaggio è una notifica di chiamata o videochiamata in arrivo, è significativo solo per un breve periodo di tempo prima che la chiamata venga terminata. Oppure, se il messaggio è un invito a un evento, è inutile se ricevuto dopo la fine dell'evento.

Su Android e Web/JavaScript, puoi specificare la durata massima di un messaggio. Il valore deve essere una durata compresa tra 0 e 2.419.200 secondi (28 giorni) e corrisponde al periodo di tempo massimo per cui FCM memorizza e tenta di recapitare il messaggio. Le richieste che non contengono questo campo hanno come valore predefinito il periodo massimo di quattro settimane.

Ecco alcuni possibili utilizzi di questa funzionalità:

  • Chiamate in arrivo con chat video
  • Eventi di invito in scadenza
  • Eventi di calendario

Un altro vantaggio della specifica della durata di un messaggio è che FCM non applica la limitazione dei messaggi comprimibili ai messaggi con un valore Time to Live di 0 secondi. FCM offre la gestione migliore possibile dei messaggi che devono essere recapitati "ora o mai più". Tieni presente che un valore time_to_live pari a 0 indica che i messaggi che non possono essere consegnati immediatamente vengono eliminati. Tuttavia, poiché questi messaggi non vengono mai archiviati, ciò garantisce la migliore latenza per l'invio di messaggi di notifica.

Ecco un esempio di richiesta che include il 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"
      }
    }
  }
}

Durata di un messaggio

Quando il server di un'app pubblica un messaggio su FCM e riceve un ID messaggio, non significa che il messaggio sia già stato recapitato al dispositivo. Significa invece che è stato accettato per la consegna. Ciò che accade al messaggio dopo l'accettazione dipende da molti fattori.

Nello scenario migliore, se il dispositivo è connesso a FCM, lo schermo è acceso e non ci sono limitazioni di throttling, il messaggio viene recapitato immediatamente.

Se il dispositivo è connesso ma in modalità Doze, un messaggio a bassa priorità viene memorizzato da FCM finché il dispositivo non esce dalla modalità Doze. Ed è qui che entra in gioco il flag collapse_key: se è già presente un messaggio con la stessa chiave di compressione (e lo stesso token di registrazione) archiviato e in attesa di consegna, il vecchio messaggio viene eliminato e sostituito dal nuovo (ovvero, il vecchio messaggio viene compresso dal nuovo). Tuttavia, se la chiave di compressione non è impostata, sia i messaggi nuovi che quelli vecchi vengono archiviati per la consegna futura.

Se il dispositivo non è connesso a FCM, il messaggio viene memorizzato finché non viene stabilita una connessione (rispettando di nuovo le regole della chiave di compressione). Quando viene stabilita una connessione, FCM invia tutti i messaggi in attesa al dispositivo. Se il dispositivo non si connette più (ad esempio, se sono stati ripristinati i dati di fabbrica), il messaggio scade e viene eliminato dallo spazio di archiviazione di FCM. Il timeout predefinito è di quattro settimane, a meno che non sia impostato il flag time_to_live.

Per ottenere maggiori informazioni sulla consegna di un messaggio:

    Per ottenere maggiori informazioni sulla distribuzione dei messaggi sulle piattaforme Android o Apple, consulta la dashboard dei report FCM, che registra il numero di messaggi inviati e aperti su dispositivi Apple e Android, insieme ai dati relativi alle "impressioni" (notifiche visualizzate dagli utenti) per le app per Android.

Per i dispositivi Android con la messaggistica diretta del canale abilitata, se il dispositivo non si è connesso a FCM per più di un mese, FCM accetta comunque il messaggio, ma lo elimina immediatamente. Se il dispositivo si connette entro quattro settimane dall'ultimo messaggio di dati che gli hai inviato, il client riceve il callback onDeletedMessages(). L'app può quindi gestire correttamente la situazione, in genere richiedendo una sincronizzazione completa dal server dell'app.

Infine, quando FCM tenta di recapitare un messaggio al dispositivo e l'app è stata disinstallata, FCM scarta immediatamente il messaggio e invalida il token di registrazione. I tentativi futuri di inviare un messaggio a quel dispositivo generano un errore NotRegistered.

Credenziali

A seconda delle funzionalità di FCM che implementi, potresti aver bisogno delle seguenti credenziali del tuo progetto Firebase:

ID progetto Un identificatore univoco per il tuo progetto Firebase, utilizzato nelle richieste all'endpoint HTTP v1 di FCM. Questo valore è disponibile nel riquadro Firebase console Impostazioni.
Token di registrazione

Una stringa di token univoca che identifica ogni istanza dell'app client. Il token di registrazione è necessario per la messaggistica su un singolo dispositivo e su un gruppo di dispositivi. Tieni presente che i token di registrazione devono essere mantenuti segreti.
ID mittente Un valore numerico univoco creato quando crei il progetto Firebase, disponibile nella scheda Cloud Messaging della console Firebase nel riquadro Impostazioni. L'ID mittente viene utilizzato per identificare ogni mittente che può inviare messaggi all'app client.
Token di accesso Un token OAuth 2.0 di breve durata che autorizza le richieste all'API HTTP v1. Questo token è associato a un account di servizio che appartiene al tuo progetto Firebase. Per creare e ruotare i token di accesso, segui i passaggi descritti in Autorizzare le richieste di invio.