Tipi di notifica e struttura del payload

Le notifiche push inviate tramite firebase push connector possono essere strutturate in due modalità principali:

• Notification + Data (standard)

• Data-only

La scelta del tipo di notifica influenza il comportamento dell’app client, le modalità di visualizzazione e le logiche di tracciamento implementate in firebase.
Questa sezione spiega le differenze, la struttura del payload e le buone pratiche di configurazione.

1. Tipologie di messaggio

Notification + Data (default)

In questa modalità, il messaggio contiene due sezioni:

• notification: i contenuti mostrati al dispositivo (titolo, corpo, immagine);

• data: informazioni aggiuntive, non visualizzate ma consegnate all’app.

Esempio di payload “Notification + Data”:

{
  "notification": {
    "title": "Nuova offerta disponibile!",
    "body": "Accedi all’app e scopri i dettagli.",
    "image": "https://example.com/img/promo.png"
  },
  "data": {
    "mn_message_id": "mnid2m.1234.12.12.1.2",
    "pushdata.promo": "OFFERTA_ESTIVA",
    "pushdata.url": "https://example.com/promo"
  }
}

Comportamento:

• La notifica viene mostrata automaticamente dal sistema operativo.

• Gli eventi di click o dismiss devono essere intercettati dal codice dell’app per essere tracciati.

• È la modalità consigliata per messaggi visibili e promozionali.

Data-only

Il messaggio contiene solo la sezione data, senza elementi visibili.
In questo caso, l’app riceve il payload ma deve gestire manualmente la visualizzazione o l’elaborazione.

Esempio di payload “Data-only”:

{
  "data": {
    "mn_message_id": "mnid2m.5678.10.04.3.1",
    "pushdata.action": "refresh_profile",
    "pushdata.user_id": "USR12345"
  }
}

Comportamento:

• Il messaggio non genera una notifica visibile di default.

• L’app deve implementare un listener che interpreta il contenuto del payload e decide come reagire (es. aggiornare dati, sincronizzare contenuti, notificare internamente l’utente).

• È la modalità consigliata per notifiche silenziose o di sincronizzazione dati.

2. Struttura del payload JSON

Ogni notifica inviata tramite firebase push connector ha una struttura comune.
Il connettore compone il payload unendo:

• i campi impostati nell’editor della comunicazione (titolo, corpo, immagine, payload personalizzato);

• il payload di default definito nell’App ID;

• i parametri di tracciamento automatici, tra cui mn_message_id.

Struttura generale:

{
  "notification": {
    "title": "Titolo opzionale",
    "body": "Testo del messaggio",
    "image": "https://..."
  },
  "data": {
    "mn_message_id": "mnid2m.1234.12.12.1.2",
    "pushdata.key": "value"
  },
  "android": {
    "priority": "high"
  },
  "apns": {
    "headers": { "apns-priority": "10" }
  }
}

Nota: le sezioni android, apns, webpush, fcm_options sono generate automaticamente se configurate come extra options nell’App ID.

3. Il campo mn_message_id

Ogni notifica include un identificatore univoco generato dal sistema:

mn_message_id

Questo valore:

• consente di collegare gli eventi (click, open, dismiss) alla notifica originale;

• viene incluso nel payload data;

• deve essere inviato dalle app all’endpoint /event quando si registrano interazioni.

Esempio:

{
  "event_type": "click",
  "mn_message_id": "mnid2m.1234.12.12.1.2"
}

Suggerimento: assicurati che il tuo client Firebase salvi temporaneamente mn_message_id durante la ricezione del messaggio per poterlo riutilizzare nel tracciamento degli eventi.

4. Differenze di comportamento lato app

Attenzione: alcuni dispositivi Android possono limitare la ricezione delle notifiche data-only se l’app non è in foreground. Verifica sempre il comportamento dell’SDK Firebase per la versione specifica della tua app.

5. Best practice per payload personalizzati

• Usa nomi chiari per le chiavi dei campi pushdata.* (es. pushdata.campaign, pushdata.url).

• Evita payload eccessivamente grandi: Firebase impone un limite di 4 KB per il corpo del messaggio.

• Gestisci in modo esplicito la priorità (high, normal) nelle extra options per garantire la corretta consegna.

• Centralizza la logica di tracciamento: tutti gli eventi dell’app devono includere mn_message_id.

• Testa entrambe le modalità (notification+data e data-only) per assicurarti che l’esperienza utente sia coerente su iOS e Android.