Protocollo XMPP di Firebase Cloud Messaging

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.

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

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

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

I parametri e le opzioni disponibili rientrano nelle seguenti categorie:

• Sintassi dei messaggi a valle
• Codici di risposta di errore dei messaggi a valle
• Sintassi dei messaggi upstream
• Messaggi di controllo FCM

Sintassi dei messaggi downstream

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

Messaggi XMPP a valle (JSON)

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

Tabella 1 Destinatari, opzioni e payload per i messaggi XMPP a valle (JSON).

Parametro	Utilizzo	Descrizione
Destinazione
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 prefisso /topics/). Per l'invio a più argomenti, utilizza il parametro condition.
condition	Facoltativo, stringa	Questo parametro specifica un'espressione logica di condizioni che determina il target del messaggio. Condizione supportata: Argomento, formattato come "'yourTopic' in topics". Questo valore non è sensibile alle maiuscole. Operatori supportati: &&, ||. Sono supportati al massimo due operatori per messaggio dell'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 es. con collapse_key: "Updates Available") che possono essere compressi in modo che solo il ultimo messaggio venga inviato quando la pubblicazione viene ripresa. Lo scopo è evitare di inviare troppi messaggi uguali quando il dispositivo torna online o esce dalla modalità sospensione. Non è garantito l'ordine in cui i messaggi vengono inviati. Nota: in un determinato momento sono consentite al massimo 4 chiavi di collasso diverse. Ciò significa che FCM può memorizzare contemporaneamente 4 messaggi diversi per app client. Se superi questo numero, non è garantito quali 4 chiavi di collasso verranno conservate da FCM.
priority	Facoltativo, stringa	Imposta la priorità del messaggio. I valori validi sono "normale" e "alto". Sulle piattaforme Apple, queste corrispondono alle priorità APN 5 e 10. Per impostazione predefinita, i messaggi di notifica vengono inviati con priorità elevata e 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 l'invio immediato. Per i messaggi con priorità normale, l'app potrebbe riceverli con un ritardo non specificato. Quando un messaggio viene inviato con priorità elevata, viene inviato immediatamente e l'app può mostrare una notifica.
content_available	Facoltativo, booleano	Sulle piattaforme Apple, utilizza questo campo per rappresentare content-available nel payload APNs. Quando viene inviata una notifica o un messaggio e questo valore è impostato su true, viene risvegliata 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 recapitate e che possono dipendere da fattori quali l'attivazione della modalità a basso consumo da parte dell'utente, l'uscita forzata dall'app e così via. Su Android, i messaggi di dati riattivano l'app per impostazione predefinita. Su Chrome, non è attualmente supportato.
mutable_content	Facoltativo, booleano JSON	Sulle piattaforme Apple, utilizza questo campo per rappresentare mutable-content nel payload APNs. Quando viene inviata una notifica e questo valore è impostato su true, i contenuti della notifica possono essere modificati prima che vengano visualizzati utilizzando un' estensione dell'app Notification Service. Questo parametro verrà ignorato per Android e il web.
time_to_live	Facoltativo, numero	Questo parametro specifica per quanto tempo (in secondi) il messaggio deve essere conservato nello spazio di archiviazione FCM se il dispositivo è offline. La durata (TTL) massima supportata è di 4 settimane e il valore predefinito è 4 settimane. Per ulteriori informazioni, vedi Impostare la durata di un messaggio.
dry_run	Facoltativo, booleano	Se questo parametro viene impostato su true, consente agli sviluppatori di testare una richiesta senza inviare effettivamente un messaggio. Il valore predefinito è false.
Payload
data	Facoltativo, 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 inviato tramite APN, rappresenta i campi di dati personalizzati. Se viene fornito da FCM, viene rappresentato come un dizionario di valori chiave in AppDelegate application:didReceiveRemoteNotification:. Su Android, ne risulta un intent extra denominato score con il valore di stringa 3x1. La chiave non deve essere una parola riservata ("from", "message_type" o qualsiasi parola che inizi con "google" o "gcm"). Non utilizzare le parole definite in questa tabella (ad esempio collapse_key). Si consiglia di utilizzare valori di tipo stringa. Devi convertire i valori in oggetti o altri tipi di dati non di stringa (ad es. interi o booleani) in stringa.
notification	Facoltativo, oggetto	Questo parametro specifica le coppie chiave/valore predefinite visibili all'utente del payload della notifica. Per maggiori dettagli, consulta il supporto del payload della notifica. Per ulteriori informazioni sulle opzioni dei messaggi di notifica e dei messaggi di dati, consulta Tipi di messaggi. Se viene fornito un payload di notifica o se l'opzione content_available è impostata su true per un messaggio inviato a un dispositivo Apple, il messaggio viene inviato tramite APN, altrimenti viene inviato tramite FCM.

Supporto del payload delle notifiche

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

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

Parametro	Utilizzo	Descrizione
title	Facoltativo, stringa	Il titolo della notifica. Questo campo non è visibile su smartphone 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 bundle principale dell'app client o nella cartella Library/Sounds del contenitore di dati dell'app. Per scoprire di più, consulta la libreria degli sviluppatori iOS.
badge	Facoltativo, stringa	Il valore del badge sull'icona dell'app nella schermata Home. Se non viene specificato, il badge non viene modificato. Se impostato su 0, il badge viene rimosso.
click_action	Facoltativo, stringa	L'azione associata al clic di un utente sulla notifica. Corrisponde a category nel payload APN.
subtitle	Facoltativo, stringa	Il sottotitolo della notifica.
body_loc_key	Facoltativo, stringa	La chiave della stringa del corpo nelle risorse stringa dell'app da utilizzare per localizzare il testo del corpo in base alla localizzazione corrente dell'utente. Corrisponde a loc-key nel payload APN. Per ulteriori informazioni, consulta Riferimento alle chiavi del payload e Localizzazione dei contenuti delle notifiche remote.
body_loc_args	Facoltativo, array JSON come stringa	Valori di stringa variabili da utilizzare al posto degli specificatori di formato in body_loc_key da utilizzare per localizzare il testo del corpo in base alla localizzazione corrente dell'utente. Corrisponde a loc-args nel payload APN. Per ulteriori informazioni, consulta Riferimento alle chiavi del payload e Localizzazione dei contenuti delle notifiche remote.
title_loc_key	Facoltativo, stringa	La chiave della stringa del titolo nelle risorse stringa dell'app da utilizzare per localizzare il testo del titolo in base alla localizzazione corrente dell'utente. Corrisponde a title-loc-key nel payload APN. Per ulteriori informazioni, consulta Riferimento alle chiavi del payload e Localizzazione dei contenuti delle notifiche remote.
title_loc_args	Facoltativo, array JSON come stringa	Valori di stringa variabili da utilizzare al posto degli specificatori di formato in title_loc_key da utilizzare per localizzare il testo del titolo in base alla localizzazione corrente dell'utente. Corrisponde a title-loc-args nel payload APN. Per ulteriori informazioni, consulta Riferimento alle chiavi del payload e Localizzazione dei contenuti delle notifiche remote.

Tabella 2b. Android: chiavi 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 canale della notifica (novità di Android O). L'app deve creare un canale con questo ID prima che venga ricevuta una 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 file manifest dell'app.
icon	Facoltativo, stringa	L'icona della notifica. Imposta l'icona di notifica su myicon per la risorsa drawable myicon. Se non invii questa chiave nella richiesta, FCM mostra l'icona del programma di avvio specificata nel file 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 trovarsi in /res/raw/.
tag	Facoltativo, stringa	Identificatore utilizzato per sostituire le notifiche esistenti nel riquadro a scomparsa delle notifiche. Se non specificato, ogni richiesta crea una nuova notifica. Se specificato e se è già visualizzata una notifica con lo stesso tag, la nuova notifica sostituisce quella esistente nel riquadro delle notifiche.
color	Facoltativo, stringa	Il colore dell'icona della notifica, espresso in formato #rrggbb.
click_action	Facoltativo, stringa	L'azione associata al clic di un utente sulla notifica. Se specificato, un'attività con un filtro per intenzione corrispondente viene avviata quando un utente fa clic sulla notifica.
body_loc_key	Facoltativo, stringa	La chiave della stringa del corpo nelle risorse stringa dell'app da utilizzare per localizzare il testo del corpo in base alla localizzazione corrente dell'utente. Per saperne di più, consulta la sezione Risorse stringa.
body_loc_args	Facoltativo, array JSON come stringa	Valori di stringa variabili da utilizzare al posto degli specificatori di formato in body_loc_key da utilizzare per localizzare il testo del corpo in base alla localizzazione corrente dell'utente. Per ulteriori informazioni, consulta Formattazione e stili.
title_loc_key	Facoltativo, stringa	La chiave della stringa del titolo nelle risorse stringa dell'app da utilizzare per localizzare il testo del titolo in base alla localizzazione corrente dell'utente. Per saperne di più, consulta la sezione Risorse stringa.
title_loc_args	Facoltativo, array JSON come stringa	Valori di stringa variabili da utilizzare al posto degli specificatori di formato in title_loc_key da utilizzare per localizzare il testo del titolo in base alla localizzazione corrente dell'utente. Per ulteriori informazioni, consulta Formattazione e stili.

Tabella 2c. Web (JavaScript): chiavi 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 al clic di un utente sulla notifica. Per tutti i valori dell'URL, è obbligatorio HTTPS.

Interpreta una risposta al messaggio XMPP a valle

La tabella seguente elenca i campi visualizzati in una risposta al messaggio XMPP a valle.

Tabella 3 Corpo della risposta XMPP del messaggio a valle.

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 dell'app. Se il valore è impostato su nack, l'app server deve esaminare error e error_description per ottenere informazioni sull'errore.
error	Facoltativo, stringa	Questo parametro specifica un errore relativo al messaggio a valle. Viene impostato quando message_type è nack. Per informazioni dettagliate, consulta la tabella 4.
error_description	Facoltativo, stringa	Questo parametro fornisce informazioni descrittive sull'errore. Viene impostato quando message_type è nack.

Codici di risposta di errore dei messaggi a valle

La tabella seguente elenca i codici di risposta di errore per i messaggi a valle.

Tabella 4 Codici di risposta di errore dei messaggi a valle.

Errore	Codice XMPP	Azione consigliata
Token di registrazione mancante	INVALID_JSON	Verifica che la richiesta contenga un token di registrazione (in registration_id in un messaggio in testo normale o nel campo to o registration_ids in JSON).
Registrazione APN non valida	INVALID_JSON	Per le registrazioni iOS, verifica 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 ricevuto dall'app client dalla registrazione con FCM. Non troncare o aggiungere altri caratteri.
Dispositivo non registrato	DEVICE_UNREGISTERED	Un token di registrazione esistente potrebbe non essere più valido in una serie di scenari, tra cui: Se l'app client si annulla la registrazione con FCM. Se l'app client non è registrata automaticamente, il che può accadere se l'utente disinstalla l'applicazione. Ad esempio, su iOS, se APNs ha segnalato il token APNs 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 è aggiornata, ma la nuova versione non è configurata per ricevere messaggi. Per tutti questi casi, rimuovi questo token di registrazione dall'app server e smetti di utilizzarlo per inviare messaggi.
Mittente non corrispondente	SENDER_ID_MISMATCH	Un token di registrazione è associato a un determinato gruppo di mittenti. Quando un'app client si registra per FCM, deve specificare quali mittenti sono autorizzati a inviare messaggi. Devi utilizzare uno di questi ID mittente quando invii messaggi all'app client. Se passi a un altro mittente, i token di registrazione esistenti non funzioneranno.
JSON non valido	INVALID_JSON	Verifica che il messaggio JSON sia formattato correttamente e contenga campi validi (ad esempio, assicurati che venga passato il tipo di dati corretto).
Messaggio troppo grande	INVALID_JSON	Verifica che la dimensione totale dei dati del payload inclusi in un messaggio non superi i limiti di FCM: 4096 byte per la maggior parte dei messaggi o 2048 byte per i messaggi agli argomenti. Sono inclusi sia le chiavi sia i valori.
Chiave dei dati non valida	INVALID_JSON	Verifica che i dati del payload non contengano una chiave (ad esempio from, gcm o qualsiasi valore con prefisso google) utilizzata internamente da FCM. Tieni presente che alcune parole (ad esempio collapse_key) vengono utilizzate anche da FCM, ma sono consentite nel payload. In questo caso, il valore del payload viene sostituito dal valore FCM.
Durata non valida	INVALID_JSON	Verifica che il valore utilizzato in time_to_live sia un numero intero che rappresenti una durata in secondi compresa tra 0 e 2.419.200 (4 settimane).
Messaggio ACK errato	BAD_ACK	Verifica che il messaggio ack sia formattato correttamente prima di riprovare. Per informazioni dettagliate, consulta la tabella 6.
Timeout	SERVICE_UNAVAILABLE	Il server non è riuscito a elaborare la richiesta in tempo. Riprova a inviare la stessa richiesta, ma devi: Implementa il backoff esponenziale nel meccanismo di nuovo tentativo. 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, ritardali singolarmente di un'ulteriore quantità casuale per evitare di emettere una nuova richiesta per tutti i messaggi contemporaneamente. Il ritardo del primo tentativo deve essere impostato su 1 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 elaborazione della richiesta. Puoi riprovare la stessa richiesta seguendo i requisiti elencati in "Timeout" (vedi riga sopra).
Frequenza dei messaggi del dispositivo superata	DEVICE_MESSAGE_RATE _EXCEEDED	La frequenza dei messaggi inviati a un determinato dispositivo è troppo elevata. Riduci il numero di messaggi inviati a questo dispositivo e non riprovare immediatamente a inviare messaggi a questo dispositivo.
Frequenza dei messaggi degli argomenti superata	TOPICS_MESSAGE_RATE _EXCEEDED	La frequenza dei messaggi inviati agli iscritti a un determinato argomento è troppo elevata. Riduci il numero di messaggi inviati per questo argomento e non riprovare immediatamente a inviare.
Svuotamento della connessione	CONNECTION_DRAINING	Impossibile elaborare il messaggio perché la connessione sta esaurendo la batteria. Questo accade perché, periodicamente, FCM deve chiudere una connessione per eseguire il bilanciamento del carico. Riprova a inviare il messaggio tramite un'altra connessione XMPP.
Credenziali APN non valide	INVALID_APNS_CREDENTIAL	Non è stato possibile inviare un messaggio indirizzato a un dispositivo iOS perché la chiave di autenticazione APN obbligatoria non è stata caricata o è scaduta. Verifica la validità delle credenziali di sviluppo e produzione.
Autenticazione non riuscita	AUTHENTICATION_FAILED	Impossibile eseguire l'autenticazione con i servizi push esterni. Verifica di utilizzare i certificati push web corretti.

Sintassi dei messaggi upstream

Un messaggio in upstream è un messaggio inviato dall'app client al server dell'app. Al momento solo XMPP supporta la messaggistica upstream. Per ulteriori informazioni sull'invio di messaggi dalle app client, consulta la documentazione della tua piattaforma.

Interpretazione di un messaggio XMPP a monte

La seguente tabella descrive i campi della stanza XMPP generata da FCM in risposta alle richieste di messaggi a monte da parte delle app 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 dell'app 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 seguente tabella descrive la risposta ACK che il server dell'app deve inviare a FCM in risposta a un messaggio upstream ricevuto dal server dell'app.

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 a monte.
message_id	Obbligatorio, stringa	Questo parametro specifica il messaggio a cui è destinata la risposta. Il valore deve essere il valore message_id del messaggio a monte corrispondente.
message_type	Obbligatorio, stringa	Questo parametro specifica un messaggio ack da un server app a CCS. Per i messaggi in upstream, deve essere sempre impostato su ack.

FCM messaggi del server (XMPP)

Questo è un messaggio inviato da FCM a un server di app. Di seguito sono riportati i tipi principali di messaggi inviati da FCM al server dell'app:

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

La seguente tabella descrive i campi inclusi nei messaggi inviati da CCS a un server app.

Tabella 7 FCM Messaggi di controllo (XMPP).

Parametro	Utilizzo	Descrizione
Campo comune
message_type	Obbligatorio, stringa	Questo parametro specifica il tipo di messaggio: controllo. Se è 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. Al momento è supportato solo CONNECTION_DRAINING. FCM invia questo messaggio di controllo prima di chiudere una connessione per eseguire il bilanciamento del carico. Quando la connessione si esaurisce, non è più consentito inviare messaggi alla connessione, ma i messaggi esistenti nella pipeline continuano a essere elaborati.