Questo documento fornisce un riferimento per la sintassi HTTP utilizzata per passare i messaggi dal server delle app alle app client tramite Firebase Cloud Messaging.
Se utilizzi il protocollo HTTP legacy, il server dell'app deve indirizzare tutte le richieste HTTP a questo endpoint:
https://fcm.googleapis.com/fcm/send
I parametri e le opzioni disponibili rientrano nelle seguenti grandi categorie:
Sintassi dei messaggi 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)
Nella tabella seguente sono elencati i target, le opzioni e il payload per i messaggi JSON HTTP.
Parametro | Utilizzo | Descrizione | |
---|---|---|---|
Obiettivi | |||
to |
Facoltativo, stringa |
Questo parametro specifica il destinatario di un messaggio.
Il valore può essere un token di registrazione di un dispositivo, la chiave di notifica di un gruppo di dispositivi o un singolo argomento (con prefisso |
|
registration_ids | Array di stringhe facoltativo |
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 da 1 a 1000 token di registrazione. Per inviare un messaggio a un singolo dispositivo, utilizza il
parametro I messaggi multicast sono consentiti solo utilizzando il formato JSON HTTP. |
|
condition |
Facoltativo, stringa | Questo parametro specifica un'espressione logica di condizioni che determinano la destinazione del messaggio. Condizione supportata: argomento, con formato "yourTopic" negli argomenti. Questo valore non fa distinzione tra maiuscole e minuscole. Operatori supportati: |
|
notification_key Deprecato |
Facoltativo, stringa | Questo parametro è obsoleto. Utilizza invece |
|
Opzioni | |||
collapse_key |
Facoltativo, stringa | Questo parametro identifica un gruppo di messaggi (ad esempio, con Tieni presente che non vi è alcuna garanzia in merito all'ordine con cui i messaggi vengono inviati. Nota: sono consentite massimo quattro diverse chiavi di compressione alla volta. Ciò significa che FCM può archiviare contemporaneamente quattro messaggi diversi per app client. Se superi questo numero, non è possibile garantire quali quattro chiavi di compressione verranno conservate da FCM. |
|
priority |
Facoltativo, stringa | Imposta la priorità del messaggio. I valori validi sono "normal" e "high". Sulle piattaforme Apple, corrispondono alle priorità 5 e 10 dell'APN. Per impostazione predefinita, i messaggi di notifica vengono inviati con priorità elevata, 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 riceverli 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 |
|
mutable_content |
Facoltativo, JSON booleano | 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 nello spazio di archiviazione FCM se il dispositivo è offline. La durata massima supportata è di 4 settimane, mentre il valore predefinito è 4 settimane. Per ulteriori informazioni, consulta Impostazione della durata di un messaggio. |
|
restricted_package_
(solo Android) |
Facoltativo, stringa | Questo parametro specifica il nome del pacchetto dell'applicazione in cui i token di registrazione devono corrispondere per ricevere il messaggio. | |
dry_run |
Facoltativo, booleano | Se impostato su Il valore predefinito è |
|
Carico | |||
data |
Facoltativo, 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 di dati personalizzati. Se viene inviato tramite FCM, viene rappresentato come dizionario dei valori chiave in Su Android, ciò comporterebbe un intent extra denominato La chiave non deve essere una parola riservata ("from", "message_type" o una parola che inizia con "google" o "gcm"). Non utilizzare nessuna delle parole definite in questa tabella (ad esempio Si consigliano i valori nei tipi di stringhe. Devi convertire i valori negli oggetti o in altri tipi di dati non stringa (ad es. numeri interi o booleani) in stringa. |
|
notification |
Facoltativo, oggetto | Questo parametro specifica le coppie chiave-valore predefinite e visibili all'utente del
payload di notifica. Per maggiori dettagli, vedi Supporto payload delle notifiche.
Per saperne di più sulle opzioni relative ai messaggi di notifica e ai 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 a un dispositivo Apple, il messaggio viene inviato tramite APN, altrimenti viene inviato tramite FCM.
|
Supporto payload delle notifiche
Le seguenti tabelle 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 bundle principale dell'app client o nella cartella |
badge |
Facoltativo, stringa |
Il valore del badge sull'icona dell'app nella schermata Home. Se non specificato, il badge non viene modificato.
Se impostato su |
click_action |
Facoltativo, stringa |
L'azione associata a un utente che fa clic sulla notifica.
Corrisponde a |
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 corpo del testo nell'attuale localizzazione dell'utente.
Corrisponde a Per saperne di più, consulta Riferimento per le chiavi payload e Localizzare i contenuti delle notifiche remote. |
body_loc_args |
Array JSON facoltativo come stringa |
Valori di stringa delle variabili da utilizzare al posto degli identificatori di formato in
Corrisponde a Per saperne di più, consulta Riferimento per le chiavi payload e Localizzare i 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 nell'attuale localizzazione dell'utente.
Corrisponde a Per saperne di più, consulta Riferimento per le chiavi payload e Localizzare i contenuti delle notifiche remote. |
title_loc_args |
Array JSON facoltativo come stringa |
Valori di stringa delle variabili da utilizzare al posto degli identificatori di formato in
Corrisponde a Per saperne di più, consulta Riferimento per le chiavi payload e Localizzare i contenuti 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 canale della notifica (novità di Android O). L'app deve creare un canale con questo ID canale prima di ricevere 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 file 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 riquadro a scomparsa delle notifiche. Se non specificato, ogni richiesta crea una nuova notifica. Se specificata e una notifica con lo stesso tag viene già mostrata, la nuova notifica sostituisce quella esistente nel riquadro a scomparsa delle notifiche. |
color |
Facoltativo, stringa |
Il colore dell'icona della notifica, espresso nel formato |
click_action |
Facoltativo, stringa |
L'azione associata a un utente che fa clic sulla notifica. Se specificato, 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 corpo del testo nell'attuale localizzazione dell'utente. Per ulteriori informazioni, consulta le risorse per le stringhe. |
body_loc_args |
Array JSON facoltativo come stringa |
Valori di stringa delle variabili da utilizzare al posto degli identificatori di formato in
Per ulteriori informazioni, consulta la sezione 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 nell'attuale localizzazione dell'utente. Per ulteriori informazioni, consulta le risorse per le stringhe. |
title_loc_args |
Array JSON facoltativo come stringa |
Valori di stringa delle variabili da utilizzare al posto degli identificatori di formato in
Per ulteriori informazioni, consulta la sezione Formattazione e stili. |
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 utente che fa clic sulla notifica. Per tutti i valori degli URL, HTTPS è obbligatorio. |
Messaggi HTTP downstream (testo normale)
La seguente tabella elenca la sintassi per target, opzioni e payload in 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ù di un token di registrazione) è consentita solo utilizzando il formato JSON HTTP. |
Opzioni | ||
collapse_key |
Facoltativo, stringa | Per ulteriori dettagli, consulta la tabella 1. |
time_to_live |
Facoltativo, numero | Per ulteriori dettagli, consulta la tabella 1. |
restricted_package_name |
Facoltativo, stringa | Per ulteriori dettagli, consulta la tabella 1. |
dry_run |
Facoltativo, booleano | Per ulteriori dettagli, consulta la tabella 1. |
Carico | ||
data.<key> |
Facoltativo, stringa | Questo parametro specifica le coppie chiave-valore del payload del messaggio. Non esiste un limite al numero di parametri chiave-valore, ma esiste un limite per le dimensioni totali dei messaggi di 4096 byte. Ad esempio, in Android, La chiave non deve essere una parola riservata ("from", "message_type" o una parola che inizia con "google" o "gcm"). Non utilizzare nessuna delle parole definite in questa tabella (ad esempio |
Interpretazione di una risposta a un messaggio downstream
Il server dell'app deve valutare sia l'intestazione della risposta al messaggio sia il corpo per interpretare la risposta al messaggio inviata da FCM. La seguente tabella descrive le possibili risposte.
Risposta | Descrizione |
---|---|
200 | Il messaggio è stato elaborato correttamente. Il corpo della risposta conterrà ulteriori dettagli sullo stato del messaggio, ma il suo formato dipenderà dal fatto che la richiesta fosse JSON o testo normale. Per ulteriori dettagli, consulta la tabella 5. |
400 | Si applica solo alle richieste JSON. Indica che non è stato possibile analizzare la richiesta come JSON oppure che conteneva campi non validi (ad esempio, passando una stringa in cui 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 compresi nell'intervallo 500-599 (ad esempio 500 o 503) indicano che si è verificato un errore interno nel backend FCM durante il tentativo di elaborazione della richiesta o che il server è temporaneamente non disponibile (ad esempio a causa di timeout). Il mittente deve riprovare più tardi, rispettando l'intestazione Retry-After inclusa nella risposta. I server delle applicazioni devono implementare il backoff esponenziale. |
La seguente tabella elenca i campi in un corpo di risposta del messaggio downstream (JSON).
Parametro | Utilizzo | Descrizione |
---|---|---|
multicast_id |
Obbligatorio, numero | ID (numero) univoco 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 |
Array obbligatorio di oggetti | Array di oggetti che rappresenta lo stato dei messaggi elaborati. Gli oggetti vengono elencati nello stesso ordine della richiesta (ad esempio, per ogni ID registrazione nella richiesta, il risultato viene elencato nello stesso indice nella risposta).
|
Parametro | Utilizzo | Descrizione |
---|---|---|
message_id |
Facoltativo, numero | L'ID messaggio dell'argomento quando FCM ha ricevuto correttamente la richiesta e tenterà di recapitarla a tutti i dispositivi in abbonamento. |
error |
Facoltativo, stringa | Errore che si è verificato durante l'elaborazione del messaggio. I valori possibili sono riportati nella tabella 9. |
Parametro | Utilizzo | Descrizione |
---|---|---|
id |
Obbligatorio, stringa | Questo parametro specifica l'ID messaggio univoco FCM 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 di errore durante l'elaborazione del messaggio per il destinatario. Per informazioni dettagliate, consulta la tabella 9. |
Codici di risposta di errore dei messaggi downstream
Nella tabella seguente sono elencati i codici di risposta di errore per i messaggi downstream.
Errore | Codice HTTP | Azione consigliata |
---|---|---|
Token di registrazione mancante | 200 + errore:Registrazione mancante | Verifica che la richiesta contenga un token di registrazione (in registration_id in un messaggio di testo normale o nel campo to o registration_ids in JSON). |
Token di registrazione non valido | 200 + errore:Registrazione non valida | Verifica 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 e non aggiungere altri caratteri. |
Dispositivo non registrato | 200 + errore:Non registrato | Un token di registrazione esistente può non essere più valido in diversi casi, tra cui:
|
Nome del pacchetto non valido | 200 + errore:InvalidPackageName | Assicurati che il messaggio sia stato indirizzato a un token di registrazione il cui nome del pacchetto corrisponde al valore trasmesso 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 è associato a un determinato gruppo di mittenti. Quando un'app client si registra per FCM, deve specificare a quali mittenti è consentito inviare messaggi. Devi 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 | Verifica che il messaggio JSON sia formattato correttamente e contenga campi validi (ad esempio, assicurandoti che venga trasmesso il tipo di dati corretto). |
Parametri non validi | 400 + error:InvalidParameters | Verifica che il nome e il tipo dei parametri forniti siano corretti. |
Messaggio troppo grande | 200 + errore:MessageTooBig | Verifica 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 per i messaggi indirizzati agli argomenti. Sono incluse sia le chiavi che i valori. |
Chiave dati non valida | 200 + errore:
InvalidDataKey |
Verifica che i dati del payload non contengano una chiave (come from ,
o gcm , o qualsiasi valore preceduto da google ) utilizzata internamente da FCM. Tieni presente che alcune parole (come collapse_key )
vengono utilizzate da FCM, ma sono consentite nel payload, nel qual caso
il valore del payload verrà sostituito dal valore FCM. |
Durata non valida | 200 + errore:Ttl non valido | 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). |
Timeout | 5xx o 200 + errore:non disponibile | Il server non è riuscito a elaborare la richiesta in tempo. Riprova a effettuare la stessa richiesta, ma devi:
I mittenti che causano problemi rischiano di essere inseriti nella blacklist. |
Errore interno del server | 500 o 200 + errore:InternalServerError | Il server ha riscontrato un errore durante il tentativo di elaborare la richiesta. Puoi riprovare a eseguire la stessa richiesta seguendo i requisiti elencati in "Timeout" (vedi la riga sopra). Se l'errore persiste, contatta l'assistenza Firebase. |
Frequenza di messaggi del dispositivo superata | Più di 200 errore:
DeviceMessageRate Superata |
La frequenza dei messaggi inviati a un determinato dispositivo è troppo alta. Se un'app Apple invia messaggi a una velocità che supera i limiti del servizio APN, potrebbe ricevere questo messaggio di errore Riduci il numero di messaggi inviati a questo dispositivo e utilizza il backoff esponenziale per riprovare a inviare. |
Frequenza dei messaggi degli argomenti superata | 200 + errore:
TopicsMessageRate Superata |
La percentuale di messaggi per i sottoscrittori di un determinato argomento è troppo alta. Riduci il numero di messaggi inviati per questo argomento e utilizza il backoff esponenziale per riprovare a inviare. |
Credenziali del servizio APN non valide | 200 + errore:
InvalidApnsCredential |
Impossibile inviare un messaggio indirizzato a un dispositivo Apple perché la chiave di autenticazione del servizio APN richiesta non è stata caricata o è scaduta. Verifica la validità delle tue credenziali di sviluppo e di produzione. |
Gestione dei gruppi 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 (tranne per l'operazione create , la stringa |
Identificatore univoco del gruppo di dispositivi. Questo valore viene restituito nella risposta di un'operazione create riuscita ed è obbligatorio per tutte le operazioni successive sul gruppo di dispositivi. |
registration_ids |
Array di stringhe obbligatorio | 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. |