Informazioni sui messaggi FCM

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

Tipi di messaggi

Con FCM puoi inviare ai clienti due tipi di messaggi:

• Messaggi di notifica, a volte considerati "messaggi di visualizzazione". Questi vengono gestiti automaticamente dall'SDK FCM.
• Messaggi di dati, che vengono gestiti dall'app client.

I messaggi di notifica contengono un insieme predefinito di chiavi visibili all'utente. I messaggi di dati, al contrario, contengono solo le coppie chiave-valore personalizzate definite dall'utente. I messaggi di notifica possono contenere un payload di dati facoltativo. Il payload massimo per entrambi i tipi di messaggi è 4096 byte, tranne quando si inviano messaggi dalla console Firebase, che applica un limite di 1000 caratteri.

	Scenario d'uso	Come inviare
Messaggio di notifica	L'SDK FCM mostra il messaggio sui dispositivi degli utenti finali per conto dell'app client quando è in esecuzione in background. In caso contrario, se l'app è in esecuzione in primo piano al momento della ricezione della notifica, il codice dell'app determina il comportamento. I messaggi di notifica includono un set predefinito di chiavi visibili all'utente e un payload di dati facoltativo di coppie chiave-valore personalizzate.	In un ambiente attendibile come Cloud Functions o il tuo server app, utilizza l'SDK Admin o l'API HTTP v1. Imposta la chiave notification. Può avere un payload di dati facoltativo. Sempre comprimibili. Guarda alcuni esempi di notifiche di visualizzazione e invia payload di richieste. Utilizza il compositore delle notifiche: inserisci il testo, il titolo e così via del messaggio e invia. Aggiungi payload di dati facoltativo fornendo dati personalizzati.
Messaggio di dati	L'app client è responsabile del trattamento dei messaggi di dati. I messaggi di dati contengono solo coppie chiave-valore personalizzate senza nomi di chiavi riservati (vedi di seguito).	In un ambiente attendibile come Cloud Functions o il tuo server app, utilizza l'SDK Admin o i Protocolli del server FCM. Nella richiesta di invio, imposta la chiave data.

Utilizza i messaggi di notifica quando vuoi che l'SDK FCM gestisca la visualizzazione automatica di una notifica quando la tua app è in esecuzione in background. Utilizza i messaggi di dati quando vuoi elaborare i messaggi con il tuo codice dell'app client.

FCM può inviare un messaggio di notifica che include un payload facoltativo di dati. In questi casi, FCM gestisce la visualizzazione del payload della notifica e l'app client gestisce il payload di dati.

Messaggi di notifica

Per i test o per il marketing e il ricoinvolgimento degli utenti, puoi inviare messaggi di notifica utilizzando la console Firebase. La console Firebase fornisce test A/B basati su dati e analisi per aiutarti a perfezionare e migliorare i messaggi di marketing.

Per inviare messaggi di notifica in modo programmatico utilizzando l'SDK Admin o i protocolli FCM, imposta la chiave notification con l'insieme predefinito necessario di opzioni chiave-valore per la parte visibile all'utente del messaggio di notifica. Ad esempio, ecco un messaggio di notifica in formato JSON in un'app di messaggistica immediata. L'utente potrà aspettarsi di visualizzare un messaggio con il titolo "Portogallo contro Danimarca" e il testo "Ottimo abbinamento!" sul dispositivo:

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

I messaggi di notifica vengono recapitati nella barra delle notifiche quando l'app è in background. Per le app in primo piano, i messaggi vengono gestiti da una funzione di callback.

Consulta la documentazione di riferimento relativa all'oggetto di notifica del protocollo HTTP v1 per l'elenco completo delle chiavi predefinite disponibili per la creazione di messaggi di notifica.

Messaggi di dati

Imposta la chiave appropriata con le coppie chiave-valore personalizzate per inviare un payload di dati all'app client.

Assicurati di non utilizzare parole riservate nelle tue coppie chiave-valore personalizzate. Le parole riservate includono "from", "notification", "message_type" o qualsiasi parola che inizi con "google" o "gcm".

Ad esempio, ecco un messaggio in formato JSON nella stessa app di messaggistica immediata precedente, in cui le informazioni sono incapsulate nella chiave data comune e l'app client dovrebbe interpretare i contenuti:

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

L'esempio riportato sopra mostra l'utilizzo del campo di primo livello o comune data, interpretato dai client su tutte le piattaforme che ricevono il messaggio. Su ogni piattaforma, l'app client riceve il payload dei dati in una funzione di callback.

Crittografia per i messaggi di dati

Il livello di trasporto di Android (vedi Architettura FCM) utilizza la crittografia punto a punto. A seconda delle tue esigenze, puoi decidere di aggiungere la crittografia end-to-end ai messaggi di dati. FCM non fornisce una soluzione end-to-end. Tuttavia, sono disponibili soluzioni esterne come Capillary o DTLS.

Messaggi di notifica con payload di dati facoltativi

Sia tramite programmazione che tramite la console Firebase, puoi inviare messaggi di notifica contenenti un payload facoltativo di coppie chiave/valore personalizzate. Nel Editor di notifiche, utilizza i campi Dati personalizzati in Opzioni avanzate.

Il comportamento dell'app quando riceve messaggi che includono sia i payload di notifica sia quelli di 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 dei dati solo quando l'utente tocca la notifica.
• Quando è in primo piano, l'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"
    }
  }
}

Personalizzazione di un messaggio su più piattaforme

Il protocollo HTTP Firebase Admin SDK e FCM v1 consentono entrambi alle richieste di messaggi di impostare tutti i campi disponibili nell'oggetto message. Sono inclusi:

• un insieme comune di campi da interpretare da tutte le istanze dell'app che ricevono il messaggio.
• insiemi di campi specifici della piattaforma, come AndroidConfig e WebpushConfig, interpretati solo dalle istanze dell'app in esecuzione sulla piattaforma specificata.

I blocchi specifici della piattaforma ti offrono la flessibilità di personalizzare i messaggi per piattaforme diverse per assicurarti che vengano gestiti correttamente al momento della ricezione. Il backend FCM prenderà in considerazione tutti i parametri specificati e personalizzerà il messaggio per ogni piattaforma.

Quando utilizzare i campi comuni

Utilizza i campi comuni quando:

• Targeting di istanze di app su tutte le piattaforme: Apple, Android e web
• Invio di messaggi agli argomenti

Tutte le istanze dell'app, indipendentemente dalla piattaforma, possono interpretare i seguenti campi comuni:

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

Quando utilizzare i campi specifici della piattaforma

Utilizza i campi specifici della piattaforma quando vuoi:

• Inviare campi solo a piattaforme specifiche
• Invia campi specifici della piattaforma oltre a quelli comuni

Quando vuoi inviare valori solo a piattaforme specifiche, non utilizzare i campi comuni, ma quelli specifici della piattaforma. Ad esempio, per inviare una notifica solo alle piattaforme Apple e al web, ma non ad Android, devi utilizzare due insiemi di campi distinti, uno per Apple e uno per il web.

Quando invii messaggi con opzioni di recapito specifiche, utilizza i campi specifici della piattaforma per impostarle. Se vuoi, puoi specificare valori diversi per piattaforma. Tuttavia, anche se vuoi impostare essenzialmente lo stesso valore su tutte le piattaforme, devi utilizzare campi specifici della piattaforma. Questo perché ogni piattaforma potrebbe interpretare il valore in modo leggermente diverso: ad esempio, la durata (TTL) è impostata su Android come una scadenza in secondi, mentre su Apple è impostata come data di scadenza.

Esempio: messaggio di notifica con opzioni di invio specifiche della piattaforma

La seguente richiesta di invio v1 invia un titolo e contenuti di notifica comuni a tutte le piattaforme, ma anche alcuni override specifici per le piattaforme. Nello specifico, la richiesta:

• consente di impostare una durata lunga per le piattaforme Android e web e di impostare la priorità dei messaggi degli APN (piattaforme Apple) su un valore basso
• imposta le chiavi appropriate per definire il risultato del tocco di un utente sulla notifica su Android e Apple, rispettivamente click_action e 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"
       }
     }
   }
 }

Consulta la documentazione di riferimento di HTTP v1 per informazioni dettagliate sulle chiavi disponibili nei blocchi specifici della piattaforma nel corpo del messaggio. Per ulteriori informazioni sulla creazione di richieste di invio che contengono il corpo del messaggio, consulta la sezione Creare richieste di invio.

Opzioni di consegna

FCM fornisce un insieme specifico di opzioni di recapito per i messaggi inviati ai dispositivi Android e consente opzioni simili sulle piattaforme Apple e sul web. Ad esempio, il comportamento dei messaggi "comprimibili" è supportato su Android tramite collapse_key di FCM, 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.

Messaggi comprimibili e non comprimibili

Un messaggio non comprimibile indica che ogni singolo messaggio viene recapitato sul dispositivo. Un messaggio non comprimibile fornisce alcuni contenuti utili, a differenza di un messaggio comprimibile come un "ping" senza contenuti all'app mobile per contattare il server e recuperare i dati.

FCM non garantisce l'ordine di invio.

Alcuni casi d'uso tipici dei messaggi non comprimibili sono i messaggi di chat o quelli critici. Ad esempio, in un'app di messaggistica istantanea, vorrai inviare ogni messaggio, perché ogni messaggio ha contenuti diversi.

Per Android esiste un limite di 100 messaggi che possono essere archiviati senza comprimersi. Se viene raggiunto il limite, tutti i messaggi archiviati vengono eliminati. Quando il dispositivo torna online, riceve un messaggio speciale che indica che è stato raggiunto il limite. L'app può quindi gestire la situazione correttamente, in genere richiedendo una sincronizzazione completa dal server dell'app.

Un messaggio comprimibile è un messaggio che può essere sostituito da un nuovo messaggio se non è ancora stato recapitato sul dispositivo.

Un caso d'uso comune dei messaggi comprimibili è quello di indicare a un'app mobile di sincronizzare i dati dal server. Un esempio è un'app sportiva che aggiorna gli utenti con il punteggio più recente. Solo il messaggio più recente è pertinente.

Per contrassegnare un messaggio come comprimibile su Android, includi il parametro collapse_key nel payload del messaggio. Per impostazione predefinita, la chiave di collasso è il nome del pacchetto dell'app registrato nella console Firebase. Il server FCM può archiviare contemporaneamente quattro diversi messaggi comprimibili per dispositivo, ognuno con una chiave di compressione diversa. Se superi questo numero, FCM conserva solo quattro chiavi di collasso, senza alcuna garanzia su quali vengano conservate.

I messaggi topic senza payload sono comprimibili per impostazione predefinita. I messaggi di notifica sono sempre comprimibili e ignorano il parametro collapse_key.

Quale devo utilizzare?

I messaggi comprimibili sono una scelta migliore dal punto di vista del rendimento, a condizione che la tua app non debba utilizzare messaggi non comprimibili. Tuttavia, se utilizzi messaggi comprimibili, ricorda che FCM consente l'utilizzo di un massimo di quattro chiavi di compressione diverse da FCM per token di registrazione in un dato momento. Non devi superare questo numero, altrimenti potrebbe causare conseguenze imprevedibili.

	Scenario d'uso	Come inviare
Non comprimibile	Ogni messaggio è importante per l'app client e deve essere inviato.	Ad eccezione dei messaggi di notifica, tutti i messaggi non sono comprimibili per impostazione predefinita.
Ripiegabili	Quando è presente un messaggio più recente che esegue il rendering di un messaggio correlato meno recente irrilevante per l'app client, FCM sostituisce il messaggio meno recente. Ad esempio: messaggi utilizzati per avviare una sincronizzazione dei dati dal server o messaggi di notifica устаревших.	Imposta il parametro appropriato nella richiesta di messaggi: collapseKey su Android apns-collapse-id su Apple Topic sul web collapse_key nei protocolli legacy (tutte le piattaforme)

Impostare la priorità di un messaggio

Hai due opzioni per assegnare la priorità di recapito ai messaggi a valle: prioritaria e normale. Sebbene il comportamento differisca leggermente tra le piattaforme, l'invio di messaggi con priorità normale e alta funziona come segue:

• Priorità normale. I messaggi con priorità normale vengono inviati immediatamente quando l'app è in primo piano. Per le app in background, l'invio 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 recapito normale.

• Priorità elevata. FCM tenta di inviare immediatamente i messaggi di alta priorità anche se il dispositivo è in modalità Sospensione. I messaggi con priorità elevata sono destinati a contenuti visibili agli utenti e soggetti a scadenza.

Quando invii messaggi di dati ai dispositivi Apple, la priorità deve essere impostata su 5 o su priorità normale. I messaggi inviati con priorità elevata vengono rifiutati dal backend di FCM con l'errore INVALID_ARGUMENT.

Ecco un esempio di messaggio con priorità normale inviato tramite il protocollo FCM HTTP v1 per informare un abbonato a una rivista che è possibile scaricare nuovi contenuti:

{
  "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 ulteriori dettagli specifici della piattaforma sull'impostazione della priorità dei messaggi:

• Documentazione degli APN
• Impostare e gestire la priorità dei messaggi (Android)
• Urgenza dei messaggi push web

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 (ad esempio 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, qualsiasi loro parte o funzionalità o il relativo accesso, per qualsiasi motivo e in qualsiasi momento, senza responsabilità o altri obblighi nei confronti dell'utente o dei suoi utenti.

Impostare la durata di un messaggio

FCM in genere consegna i messaggi immediatamente dopo che sono stati inviati. Tuttavia, questo potrebbe non essere sempre possibile. Ad esempio, se la piattaforma è Android, il dispositivo potrebbe essere spento, offline o non disponibile per altri motivi. 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 archivia il messaggio e lo invia appena possibile. Nella maggior parte dei casi questo non è un problema, ma per alcune app un messaggio in ritardo potrebbe non essere mai recapitato. Ad esempio, se il messaggio è una chiamata in arrivo o una notifica di videochiamata, avrà senso solo per un breve periodo di tempo prima che la chiamata venga terminata. In alternativa, 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 inviare il messaggio. Le richieste che non contengono questo campo vengono impostate sul periodo massimo di quattro settimane per impostazione predefinita.

Ecco alcuni possibili utilizzi di questa funzionalità:

• Chiamate in arrivo tramite chat video
• Eventi di inviti in scadenza
• Eventi nel 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 TTL di 0 secondi. FCM si impegna a gestire al meglio i messaggi che devono essere inviati "ora o mai più". Tieni presente che un valore time_to_live pari a 0 indica che i messaggi che non possono essere recapitati immediatamente vengono eliminati. Tuttavia, poiché questi messaggi non vengono mai archiviati, viene offerta la latenza migliore 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 un server dell'app pubblica un messaggio su FCM e riceve un ID messaggio, non significa che il messaggio sia già stato recapitato sul dispositivo. Significa invece che è stata accettata per la consegna. Ciò che accade al messaggio dopo essere stato accettato dipende da molti fattori.

Nella migliore delle ipotesi, 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à Sospensione, un messaggio con priorità bassa viene memorizzato da FCM finché il dispositivo non esce dalla modalità Sospensione. Il flag collapse_key assume un ruolo qui: se un messaggio con la stessa chiave di compressione (e lo stesso token di registrazione) è già archiviato e in attesa di essere recapitato, il vecchio messaggio viene eliminato e quello nuovo sostituisce quello nuovo, ovvero il vecchio messaggio viene compresso dal nuovo. Tuttavia, se la chiave collapse non è impostata, sia i messaggi nuovi che quelli vecchi vengono archiviati per l'invio futuro.

Se il dispositivo non è connesso a FCM, il messaggio viene memorizzato fino a quando non viene stabilita una connessione (rispettando sempre le regole delle chiavi di collasso). Quando viene stabilita una connessione, FCM invia tutti i messaggi in attesa al dispositivo. Se il dispositivo non si connette mai più (ad esempio se sono stati ripristinati i dati di fabbrica), il messaggio scade e viene eliminato dall'archiviazione FCM. Il timeout predefinito è di quattro settimane, a meno che non sia impostato il flag time_to_live.

Per saperne di più sulla consegna di un messaggio:

Per saperne di più sull'invio dei messaggi sulle piattaforme Android o Apple, consulta la FCMdashboard dei report, che registra il numero di messaggi inviati e aperti su dispositivi Apple e Android, nonché i 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 hai inviato, il tuo client riceve il callback onDeletedMessages(). L'app può quindi gestire la situazione correttamente, in genere richiedendo una sincronizzazione completa dal server dell'app.

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

Rallentamento e quote

Il nostro obiettivo è consegnare sempre tutti i messaggi inviati tramite FCM. Tuttavia, a volte l'invio di ogni messaggio comporta un'esperienza utente complessiva scadente. In altri casi, dobbiamo fornire dei limiti per garantire che FCM fornisca un servizio scalabile per tutti i mittenti. I tipi di limiti e quote descritti in questa sezione ci aiutano a bilanciare questi fattori importanti.

Nota: i limiti descritti in questa sezione sono soggetti a modifiche.

Limitazione dei messaggi downstream

L'API HTTP v1 ha introdotto quote per progetto e per minuto per la messaggistica a valle. La quota predefinita di 600.000 messaggi al minuto copre oltre il 99% degli sviluppatori di FCM, proteggendo al contempo la stabilità del sistema e riducendo al minimo l'impatto dei progetti con picchi.

I pattern di traffico con picchi possono causare errori di quota superata. In uno scenario di superamento della quota, il sistema pubblica il codice di stato HTTP 429 (QUOTA_EXCEEDED) fino a quando la quota non viene ricaricata nel minuto successivo. Le risposte 429 possono essere restituite anche in situazioni di sovraccarico, pertanto ti consigliamo vivamente di gestirle in base ai consigli pubblicati.

Ricorda:

• La quota downstream misura i messaggi, non le richieste.
• Vengono conteggiati gli errori client (codici di stato HTTP 400-499) (esclusi i codici 429).
• Le quote sono calcolate in base ai minuti, ma questi minuti non sono allineati all'orologio.

Quota di monitoraggio

Puoi visualizzare quota, utilizzo ed errori nella console Google Cloud:

1. Vai alla console Google Cloud
2. Seleziona API e servizi.
3. Dall'elenco delle tabelle, seleziona API Firebase Cloud Messaging
4. Seleziona QUOTA E LIMITI DI SISTEMA.

NOTA: questi grafici non sono allineati esattamente al tempo con i minuti di quota, il che significa che potrebbero essere serviti 429 secondi quando il traffico sembra essere inferiore alla quota.

Richiesta di aumento della quota

Prima di richiedere un aumento della quota, assicurati che:

• Il tuo utilizzo è regolarmente ≥ 80% della quota per almeno 5 minuti consecutivi al giorno.
• Il rapporto di errori client è inferiore al 5%, in particolare durante i picchi di traffico.
• Rispetta le best practice per l'invio di messaggi su larga scala.

Se soddisfi questi criteri, puoi inviare una richiesta di aumento della quota fino al +25% e FCM farà ogni sforzo pratico per soddisfare la richiesta (non è possibile garantire alcun aumento).

Se hai bisogno di un aumento della quota di messaggi downstream a causa di un lancio imminente o un evento temporaneo, richiedilo con almeno 15 giorni di anticipo per concedere un tempo sufficiente per gestire la richiesta. Per le richieste di grandi dimensioni (>18 milioni di messaggi al minuto), è necessario un preavviso di almeno 30 giorni. I lanci e le richieste di eventi speciali sono comunque soggetti al rapporto di errori del client e ai requisiti delle best practice.

Consulta anche le domande frequenti sulle quote di FCM.

Limite messaggi argomento

La velocità di aggiunta/rimozione delle sottoscrizioni di argomenti è limitata a 3000 QPS per progetto.

Per le frequenze di invio dei messaggi, consulta Ritardo del fanout.

Limitazione del fanout

La distribuzione di messaggi è il processo di invio di un messaggio a più dispositivi, ad esempio quando scegli come target argomenti e gruppi o quando utilizzi lo strumento di creazione di notifiche per scegliere come target segmenti di pubblico o utenti.

La distribuzione dei messaggi non è istantanea, pertanto a volte sono in corso più distribuzioni contemporaneamente. Limitiamo il numero di fanout simultanei di messaggi per progetto a 1000. Dopodiché, potremmo rifiutare ulteriori richieste di fanout o posticipare il fanout delle richieste fino al completamento di alcuni dei fanout già in corso.

Il tasso effettivo di fanout ottenibile dipende dal numero di progetti che richiedono fanout contemporaneamente. Un tasso di fanout di 10.000 QPS per un singolo progetto non è insolito, ma questo numero non è una garanzia ed è il risultato del carico totale sul sistema. È importante notare che la capacità di fanout disponibile viene divisa tra progetti e non tra richieste di fanout. Pertanto, se il tuo progetto ha due fanout in corso, ciascuno di questi vedrà solo metà della frequenza di fanout disponibile. Il modo consigliato per massimizzare la velocità di fanout è di avere in corso un solo fanout attivo alla volta.

Regolazione della frequenza dei messaggi comprimibili

Come descritto sopra, i messaggi comprimibili sono notifiche senza contenuti progettate per essere compresse una sopra l'altra. Se uno sviluppatore ripete lo stesso messaggio a un'app troppo spesso, ritardiamo (limitiamo) i messaggi per ridurre l'impatto sulla batteria di un utente.

Ad esempio, se invii un numero elevato di nuove richieste di sincronizzazione email a un singolo dispositivo, potremmo ritardare di alcuni minuti la successiva richiesta di sincronizzazione dell'email, in modo che il dispositivo possa sincronizzarsi a una velocità media inferiore. Questa limitazione viene eseguita esclusivamente per limitare l'impatto sulla batteria percepito dall'utente.

Se il tuo caso d'uso richiede pattern di invio con picchi elevati, i messaggi non comprimibili potrebbero essere la scelta giusta. Per questi messaggi, assicurati di includere i contenuti al loro interno per ridurre il consumo della batteria.

Limitiamo i messaggi comprimibili a una raffica di 20 messaggi per app e dispositivo, con un reintegro di 1 messaggio ogni 3 minuti.

Limitazione del server XMPP

Attenzione: l'invio di messaggi (inclusi i messaggi a monte) con le API legacy FCM XMPP e HTTP è stato ritirato il 20 giugno 2023 e verrà rimosso a partire da giugno 2024. Se utilizzi le API di invio FCM legacy, ti consigliamo vivamente di eseguire la migrazione all'API HTTP v1 o di valutare la possibilità di utilizzare l'SDK Admin per creare richieste di invio.

Limitiamo la frequenza con cui puoi connetterti ai server XMPP FCM a 400 connessioni al minuto per progetto. Questo non dovrebbe essere un problema per la consegna dei messaggi, ma è importante per garantire la stabilità del sistema. Per ogni progetto, FCM consente 2500 connessioni in parallelo.

Per la messaggistica upstream con XMPP, FCM limita i messaggi upstream a 1.500.000 al minuto per progetto per evitare di sovraccaricare i server di destinazione upstream.

Limitiamo a 1000/minuto i messaggi in upstream per dispositivo per proteggerti dall'esaurimento della batteria a causa del comportamento di app dannose.

Frequenza massima dei messaggi per un singolo dispositivo

Per Android, puoi inviare fino a 240 messaggi al minuto e 5000 messaggi all'ora a un singolo dispositivo. Questa soglia elevata è pensata per consentire picchi di traffico a breve termine, ad esempio quando gli utenti interagiscono rapidamente tramite chat. Questo limite impedisce che gli errori di invio della logica si scarichino inavvertitamente la batteria di un dispositivo.

Per iOS, viene restituito un errore quando la frequenza supera i limiti degli APN.

Attenzione: non inviare sistematicamente messaggi in prossimità di questa frequenza massima. Ciò potrebbe far sprecare le risorse degli utenti finali e la tua app potrebbe essere contrassegnata come illecita.

FCM porte e il firewall

Se la tua organizzazione dispone di un firewall per limitare il traffico da o verso internet, devi configurarlo in modo da consentire ai dispositivi mobili di connettersi a FCM affinché i dispositivi sulla tua rete ricevano messaggi. FCM in genere utilizza la porta 5228, ma a volte utilizza 443, 5229 e 5230.

Per i dispositivi che si connettono alla tua rete, FCM non fornisce IP specifici perché il nostro intervallo IP cambia troppo spesso e le regole del firewall potrebbero non essere aggiornate, con ripercussioni sull'esperienza degli utenti. Idealmente, inserisci nella lista consentita le porte 5228-5230 e 443 senza limitazioni IP. Tuttavia, se devi applicare una limitazione IP, devi inserire nella lista consentita tutti gli indirizzi IP elencati in goog.json. Questo ampio elenco viene aggiornato regolarmente e ti consigliamo di aggiornare le regole su base mensile. I problemi causati dalle limitazioni IP del firewall sono spesso intermittenti e difficili da diagnosticare.

Offriamo una serie di nomi di dominio che possono essere inseriti nella lista consentita anziché indirizzi IP. Questi nomi host sono elencati di seguito. Se inizieremo a utilizzare altri nomi host, aggiorneremo l'elenco qui. L'utilizzo di nomi di dominio per la regola del firewall può o meno essere funzionale nel dispositivo firewall.

Porte TCP da aprire:

• 5228
• 5229
• 5230
• 443

Nomi host da aprire:

• 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

Firewall con Network Address Translation e/o ispezione approfondita dei pacchetti:

Se la tua rete implementa la Network Address Translation (NAT) o la Stateful Packet Inspection (SPI), implementa un timeout di almeno 30 minuti per le nostre connessioni tramite le porte 5228-5230. In questo modo possiamo offrire una connettività affidabile riducendo al contempo il consumo della batteria dei dispositivi mobili dei tuoi utenti.

Nota: se ricevi notifiche tramite APN, assicurati di aver aperto anche le porte specificate da Apple.

Interazioni e possibilità di bypass delle VPN

Firebase Cloud Messaging adotta vari passaggi per garantire che la connessione di messaggistica push dal telefono al server sia affidabile e disponibile il più spesso possibile. L'utilizzo di una VPN complica questo sforzo.

Le VPN mascherano le informazioni sottostanti di cui FCM ha bisogno per ottimizzare la connessione al fine di massimizzare l'affidabilità e la durata della batteria. In alcuni casi le VPN interrompono attivamente le connessioni di lunga durata, causando un'esperienza utente negativa a causa di messaggi persi o ritardati o a un costo elevato della batteria. Se la VPN è configurata in modo da consentire questa operazione, la aggiriamo utilizzando una connessione criptata (tramite Wi-Fi o LTE di rete di base), in modo da garantire un'esperienza affidabile e che dura la batteria. L'utilizzo di VPN aggirabili da parte di FCM è specifico per il canale di notifica push di FCM. L'altro traffico FCM, ad esempio il traffico di registrazione, utilizza la VPN se è attiva. Quando la connessione FCM aggira la VPN, perde i vantaggi aggiuntivi che la VPN potrebbe offrire, come il mascheramento IP.

VPN diverse avranno metodi diversi per controllare se possono essere aggirate o meno. Per istruzioni, consulta la documentazione della VPN specifica.

Se la VPN non è configurata per essere aggirata, Firebase Cloud Messaging userà la rete VPN per connettersi al server. Ciò potrebbe causare periodi di tempo in cui i messaggi subiscono ritardi e un maggiore utilizzo della batteria, in quanto Cloud Messaging lavora per mantenere la connessione tramite la connessione VPN.

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 FCM v1. Questo valore è disponibile nel riquadro Impostazioni della console Firebase.
Token di registrazione	Una stringa token univoca che identifica ogni istanza dell'app client. Il token di registrazione è necessario per i messaggi di gruppo e per i singoli 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 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 appartenente al tuo progetto Firebase. Per creare e ruotare i token di accesso, segui i passaggi descritti in Autorizzare le richieste di invio.
Chiave server (per i protocolli precedenti **ritratte**)	Una chiave server che autorizza il server dell'app per l'accesso ai servizi Google, inclusa l'invio di messaggi tramite i protocolli legacy Firebase Cloud Messaging ritirati. Importante: non includere la chiave server in nessun punto del codice client. Inoltre, assicurati di utilizzare solo le chiavi del server per autorizzare il tuo server app. Le chiavi Android, della piattaforma Apple e del browser vengono rifiutate da FCM.