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 disponibili e 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)

Nella tabella seguente sono elencati i target, le opzioni e il payload per il file JSON XMPP. messaggi.

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" negli argomenti". 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 presente 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 possiamo garantire l'ordine di invio dei messaggi. Nota: in un determinato momento sono consentite al massimo 4 chiavi di collasso diverse. Ciò significa FCM può memorizzare contemporaneamente 4 diversi i messaggi per app client. Se superare questo numero, non c'è garanzia di quali 4 chiavi di compressione FCM verranno conservati.
priority	Facoltativo, stringa	Imposta la priorità del messaggio. I valori validi sono "normali" e "alta". Sulle piattaforme Apple, corrispondono alle priorità 5 e 10 dell'APN. 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 rendimento consumo eccessivo della batteria e deve essere utilizzata a meno che non sia necessaria 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à elevata, viene inviato immediatamente e l'app può visualizzare una notifica.
content_available	Facoltativo, booleano	Sulle piattaforme Apple, utilizza questo campo per rappresentare content-available negli APN il payload. 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, valore JSON booleano	Sulle piattaforme Apple, usa questo campo per rappresentare mutable-content nel payload del servizio APN. 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	Numero facoltativo	Questo parametro specifica per quanto tempo (in secondi) il messaggio deve essere conservato nello spazio di archiviazione FCM se il dispositivo è offline. La durata massima supportata è di 4 settimane e il valore predefinito è 4 settimane. Per ulteriori informazioni, vedi Impostare la durata di un messaggio.
dry_run	Valore booleano facoltativo	Se impostato su true, questo parametro consente agli sviluppatori di testare un senza inviare effettivamente un messaggio. Il valore predefinito è false.
Payload
data	Oggetto facoltativo	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 consegnato da FCM, è rappresentato come un dizionario chiave-valore in AppDelegate application:didReceiveRemoteNotification:. Su Android, ne risulta un extra intent denominato score con il valore di stringa 3x1. La chiave non deve essere una parola riservata ("from", "message_type" o qualsiasi parola che inizia 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 in altri tipi di dati non stringa. (ad es. numeri interi o booleani) a stringhe.
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 relative ai messaggi di notifica e ai messaggi di dati, vedi 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 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 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 specificato, il badge rimane invariato. Se impostato su 0, il badge viene rimosso.
click_action	Facoltativo, stringa	L'azione associata a un utente fa clic 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 del servizio 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 indicatori di formato in body_loc_key da utilizzare per localizzare il corpo del testo nell' localizzazione attuale dell'utente. Corrisponde a loc-args nel payload del servizio 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 di stringa dell'app da utilizzare per localizzare il testo del titolo in base alla posizione attuale 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. Consulta: Riferimento chiave di payload e Localizzazione dei contenuti delle notifiche remote per saperne di più informazioni.

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 canale della notifica (novità di Android O). L'app deve creare un canale con questo ID canale prima che qualsiasi notifica con questo ID canale venga ricevuto. Se non invii questo ID canale nella richiesta o se l'ID canale fornito non è stato ancora creato dall'app, FCM usa 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 in bundle nell'app. I file audio devono risiedere in /res/raw/.
tag	Facoltativo, stringa	Identificatore utilizzato per sostituire le notifiche esistenti nella notifica riquadro a scomparsa. 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 a un utente fa clic sulla notifica. Se specificata, viene avviata un'attività con un filtro per intent corrispondente 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. Consulta: Risorse stringa per ulteriori informazioni.
body_loc_args	Facoltativo, array JSON come stringa	Valori di stringa variabili da utilizzare al posto degli indicatori di formato in body_loc_key da utilizzare per localizzare il corpo del testo nell' localizzazione attuale dell'utente. Consulta: Formattazione e stile per ulteriori informazioni.
title_loc_key	Facoltativo, stringa	La chiave della stringa del titolo nelle risorse di stringa dell'app da utilizzare per localizzare il testo del titolo in base alla posizione attuale 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. Il protocollo HTTPS è obbligatorio per tutti i valori degli URL.

Interpretare una risposta di messaggi XMPP downstream

Nella tabella seguente sono elencati i campi che vengono visualizzati in una risposta di 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 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 downstream. 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 downstream

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

Tabella 4 Codici di risposta di errore dei messaggi downstream.

Errore	Codice XMPP	Azione consigliata
Token di registrazione mancante	INVALID_JSON	Verifica che la richiesta contenga un token di registrazione (nel registration_id in un messaggio di testo normale o nel to o registration_ids in JSON).
Registrazione del servizio APN non valida	INVALID_JSON	Per le registrazioni iOS, controlla che la richiesta di registrazione inviata dal client contenga un un token del servizio APN e un ID applicazione validi.
Token di registrazione non valido	BAD_REGISTRATION	Verifica 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. Azioni sconsigliate troncare o aggiungere altri caratteri.
Dispositivo non registrato	DEVICE_UNREGISTERED	Un token di registrazione esistente potrebbe non essere più valido in diversi scenari, tra cui: Se l'app client si annulla la registrazione con FCM. Se la registrazione dell'app client viene annullata automaticamente, può succedere se l'utente disinstalla l'applicazione. Ad esempio, su iOS, se gli APN ha segnalato il token del servizio 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 è aggiornata, ma la nuova versione non è configurata per ricevere messaggi. In tutti questi casi, rimuovi il token di registrazione dall'app server web e smettere di utilizzarlo per inviare messaggi.
Mittente non corrispondente	SENDER_ID_MISMATCH	Un token di registrazione è collegato a un determinato gruppo di mittenti. Quando un'app client viene registrata per FCM, deve specificare i mittenti 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 le chiavi e i valori.
Chiave dati non valida	INVALID_JSON	Verifica che i dati del payload non contengano una chiave (ad esempio, from, gcm o qualsiasi valore prefisso da google) utilizzato internamente da FCM. Tieni presente che alcune parole (ad esempio collapse_key) vengono utilizzati anche da FCM ma sono consentiti nel payload, nel qual 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 rappresenta un 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. Consulta: tabella 6 per maggiori dettagli.
Timeout	SERVICE_UNAVAILABLE	Il server non è riuscito a elaborare la richiesta in tempo. Riprova a eseguire la stessa richiesta, ma devi: Implementa il backoff esponenziale nel meccanismo di nuovo tentativo. (ad es. se hai aspettato un secondo prima del primo tentativo, attendi almeno due secondi prima di quello 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 server interno	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).
Percentuale di messaggi sul dispositivo superata	DEVICE_MESSAGE_RATE _EXCEEDED	La frequenza di messaggi inviati a un determinato dispositivo è troppo elevata. Riduci numero di messaggi inviati a questo dispositivo e non riprovare immediatamente a inviare a questo dispositivo.
Percentuale di messaggi degli argomenti superata	TOPICS_MESSAGE_RATE _EXCEEDED	La percentuale di messaggi inviati ai sottoscrittori di 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 un'altra connessione XMPP.
Credenziali del servizio APN non valide	INVALID_APNS_CREDENTIAL	Impossibile inviare un messaggio indirizzato a un dispositivo iOS perché gli APN richiesti la chiave di autenticazione non è stata caricata o è scaduta. Verificare la validità del tuo sviluppo e credenziali di 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 upstream è un messaggio che l'app client invia al server delle app. Attualmente solo XMPP supporta la messaggistica upstream. Consulta: la documentazione per la tua piattaforma informazioni sull'invio di messaggi dalle app client.

Interpretazione di un messaggio XMPP upstream

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'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 tabella seguente descrive la risposta ACK a cui si prevede di inviare l'app server FCM in risposta a un il messaggio upstream ricevuto dal server di 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 upstream.
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 di app a CCS. Per i messaggi 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 Messaggi di controllo FCM (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.