Questo documento fornisce un riferimento per la sintassi HTTP utilizzata per passare messaggi dal server delle applicazioni alle app client tramite Firebase Cloud Messaging.
Quando utilizzi il protocollo HTTP legacy, il server delle applicazioni deve indirizzare tutte le richieste HTTP a questo endpoint:
https://fcm.googleapis.com/fcm/send
I parametri e le opzioni disponibili rientrano nelle seguenti ampie categorie:
Sintassi del messaggio downstream
Questa sezione fornisce la sintassi per l'invio di messaggi downstream e l'interpretazione delle risposte HTTP da Firebase Cloud Messaging.
Messaggi HTTP downstream (JSON)
La tabella seguente elenca le destinazioni, le opzioni e il payload per i messaggi HTTP JSON.
Parametro | Utilizzo | Descrizione | |
---|---|---|---|
Obiettivi | |||
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 | |
registration_ids | Facoltativo, array di stringhe | Questo parametro specifica il destinatario di un messaggio multicast, un messaggio inviato a più di un token di registrazione. Il valore deve essere un array di token di registrazione a cui inviare il messaggio multicast. L'array deve contenere almeno 1 e al massimo 1000 token di registrazione. Per inviare un messaggio a un singolo dispositivo, utilizzare il parametro I messaggi multicast sono consentiti solo utilizzando il formato HTTP JSON. | |
condition | Facoltativo, stringa | Questo parametro specifica un'espressione logica di condizioni che determinano la destinazione del messaggio. Condizione supportata: argomento, formattato come "'yourTopic' negli argomenti". Questo valore non fa distinzione tra maiuscole e minuscole. Operatori supportati: | |
notification_key Deprecato | Facoltativo, stringa | Questo parametro è deprecato. Utilizzare invece | |
Opzioni | |||
collapse_key | Facoltativo, stringa | Questo parametro identifica un gruppo di messaggi (ad esempio, con Tieni presente che 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 . | |
restricted_package_ (solo Android) | Facoltativo, stringa | Questo parametro specifica il nome del pacchetto dell'applicazione a cui devono corrispondere i token di registrazione per ricevere il 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 personalizzate del payload del messaggio. Ad esempio, con Sulle piattaforme Apple, se il messaggio viene inviato tramite APN, rappresenta i campi dati personalizzati. Se viene inviato tramite FCM, verrebbe rappresentato come dizionario dei valori chiave nell'applicazione Su Android, ciò comporterebbe 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 iOS 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. |
Messaggi HTTP downstream (testo normale)
La tabella seguente elenca la sintassi per destinazioni, opzioni e payload nei messaggi HTTP downstream in testo normale.
Parametro | Utilizzo | Descrizione |
---|---|---|
Obiettivi | ||
registration_id | Obbligatorio, stringa | Questo parametro specifica le app client (token di registrazione) che ricevono il messaggio. La messaggistica multicast (invio a più token di registrazione) è consentita solo utilizzando il formato HTTP JSON. |
Opzioni | ||
collapse_key | Facoltativo, stringa | Vedere la tabella 1 per i dettagli. |
time_to_live | Facoltativo, numero | Vedere la tabella 1 per i dettagli. |
restricted_package_name | Facoltativo, stringa | Vedere la tabella 1 per i dettagli. |
dry_run | Facoltativo, booleano | Vedere la tabella 1 per i dettagli. |
Carico utile | ||
data.<key> | Facoltativo, stringa | Questo parametro specifica le coppie chiave-valore del payload del messaggio. Non esiste alcun limite al numero di parametri del valore-chiave, ma esiste un limite alla dimensione totale del messaggio di 4000 byte. Ad esempio, in Android, 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 |
Interpretazione di una risposta al messaggio downstream
Il server delle applicazioni deve valutare sia l'intestazione che il corpo della risposta al messaggio per interpretare la risposta al messaggio inviata da FCM. La tabella seguente descrive le possibili risposte.
Risposta | Descrizione |
---|---|
200 | Il messaggio è stato elaborato correttamente. Il corpo della risposta conterrà maggiori dettagli sullo stato del messaggio, ma il suo formato dipenderà dal fatto che la richiesta fosse JSON o testo semplice. Vedere la tabella 5 per maggiori dettagli. |
400 | Si applica solo alle richieste JSON. Indica che non è stato possibile analizzare la richiesta come JSON o che conteneva campi non validi (ad esempio, passaggio di una stringa dove era previsto un numero). Il motivo esatto dell'errore è descritto nella risposta e il problema deve essere risolto prima di poter ritentare la richiesta. |
401 | Si è verificato un errore durante l'autenticazione dell'account del mittente. |
5xx | Gli errori nell'intervallo 500-599 (come 500 o 503) indicano che si è verificato un errore interno nel backend FCM durante il tentativo di elaborare la richiesta o che il server è temporaneamente non disponibile (ad esempio, a causa di timeout). Il mittente deve riprovare più tardi, rispettando qualsiasi intestazione Retry-After inclusa nella risposta. I server delle applicazioni devono implementare il backoff esponenziale. |
La tabella seguente elenca i campi nel corpo della risposta al messaggio downstream (JSON).
Parametro | Utilizzo | Descrizione |
---|---|---|
multicast_id | Obbligatorio, numero | ID univoco (numero) che identifica il messaggio multicast. |
success | Obbligatorio, numero | Numero di messaggi elaborati senza errori. |
failure | Obbligatorio, numero | Numero di messaggi che non è stato possibile elaborare. |
results | Obbligatorio, array di oggetti | Matrice di oggetti che rappresentano lo stato dei messaggi elaborati. Gli oggetti sono elencati nello stesso ordine della richiesta (vale a dire, per ciascun ID di registrazione nella richiesta, il suo risultato è elencato nello stesso indice nella risposta).
|
Parametro | Utilizzo | Descrizione |
---|---|---|
message_id | Facoltativo, numero | L'ID del messaggio dell'argomento quando FCM ha ricevuto correttamente la richiesta e tenterà di consegnarla a tutti i dispositivi sottoscritti. |
error | Facoltativo, stringa | Errore che si è verificato durante l'elaborazione del messaggio. I possibili valori si trovano nella tabella 9 . |
Parametro | Utilizzo | Descrizione |
---|---|---|
id | Obbligatorio, stringa | Questo parametro specifica l'ID messaggio univoco che FCM ha elaborato correttamente. |
registration_id | Facoltativo, stringa | Questo parametro specifica il token di registrazione per l'app client a cui è stato elaborato e inviato il messaggio. |
Parametro | Utilizzo | Descrizione |
---|---|---|
Error | Obbligatorio, stringa | Questo parametro specifica il valore dell'errore durante l'elaborazione del messaggio per il destinatario. Vedere la tabella 9 per i dettagli. |
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 HTTP | Azione raccomandata |
---|---|---|
Token di registrazione mancante | 200 + errore: registrazione mancante | 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). |
Token di registrazione non valido | 200 + errore: registrazione non valida | 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 Firebase Notifications. Non troncare né aggiungere ulteriori caratteri. |
Dispositivo non registrato | 200 + errore: Non registrato | Un token di registrazione esistente può cessare di essere valido in una serie di scenari, tra cui:
|
Nome pacchetto non valido | 200 + errore: nome pacchetto non valido | Assicurati che il messaggio sia indirizzato a un token di registrazione il cui nome di pacchetto corrisponda al valore passato nella richiesta. |
Errore di autenticazione | 401 | Non è stato possibile autenticare l'account del mittente utilizzato per inviare un messaggio. Le possibili cause sono:
|
Mittente non corrispondente | 200 + errore: MismatchSenderId | 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 | 400 | Controlla che il messaggio JSON sia formattato correttamente e contenga campi validi (ad esempio, assicurandoti che venga passato il tipo di dati corretto). |
Parametri non validi | 400 + errore: parametri non validi | Verificare che i parametri forniti abbiano il nome e il tipo corretti. |
Messaggio troppo grande | 200 + errore:MessageTooBig | 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 | 200 + errore: Chiave dati non valida | Controlla che i dati del payload non contengano una chiave (come from , o 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 verrà sovrascritto dal valore FCM. |
Tempo di vita non valido | 200 + errore:InvalidTtl | 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). |
Tempo scaduto | Errore 5xx o 200 +: non disponibile | Il server non è riuscito a elaborare la richiesta in tempo. Riprovare la stessa richiesta, ma è necessario:
I mittenti che causano problemi rischiano di essere inseriti nella lista nera. |
Errore interno del server | 500 o 200 + errore: InternalServerError | 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). Se l'errore persiste, contatta l'assistenza Firebase . |
Velocità messaggi dispositivo superata | 200 + errore: DispositivoMessageRate Superato | La frequenza dei messaggi inviati a un particolare dispositivo è troppo elevata. Se un'app Apple invia messaggi a una velocità superiore ai limiti APN, potrebbe ricevere questo messaggio di errore Riduci il numero di messaggi inviati a questo dispositivo e utilizza il backoff esponenziale per ritentare l'invio. |
La frequenza dei messaggi sugli argomenti è stata superata | 200 + errore: ArgomentiMessageRate Superato | La frequenza dei messaggi agli abbonati a un particolare argomento è troppo alta. Riduci il numero di messaggi inviati per questo argomento e utilizza il backoff esponenziale per ritentare l'invio. |
Credenziali APN non valide | 200 + errore: CredenzialeApns non valida | Non è stato possibile inviare un messaggio destinato a un dispositivo Apple perché la chiave di autenticazione APN richiesta non è stata caricata o è scaduta. Verifica la validità delle tue credenziali di sviluppo e produzione. |
Gestione del gruppo di dispositivi
Nella tabella seguente sono elencate le chiavi per creare gruppi di dispositivi e aggiungere e rimuovere membri. Per ulteriori informazioni, consulta la guida per la tua piattaforma, iOS+ o Android .
Parametro | Utilizzo | Descrizione |
---|---|---|
operation | Obbligatorio, stringa | L'operazione da eseguire. I valori validi sono create , add e remove . |
notification_key_name | Obbligatorio, stringa | Il nome definito dall'utente del gruppo di dispositivi da creare o modificare. |
notification_key | Obbligatorio (ad eccezione dell'operazione create , string | Identificatore univoco del gruppo di dispositivi. Questo valore viene restituito nella risposta per un'operazione create riuscita ed è richiesto per tutte le operazioni successive sul gruppo di dispositivi. |
registration_ids | Obbligatorio, array di stringhe | I token del dispositivo da aggiungere o rimuovere. Se rimuovi tutti i token di registrazione esistenti da un gruppo di dispositivi, FCM elimina il gruppo di dispositivi. |