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
- Codici di risposta agli errori dei messaggi downstream
- Sintassi del messaggio upstream
- Messaggi di controllo FCM
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.
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 | |
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: | |
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 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 | |
mutable_content | Facoltativo, valore booleano JSON | Sulle piattaforme Apple, utilizza questo campo per rappresentare | |
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 Il valore predefinito è | |
Carico utile | |||
data | Opzionale, oggetto | Questo parametro specifica le coppie chiave-valore del payload del messaggio. Ad esempio, con 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 Su Android, ciò si traduce in un 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 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.
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 |
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 |
click_action | Facoltativo, stringa | L'azione associata a un clic dell'utente sulla notifica. Corrisponde alla |
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 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 Corrisponde a 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 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 Corrisponde a Per ulteriori informazioni, consulta Riferimento alla chiave del payload e Localizzazione del contenuto delle notifiche remote . |
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 |
sound | Facoltativo, stringa | Il suono da riprodurre quando il dispositivo riceve la notifica. Supporta |
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 |
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 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 Per ulteriori informazioni, vedere Formattazione e stile . |
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.
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 Se il valore è impostato su |
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.
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:
|
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:
Nota: i mittenti che causano problemi rischiano di essere inseriti nella lista nera. |
Errore interno del server | INTERNAL_SERVER_ | 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 | 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 | 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.
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.
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.
Parametro | Utilizzo | Descrizione |
---|---|---|
Campo comune | ||
message_type | Obbligatorio, stringa | Questo parametro specifica il tipo di messaggio: controllo. Quando è impostato su |
control_type | Facoltativo, stringa | Questo parametro specifica il tipo di messaggio di controllo inviato da FCM. Attualmente è supportato solo |