Flusso di comunicazione e integrazione

Il connettore Firebase Push definisce un flusso di interazione chiaro tra magnews, Firebase Cloud Messaging (FCM) e le app client (Android, iOS o Web).
Comprendere come i diversi componenti comunicano è fondamentale per configurare correttamente l’integrazione, gestire utenti anonimi e riconosciuti, e garantire la coerenza del tracciamento eventi.

Visione d’insieme del flusso

Il flusso di comunicazione prevede tre fasi principali:

1. Registrazione del token: l’app comunica a magnews l’identificativo univoco del dispositivo (push token).

2. Invio della notifica: magnews invia il messaggio a Firebase, che lo recapita ai dispositivi target.

3. Tracciamento eventi: l’app restituisce a magnews gli eventi generati dall’utente (apertura, click, dismiss, conversione).

Schema logico semplificato:

[App] ⇄ [MagNews Firebase Connector] ⇄ [Firebase Cloud Messaging]
         ↕
     [Database contatti MagNews]

Nota: ogni fase è supportata da uno o più endpoint REST descritti nel documento tecnico originale. I numeri tra parentesi fanno riferimento al diagramma ufficiale del flusso.

1. Registrazione del token (App → MagNews)

Quando un utente installa o avvia l’app, Firebase genera un push token che identifica in modo univoco il dispositivo.
L’app invia questo token a magnews per la registrazione tramite uno dei seguenti endpoint:

• Utente anonimo (visitor)
  Endpoint: /merge_visitor
  → Registra un utente senza dati identificativi, collegando solo il token e l’App ID.

• Utente riconosciuto (contact)
  Endpoint: /merge_contact
  → Associa il token a un contatto magnews già presente o ne crea uno nuovo.
  Può anche riconciliare un profilo anonimo precedentemente registrato.

Durante la chiamata vengono memorizzati:

• il push_id (token Firebase);

• il riferimento al database corretto;

• il flag opt_in che indica la volontà di ricevere notifiche.

2. Invio della notifica (MagNews → Firebase → App)

Una volta configurata la comunicazione e selezionate le App ID di destinazione, magnews:

1. Filtra i token validi in base al target e alle App ID scelte.

2. Genera il payload della notifica, includendo titolo, corpo, immagine e dati aggiuntivi.

3. Invia il messaggio a Firebase Cloud Messaging (FCM), che si occupa della distribuzione ai dispositivi.

Tipologie di invio

• Standard: parte da un journey o da una comunicazione programmata.

• Transazionale: generato via API (/send_simple_message) da sistemi esterni, per eventi singoli come conferme d’ordine o reset password.

Caratteristiche tecniche

• Ogni notifica include automaticamente il campo mn_message_id, utile per la riconciliazione delle statistiche.

• magnews supporta notifiche multi-device: un singolo contatto può ricevere la stessa notifica su più dispositivi associati.

• Gli esiti di invio (success/failure) vengono registrati e resi disponibili nella sezione di tracciamento.

3. Tracciamento eventi (App → MagNews)

Quando l’utente interagisce con una notifica (apre, clicca, chiude o converte), l’app può inviare un evento a magnews tramite l’endpoint:
/event

Il payload include:

• event_type → tipo di interazione (open, click, convert, dismiss, bounceback);

• push_id o push_id_enc → identificativo dispositivo (in chiaro o cifrato);

• mn_message_id → ID del messaggio originale;

• event_time → timestamp dell’evento.

Suggerimento: l’uso del campo push_id_enc (token cifrato in AES/CBC/PKCS5Padding) è consigliato per una trasmissione sicura. Le chiavi e i vettori di cifratura devono essere condivisi tra il sistema esterno e il connettore.

Gli eventi vengono raccolti da magnews e resi disponibili:

• nella sezione Insight delle comunicazioni push;

• nei report personalizzati e nelle dashboard di automazione.

4. Ruolo degli endpoint nel flusso

Nel diagramma originale, ogni fase del processo è numerata per rappresentare un endpoint o un’interazione specifica:

Questa numerazione mantiene la coerenza con la documentazione tecnica e con i log applicativi del connettore.

5. Gestione dei diversi scenari

Utenti anonimi

• Registrati con /merge_visitor.

• Non contengono dati personali.

• Utili per tracciare prime interazioni e creare profili futuri.

Utenti riconosciuti

• Registrati o riconciliati con /merge_contact.

• Collegati a un database contatti esistente.

• Possono ricevere notifiche personalizzate e transazionali.

Invii transazionali

• Attivati via API (/send_simple_message).

• Consentono l’invio puntuale a un token, contatto o chiave primaria.

• Supportano l’uso di template magnews  e payload dinamici.

6. Sicurezza e autenticazione

Gli endpoint del connettore supportano due modalità operative:

Attenzione: se un endpoint pubblico non è esplicitamente attivato, il connettore risponde con HTTP 404, prevenendo accessi indesiderati.