Protocollo XMPP di Firebase Cloud Messaging

Questo documento fornisce un riferimento per la sintassi XMPP utilizzata per passare messaggi tra il server delle app, le app client e Firebase Cloud Messaging (FCM). Il tuo server delle applicazioni deve connettersi a questi endpoint:

// Production
fcm-xmpp.googleapis.com:5235

// Testing
fcm-xmpp.googleapis.com:5236

I parametri e le opzioni disponibili rientrano in queste categorie:

Sintassi del messaggio downstream

Questa sezione fornisce la sintassi per l'invio di messaggi downstream.

Messaggi XMPP downstream (JSON)

La tabella seguente elenca le destinazioni, le opzioni e il payload per i messaggi XMPP JSON.

Tabella 1 Destinazioni, opzioni e payload per i messaggi XMPP downstream (JSON).

Parametro Utilizzo Descrizione
Bersaglio
to Facoltativo, stringa

Questo parametro specifica il destinatario di un messaggio.

Il valore può essere il token di registrazione di un dispositivo, la chiave di notifica di un gruppo di dispositivi o un singolo argomento (con il prefisso /topics/ ). Per inviare a più argomenti, utilizzare il parametro condition .

condition Facoltativo, stringa

Questo parametro specifica un'espressione logica di condizioni che determina la destinazione del messaggio.

Condizione supportata: argomento, formattato come "'yourTopic' negli argomenti". Questo valore non fa distinzione tra maiuscole e minuscole.

Operatori supportati: && , || . Sono supportati un massimo di due operatori per messaggio di argomento.

Opzioni
message_id Obbligatorio, stringa

Questo parametro identifica in modo univoco un messaggio in una connessione XMPP.

collapse_key Facoltativo, stringa

Questo parametro identifica un gruppo di messaggi (ad esempio, con collapse_key: "Updates Available" ) che può essere compresso in modo che solo l'ultimo messaggio venga inviato quando viene ripresa la consegna. Questo ha lo scopo di evitare di inviare troppi messaggi uguali quando il dispositivo torna online o esce dal sonno.

Non esiste alcuna garanzia sull'ordine in cui i messaggi vengono inviati.

Nota: è consentito un massimo di 4 chiavi di compressione diverse alla volta. Ciò significa che FCM può archiviare contemporaneamente 4 messaggi diversi per app client. Se si supera questo numero, non vi è alcuna garanzia su quali 4 chiavi di compressione FCM manterrà.

priority Facoltativo, stringa

Imposta la priorità del messaggio. I valori validi sono "normale" e "alto". Sulle piattaforme Apple corrispondono alle priorità 5 e 10 degli APN.

Per impostazione predefinita, i messaggi di notifica vengono inviati con priorità alta mentre i messaggi di dati vengono inviati con priorità normale. La priorità normale ottimizza il consumo della batteria dell'app client e deve essere utilizzata a meno che non sia richiesta la consegna immediata. Per i messaggi con priorità normale, l'app potrebbe ricevere il messaggio con un ritardo non specificato.

Quando un messaggio viene inviato con priorità alta, viene inviato immediatamente e l'app può visualizzare una notifica.

content_available Facoltativo, booleano

Sulle piattaforme Apple, utilizza questo campo per rappresentare content-available nel payload APN. Quando viene inviata una notifica o un messaggio e questo è impostato su true , viene riattivata un'app client inattiva e il messaggio viene inviato tramite APN come notifica silenziosa e non tramite FCM. Tieni presente che non è garantito che le notifiche silenziose negli APN vengano consegnate e possono dipendere da fattori come l'attivazione della modalità di risparmio energetico da parte dell'utente, la chiusura forzata dell'app, ecc. Su Android, i messaggi di dati riattivano l'app per impostazione predefinita. Su Chrome, attualmente non supportato.

mutable_content Facoltativo, valore booleano JSON

Sulle piattaforme Apple, utilizza questo campo per rappresentare mutable-content nel payload degli APN. Quando viene inviata una notifica e questa è impostata su true , il contenuto della notifica può essere modificato prima che venga visualizzato, utilizzando un'estensione dell'app Notification Service . Questo parametro verrà ignorato per Android e web.

time_to_live Facoltativo, numero

Questo parametro specifica per quanto tempo (in secondi) il messaggio deve essere conservato nell'archivio FCM se il dispositivo è offline. Il periodo massimo di supporto è 4 settimane e il valore predefinito è 4 settimane. Per ulteriori informazioni, vedere Impostazione della durata di un messaggio .

dry_run Facoltativo, booleano

Questo parametro, se impostato su true , consente agli sviluppatori di testare una richiesta senza effettivamente inviare un messaggio.

Il valore predefinito è false .

Carico utile
data Opzionale, oggetto

Questo parametro specifica le coppie chiave-valore del payload del messaggio.

Ad esempio, con data:{"score":"3x1"}:

Sulle piattaforme Apple, se il messaggio viene recapitato tramite APN, rappresenta i campi dati personalizzati. Se viene consegnato da FCM, viene rappresentato come dizionario di valori chiave AppDelegate application:didReceiveRemoteNotification: .

Su Android, ciò si traduce in un score denominato extra con il valore di stringa 3x1 .

La chiave non deve essere una parola riservata ("da", "tipo_messaggio" o qualsiasi parola che inizi con "google" o "gcm"). Non utilizzare nessuna delle parole definite in questa tabella (come collapse_key ).

Si consigliano valori nei tipi stringa. È necessario convertire i valori negli oggetti o in altri tipi di dati non stringa (ad esempio, numeri interi o booleani) in stringhe.

notification Opzionale, oggetto Questo parametro specifica le coppie chiave-valore predefinite e visibili all'utente del payload della notifica. Vedi Supporto del payload delle notifiche per i dettagli. Per ulteriori informazioni sui messaggi di notifica e sulle opzioni dei messaggi di dati, vedere Tipi di messaggi . Se viene fornito un payload di notifica o l'opzione content_available è impostata su true per un messaggio a un dispositivo Apple, il messaggio viene inviato tramite APN , altrimenti viene inviato tramite FCM.

Supporto del payload delle notifiche

Le tabelle seguenti elencano le chiavi predefinite disponibili per la creazione di messaggi di notifica per piattaforme Apple e Android.

Tabella 2a. Apple: tasti per i messaggi di notifica

Parametro Utilizzo Descrizione
title Facoltativo, stringa

Il titolo della notifica.

Questo campo non è visibile su telefoni e tablet.

body Facoltativo, stringa

Il corpo del testo della notifica.

sound Facoltativo, stringa

Il suono da riprodurre quando il dispositivo riceve la notifica.

Stringa che specifica i file audio nel pacchetto principale dell'app client o nella cartella Library/Sounds del contenitore dati dell'app. Consulta la Libreria per sviluppatori iOS per ulteriori informazioni.

badge Facoltativo, stringa

Il valore del badge sull'icona dell'app nella schermata iniziale.

Se non specificato il badge non viene modificato.

Se impostato a 0 il badge viene rimosso.

click_action Facoltativo, stringa

L'azione associata a un clic dell'utente sulla notifica.

Corrisponde alla category nel payload APN.

subtitle Facoltativo, stringa

Il sottotitolo della notifica.

body_loc_key Facoltativo, stringa

Chiave della stringa del corpo nelle risorse stringa dell'app da utilizzare per localizzare il corpo del testo nella localizzazione corrente dell'utente.

Corrisponde a loc-key nel payload APN.

Per ulteriori informazioni, consulta Riferimento alla chiave del payload e Localizzazione del contenuto delle notifiche remote .

body_loc_args Facoltativo, array JSON come stringa

Valori di stringa variabili da utilizzare al posto degli identificatori di formato in body_loc_key da utilizzare per localizzare il corpo del testo nella localizzazione corrente dell'utente.

Corrisponde a loc-args nel payload APN.

Per ulteriori informazioni, consulta Riferimento alla chiave del payload e Localizzazione del contenuto delle notifiche remote .

title_loc_key Facoltativo, stringa

Chiave della stringa del titolo nelle risorse stringa dell'app da utilizzare per localizzare il testo del titolo nella localizzazione corrente dell'utente.

Corrisponde alla title-loc-key nel payload APN.

Per ulteriori informazioni, consulta Riferimento alla chiave del payload e Localizzazione del contenuto delle notifiche remote .

title_loc_args Facoltativo, array JSON come stringa

Valori di stringa variabili da utilizzare al posto degli identificatori di formato in title_loc_key da utilizzare per localizzare il testo del titolo nella localizzazione corrente dell'utente.

Corrisponde a title-loc-args nel payload APN.

Per ulteriori informazioni, consulta Riferimento alla chiave del payload e Localizzazione del contenuto delle notifiche remote .

Tabella 2b. Android: tasti per i messaggi di notifica

Parametro Utilizzo Descrizione
title Facoltativo, stringa

Il titolo della notifica.

body Facoltativo, stringa

Il corpo del testo della notifica.

android_channel_id Facoltativo, stringa

L' ID del canale della notifica (nuovo in Android O).

L'app deve creare un canale con questo ID canale prima che venga ricevuta qualsiasi notifica con questo ID canale.

Se non invii questo ID canale nella richiesta o se l'ID canale fornito non è stato ancora creato dall'app, FCM utilizza l'ID canale specificato nel manifest dell'app.

icon Facoltativo, stringa

L'icona della notifica.

Imposta l'icona di notifica su myicon per la risorsa disegnabile myicon . Se non invii questa chiave nella richiesta, FCM visualizza l'icona di avvio specificata nel manifest dell'app.

sound Facoltativo, stringa

Il suono da riprodurre quando il dispositivo riceve la notifica.

Supporta "default" o il nome file di una risorsa audio inclusa nell'app. I file audio devono risiedere in /res/raw/ .

tag Facoltativo, stringa

Identificatore utilizzato per sostituire le notifiche esistenti nel cassetto delle notifiche.

Se non specificato, ogni richiesta crea una nuova notifica.

Se specificato ed è già visualizzata una notifica con lo stesso tag, la nuova notifica sostituisce quella esistente nel cassetto delle notifiche.

color Facoltativo, stringa

Il colore dell'icona della notifica, espresso nel formato #rrggbb .

click_action Facoltativo, stringa

L'azione associata a un clic dell'utente sulla notifica.

Se specificato, viene avviata un'attività con un filtro di intento corrispondente quando un utente fa clic sulla notifica.

body_loc_key Facoltativo, stringa

Chiave della stringa del corpo nelle risorse stringa dell'app da utilizzare per localizzare il corpo del testo nella localizzazione corrente dell'utente.

Vedi Risorse stringa per ulteriori informazioni.

body_loc_args Facoltativo, array JSON come stringa

Valori di stringa variabili da utilizzare al posto degli identificatori di formato in body_loc_key da utilizzare per localizzare il corpo del testo nella localizzazione corrente dell'utente.

Per ulteriori informazioni, vedere Formattazione e stile .

title_loc_key Facoltativo, stringa

Chiave della stringa del titolo nelle risorse stringa dell'app da utilizzare per localizzare il testo del titolo nella localizzazione corrente dell'utente.

Vedi Risorse stringa per ulteriori informazioni.

title_loc_args Facoltativo, array JSON come stringa

Valori di stringa variabili da utilizzare al posto degli identificatori di formato in title_loc_key da utilizzare per localizzare il testo del titolo nella localizzazione corrente dell'utente.

Per ulteriori informazioni, vedere Formattazione e stile .

Tabella 2c. Web (JavaScript): tasti per i messaggi di notifica

Parametro Utilizzo Descrizione
title Facoltativo, stringa

Il titolo della notifica.

body Facoltativo, stringa

Il corpo del testo della notifica.

icon Facoltativo, stringa

L'URL da utilizzare per l'icona della notifica.

click_action Facoltativo, stringa

L'azione associata a un clic dell'utente sulla notifica.

Per tutti i valori URL, è obbligatorio HTTPS.

Interpretare una risposta al messaggio XMPP downstream

Nella tabella seguente sono elencati i campi visualizzati in una risposta al messaggio XMPP downstream.

Tabella 3 Corpo della risposta XMPP del messaggio downstream.

Parametro Utilizzo Descrizione
from Obbligatorio, stringa

Questo parametro specifica chi ha inviato questa risposta.

Il valore è il token di registrazione dell'app client.

message_id Obbligatorio, stringa Questo parametro identifica in modo univoco un messaggio in una connessione XMPP. Il valore è una stringa che identifica in modo univoco il messaggio associato.
message_type Obbligatorio, stringa

Questo parametro specifica un messaggio ack o nack da FCM al server delle applicazioni.

Se il valore è impostato su nack , il server delle applicazioni dovrebbe esaminare error ed error_description per ottenere informazioni sull'errore.

error Facoltativo, stringa Questo parametro specifica un errore relativo al messaggio downstream. Viene impostato quando message_type è nack . Vedere la tabella 4 per i dettagli.
error_description Facoltativo, stringa Questo parametro fornisce informazioni descrittive per l'errore. Viene impostato quando message_type è nack .

Codici di risposta agli errori dei messaggi downstream

Nella tabella seguente sono elencati i codici di risposta all'errore per i messaggi downstream.

Tabella 4 Codici di risposta agli errori dei messaggi downstream.

Errore Codice XMPP Azione raccomandata
Token di registrazione mancante INVALID_JSON Verifica che la richiesta contenga un token di registrazione (nel registration_id in un messaggio di testo semplice o nel campo to o registration_ids in JSON).
Registrazione APN non valida INVALID_JSON Per le registrazioni iOS, verificare che la richiesta di registrazione del client contenga un token APN e un ID applicazione validi.
Token di registrazione non valido BAD_REGISTRATION Controlla il formato del token di registrazione che passi al server. Assicurati che corrisponda al token di registrazione che l'app client riceve dalla registrazione con FCM. Non troncare né aggiungere ulteriori caratteri.
Dispositivo non registrato DEVICE_UNREGISTERED Un token di registrazione esistente può cessare di essere valido in una serie di scenari, tra cui:
  • Se l'app client annulla la registrazione con FCM.
  • Se la registrazione dell'app client viene annullata automaticamente, ciò può verificarsi se l'utente disinstalla l'applicazione. Ad esempio, su iOS, se gli APN hanno segnalato il token APN come non valido.
  • Se il token di registrazione scade (ad esempio, Google potrebbe decidere di aggiornare i token di registrazione o il token APN è scaduto per i dispositivi).
  • Se l'app client viene aggiornata, ma la nuova versione non è configurata per ricevere messaggi.
In tutti questi casi, rimuovi questo token di registrazione dal server dell'app e smetti di usarlo per inviare messaggi.
Mittente non corrispondente SENDER_ID_MISMATCH Un token di registrazione è legato a un determinato gruppo di mittenti. Quando un'app client si registra per FCM, deve specificare quali mittenti sono autorizzati a inviare messaggi. Dovresti utilizzare uno di questi ID mittente quando invii messaggi all'app client. Se passi a un mittente diverso, i token di registrazione esistenti non funzioneranno.
JSON non valido INVALID_JSON Controlla che il messaggio JSON sia formattato correttamente e contenga campi validi (ad esempio, assicurandoti che venga passato il tipo di dati corretto).
Messaggio troppo grande INVALID_JSON Verificare che la dimensione totale dei dati del payload inclusi in un messaggio non superi i limiti FCM: 4096 byte per la maggior parte dei messaggi o 2048 byte nel caso di messaggi ad argomenti. Ciò include sia le chiavi che i valori.
Chiave dati non valida INVALID_JSON Controlla che i dati del payload non contengano una chiave (come from , gcm o qualsiasi valore con prefisso google ) utilizzata internamente da FCM. Tieni presente che alcune parole (come collapse_key ) sono utilizzate anche da FCM ma sono consentite nel payload, nel qual caso il valore del payload viene sovrascritto dal valore FCM.
Tempo di vita non valido INVALID_JSON Verifica che il valore utilizzato in time_to_live sia un numero intero che rappresenta una durata in secondi compresa tra 0 e 2.419.200 (4 settimane).
Messaggio ACK errato BAD_ACK Controlla che il messaggio ack sia formattato correttamente prima di riprovare. Vedere la tabella 6 per i dettagli.
Tempo scaduto SERVICE_UNAVAILABLE

Il server non è riuscito a elaborare la richiesta in tempo. Riprovare la stessa richiesta, ma è necessario:

  • Implementa il backoff esponenziale nel meccanismo dei nuovi tentativi. (ad esempio, se hai aspettato un secondo prima del primo tentativo, attendi almeno due secondi prima del successivo, poi quattro secondi e così via). Se invii più messaggi, ritarda ciascuno di essi in modo indipendente di un importo casuale aggiuntivo per evitare di inviare una nuova richiesta per tutti i messaggi contemporaneamente.
  • Il ritardo del primo tentativo deve essere impostato su un secondo.

Nota: i mittenti che causano problemi rischiano di essere inseriti nella lista nera.

Errore interno del server INTERNAL_SERVER_
ERROR
Il server ha riscontrato un errore durante il tentativo di elaborare la richiesta. Puoi riprovare la stessa richiesta seguendo i requisiti elencati in "Timeout" (vedi riga sopra).
Velocità messaggi dispositivo superata DEVICE_MESSAGE_RATE
_EXCEEDED
La frequenza dei messaggi inviati a un particolare dispositivo è troppo elevata. Ridurre il numero di messaggi inviati a questo dispositivo e non ritentare immediatamente l'invio a questo dispositivo.
La frequenza dei messaggi sugli argomenti è stata superata TOPICS_MESSAGE_RATE
_EXCEEDED
La frequenza dei messaggi agli abbonati a un particolare argomento è troppo alta. Riduci il numero di messaggi inviati per questo argomento e non ritentare immediatamente l'invio.
Connessione Drenante CONNECTION_DRAINING Impossibile elaborare il messaggio perché la connessione è in esaurimento. Ciò accade perché, periodicamente, FCM deve chiudere una connessione per eseguire il bilanciamento del carico. Riprovare a inviare il messaggio tramite un'altra connessione XMPP.
Credenziali APN non valide INVALID_APNS_CREDENTIAL Non è stato possibile inviare un messaggio destinato a un dispositivo iOS perché la chiave di autenticazione APN richiesta non è stata caricata o è scaduta. Verifica la validità delle tue credenziali di sviluppo e produzione.
Autenticazione fallita AUTHENTICATION_FAILED Impossibile autenticarsi con servizi push esterni. Controlla se stai utilizzando i certificati push web corretti.

Sintassi del messaggio upstream

Un messaggio upstream è un messaggio che l'app client invia al server dell'app. Attualmente solo XMPP supporta la messaggistica upstream. Consulta la documentazione della tua piattaforma per ulteriori informazioni sull'invio di messaggi dalle app client.

Interpretazione di un messaggio XMPP upstream

La seguente tabella descrive i campi nella stanza XMPP generata da FCM in risposta alle richieste di messaggi upstream dalle applicazioni client.

Tabella 5 Messaggi XMPP upstream.

Parametro Utilizzo Descrizione
from Obbligatorio, stringa

Questo parametro specifica chi ha inviato il messaggio.

Il valore è il token di registrazione dell'app client.

category Obbligatorio, stringa Questo parametro specifica il nome del pacchetto dell'applicazione client che ha inviato il messaggio.
message_id Obbligatorio, stringa Questo parametro specifica l'ID univoco del messaggio.
data Facoltativo, stringa Questo parametro specifica le coppie chiave-valore del payload del messaggio.

Invio di un messaggio ACK

La tabella seguente descrive la risposta ACK che è previsto che il server delle applicazioni invii a FCM in risposta a un messaggio upstream ricevuto dal server delle applicazioni.

Tabella 6 Risposta al messaggio XMPP upstream.

Parametro Utilizzo Descrizione
to Obbligatorio, stringa

Questo parametro specifica il destinatario di un messaggio di risposta.

Il valore deve essere un token di registrazione dell'app client che ha inviato il messaggio upstream.

message_id Obbligatorio, stringa Questo parametro specifica a quale messaggio è destinata la risposta. Il valore deve essere il valore message_id del messaggio upstream corrispondente.
message_type Obbligatorio, stringa Questo parametro specifica un messaggio ack da un server app a CCS. Per i messaggi upstream, dovrebbe essere sempre impostato su ack .

Messaggi del server FCM (XMPP)

Questo è un messaggio inviato da FCM a un server app. Ecco i principali tipi di messaggi che FCM invia al server dell'app:

  • Controllo: questi messaggi generati da CCS indicano che è richiesta un'azione da parte del server delle applicazioni.

La tabella seguente descrive i campi inclusi nei messaggi che CCS invia a un server app.

Tabella 7 Messaggi di controllo FCM (XMPP).

Parametro Utilizzo Descrizione
Campo comune
message_type Obbligatorio, stringa

Questo parametro specifica il tipo di messaggio: controllo.

Quando è impostato su control , il messaggio include control_type per indicare il tipo di messaggio di controllo.

control_type Facoltativo, stringa

Questo parametro specifica il tipo di messaggio di controllo inviato da FCM.

Attualmente è supportato solo CONNECTION_DRAINING . FCM invia questo messaggio di controllo prima di chiudere una connessione per eseguire il bilanciamento del carico. Man mano che la connessione si esaurisce, non è consentito inviare altri messaggi alla connessione, ma i messaggi esistenti nella pipeline continuano a essere elaborati.