API Reference del Firebase Connector

Il Firebase Push Connector espone una serie di API REST che consentono l’integrazione tra sistemi esterni, app client e la piattaforma magnews.
Gli endpoint permettono di gestire la registrazione dei token, l’invio delle notifiche, la raccolta degli eventi e la manutenzione dei dati dei destinatari.

Questa sezione raccoglie in modo sistematico tutti gli endpoint, con esempi pratici di richieste e risposte, seguendo le specifiche della versione Connector 1.6.0 / Doc 2.0.1.

Autenticazione e access token

Endpoint:

POST https://be-mn1.mag-news.it/be/oauth/token

Descrizione

Alcuni endpoint richiedono autenticazione tramite OAuth 2.0.
Questa chiamata consente di ottenere un token valido da utilizzare nell’header Authorization.

Request

content-type: application/x-www-form-urlencoded

client_id=$app_id&client_secret=$client_secret&refresh_token=$refresh_token&grant_type=refresh_token

Response

{
  "access_token": "*",
  "refresh_token": "-",
  "token_type": "Bearer",
  "expires_in": 14399
}

Usa il valore di access_token per autenticare le chiamate successive:

Authorization: Bearer <access_token>

Registrazione utente anonimo

Endpoint:

POST https://ws-mn1.mag-news.it/ws/rest/api/apps/firebase.push.connector/merge_visitor

Descrizione

Registra un utente anonimo (visitor) in magnews, associando il token push senza informazioni personali.
Può essere chiamato anche senza autenticazione, se l’endpoint è stato attivato da AppCenter.

Request

{
  "app_id": "app-android",
  "push_id": "token123",
  "opt_in": true,
  "fields": [
    {
      "field": "INTERESSI",
      "value": "Cinema",
      "type": "multiselect",
      "action": "append"
    }
  ]
}

Response

{
  "ok": true,
  "data": {
    "visitor_id": "v-24b53d6e-07ae-4650-b3a0-76329bc8b788",
    "contactId": 3
  },
  "errors": null
}

Creazione o riconciliazione di un contatto riconosciuto

Endpoint:

POST https://ws-mn1.mag-news.it/ws/rest/api/apps/firebase.push.connector/merge_contact

Descrizione

Associa un token a un contatto identificato nel database, oppure riconcilia un utente anonimo già registrato.

Request

{
  "app_id": "app-android",
  "visitor_id": "v-24b53d6e-07ae-4650-b3a0-76329bc8b788",
  "push_id": "token123",
  "opt_in": true,
  "fields": [
    { "field": "EMAIL", "value": "mario.rossi@test.com" },
    { "field": "NAME", "value": "Mario" },
    { "field": "SURNAME", "value": "Rossi" },
    { "field": "TAG", "value": "VIP", "type": "multiselect", "action": "append" }
  ],
  "options": [
    { "key": "fields_to_copy_from_visitor", "value": "TAG" }
  ]
}

Response

{
  "ok": true,
  "data": {
    "contactId": 3,
    "primary_key": "mario.rossi@test.com",
    "dbId": 1
  },
  "errors": null
}

Aggiornamento del consenso push

Endpoint:

POST https://ws-mn1.mag-news.it/ws/rest/api/apps/firebase.push.connector/optin

Descrizione

Aggiorna lo stato del consenso (opt_in) per un contatto o token.
Può essere usato per revocare o ripristinare la ricezione di notifiche push.

Request

{
  "app_id": "app-android",
  "push_id": "token123",
  "contact_id": 12345,
  "opt_in": false
}

Response

{
  "ok": true,
  "data": {
    "updated": true,
    "opt_in": false
  },
  "errors": null
}

Registrazione eventi utente

Endpoint:

POST https://ws-mn1.mag-news.it/ws/rest/api/apps/firebase.push.connector/event

Descrizione

Registra eventi generati dall’interazione con una notifica push (es. apertura, click, conversione).
Può essere pubblico o autenticato, a seconda della configurazione.

Request

{
  "event_type": "click",
  "push_id_enc": "encodedTokenXYZ",
  "mn_message_id": "mnid2m.1234.12.12.1.2",
  "event_time": 1726449117103
}

Response

{
  "ok": true,
  "data": null,
  "errors": null
}

Suggerimento: l’uso di push_id_enc (token cifrato AES) è raccomandato per motivi di sicurezza.

Cancellazione di un token

Endpoint:

POST https://ws-mn1.mag-news.it/ws/rest/api/apps/firebase.push.connector/unregister

Descrizione

Rimuove un token push da magnews.
Può essere usato quando un utente disinstalla l’app o disattiva le notifiche.

Request

{
  "push_id": "token123",
  "contactId": "3"
}

Response

{
  "ok": true,
  "data": null,
  "errors": null
}

Nota: se il token è associato a più contatti e non viene passato contactId, il token viene scollegato da tutti.

Invio push transazionale

Endpoint:

POST https://ws-mn1.mag-news.it/ws/rest/api/apps/firebase.push.connector/send_simple_message

Descrizione

Permette a sistemi esterni di inviare notifiche push transazionali verso token, contatti o chiavi primarie, con o senza template.

Esempi di utilizzo

Invio a un contatto tramite idcontact

{
  "options": {
    "idcontact": 1
  },
  "values": {
    "appnames": ["app-android"],
    "pushtitle": "Titolo",
    "pushbody": "Ciao [contact:nome]",
    "pushimage": "https://example.com/logo.png"
  }
}

Invio tramite contactprimarykey

{
  "options": {
    "iddatabase": 1,
    "contactprimarykey": "mario.rossi@diennea.com"
  },
  "values": {
    "appnames": ["app-android"],
    "pushtitle": "Titolo",
    "pushbody": "Messaggio personalizzato"
  }
}

Invio diretto a token

{
  "values": {
    "to": ["tokenA", "tokenB"],
    "pushtitle": "Titolo",
    "pushbody": "Messaggio generico"
  }
}

Invio usando un template magnews

{
  "options": {
    "idcontact": 1,
    "iddatabase": 1,
    "contactprimarykey": "mario.rossi@diennea.com",
    "usenewsletterastemplate": true,
    "idnewsletter": 123
  }
}

Aggiunta di payload personalizzati

{
  "options": {
    "idcontact": 1
  },
  "values": {
    "appnames": ["app-android"],
    "pushtitle": "Titolo",
    "pushbody": "Ciao [contact:nome]",
    "pushdata.user_code": "codiceutente",
    "pushdata.contractcode": "CTR001"
  }
}

Response

{
  "ok": true,
  "data": {
    "sentMessages": [
      {
        "idcontact": 1,
        "pushIds": "1",
        "msgId": 22,
        "ok": true
      }
    ]
  },
  "errors": null,
  "warnings": null
}

Notification center: recupero di messaggi per singolo contatto

Endpoint:

POST https://ws-mn1.mag-news.it/ws/rest/api/v19/mql/execute

In questo caso, è possibile utilizzare API Standard di magnews, con il metodo MQL/EXECUTE per interrogare la tabella con l'elenco di tutti i messaggi inviati a tutti i contatti. E' possibile utilizzare query SQL-like per recuperare i messaggi sulla base delle necessità specifiche. 

L'entità in questione è firebase_notification che ha la seguente struttura

Esempi di utilizzo

Recupero degli ultimi 10 messaggi inviati al contatto email

{
  "query": "select * from firebase_notification where contact_key='email@example.com' order by sent_ts desc",
  "options": {
    "max": "10"
  }
}

Struttura comune delle risposte

Ogni endpoint del connettore restituisce una risposta con lo stesso formato:

{
  "ok": true|false,
  "data": { ... },
  "errors": null|[ { "code": "ERR_CODE", "message": "Descrizione" } ],
  "warnings": null|[ ... ]
}

• ok: indica l’esito generale della richiesta;

• data: contiene i risultati della chiamata;

• errors: elenca eventuali errori bloccanti;

• warnings: segnala avvisi o comportamenti non critici.

Codici di stato e note di compatibilità

Compatibilità: tutte le API descritte sono compatibili con il connettore dalla versione 1.4.0 in avanti. Alcuni campi opzionali (fields_to_copy_from_visitor, opt_in) sono stati introdotti successivamente (v.1.6.0).