Form REST API: esegui il submit di una landing page da un sito esterno – magnews Help Center

La Form REST API è un servizio che consente di eseguire l’invio di un form del frontend di magnews tramite AJAX.

Questa API è distinta dalla REST API ufficiale di magnews. Le chiamate eseguite tramite questa interfaccia non sono tracciate nei log del webservice presenti in piattaforma e non utilizzano l'infrastruttura standard delle REST API pubbliche (es. logging centralizzato, autenticazione, ..).

È utile per integrare pagine web esterne con le funzionalità di magnews. Con un token contatto valido, è anche possibile inviare una compilazione di un form modificando i dati del contatto (utilizzando le azioni pulsante configurate nella landing page magnews).

Requisiti per il submit di un form

Per eseguire una submit è necessario:

un dominio web personalizzato associato all’account cliente, ad esempio customerhost.com, su cui la Form REST API sarà disponibile all’indirizzo http://customerhost.com/nl/api/forms
l’ID del form della landing page (es. 188). Per trovare l’ID della pagina, apri il designer della landing page, seleziona la pagina che contiene il form, clicca su Modifica pagina (accanto al selettore), quindi sull’icona delle informazioni accanto al nome della pagina.
i nomi degli attributi name degli input del form
almeno un attributo name per un pulsante di submit

La richiesta deve essere inviata in formato JSON nel corpo di una richiesta HTTP POST.

Property	Datatype	Description
`idform`	int	Obbligatorio. ID della singola pagina contenente il form.
`language`	string	Opzionale. Codice lingua (3 caratteri) usato nei messaggi di errore
`token`	string	Opzionale. Token che identifica il contatto. Se non fornito, la compilazione sarà anonima
`parameters`	array of Object	Obbligatorio. Ogni oggetto dell'array rappresenta un input del form. Deve essere incluso anche un oggetto che rappresenta il pulsante di submit

Nota
Il campo name degli input viene generato automaticamente da magnews, ma può essere personalizzato nel designer della landing page (Edit dell'input > tab Codice > Personalizza l'attributo NAME)

// Request body
{
    "idform":188,
    "language":"ENG",
    "parameters":[
        {
           "name":"overridden_input_name",
           "value":"123"
        },
        {
           "name":"_mn_form_ctrl_5782", // auto generated input name
           "value":"I am an input value"
        }
    ]
}

// Response body
{
    "ok": true
}

Come ottenere un token per il contatto

Un token contatto può essere ottenuto in tre modi:

Usando un’azione pulsante che inietta l’identità del contatto nel contesto del form, come Iscrivi contatto o Login contatto
Tramite uno script di web tracking.
Tramite un'app custom, recuperando il campo token dal bean Contact.

Ottenere l’identità di un contatto tramite invio form

Esempio di invio per un form di iscrizione e risposta con token:

// Request body
{
    "idform":188,
    "language":"ENG",
    "parameters":[
        {
           "name":"_mn_form_ctrl_153", // auto generated input name
           "value":"I am an input value"
        },
        {
           "name":"overridden_email_input_name",
           "value":"example@mydomain.com"
        }
    ]
}

// Response body
{
    "idcontact": 4129578,
    "ok": true,
    "token": "17beg3f032ag30e09281398788d25f28688480e2481a18ac432a"
}

Una volta ottenuto, il token può essere riutilizzato per invii successivi con identità del contatto.
Esempio di invio con token (body della POST):

    {
    "idform":188,
    "language":"ENG",
    "token":"17beg3f032ag30e09281398788d25f28688480e2481a18ac432a",
    "parameters":[
        {
           "name":"overridden_input_name",
           "value":"update value"
        },
        {
           "name":"_mn_form_ctrl_5782", // auto generated input name
           "value":"I am an input value"
        }
    ]
}

Ottenere un’identità contatto tramite web tracking

Se lo script di web tracking è incluso in una pagina web esterna, è possibile recuperare il token contatto tramite la funzione mna.getContactId().

Per ottenere il vero ID contatto, puoi usare invece mna.getTrackedContactId(), che prova a estrarre l’ID dal token. Se non ci riesce, restituisce 0.
Esempio d’uso:

mna.getTrackedContactId(mna.getContactId())

Nota
Lo script di web tracking viene caricato in modo asincrono, quindi la funzione mna.getContactId() potrebbe non essere ancora disponibile nel momento in cui viene eseguita. Inoltre, può restituire null se la sessione contatto non è stata avviata.

Ecco un esempio di recupero del contact tramite script di web tracking:

    <!DOCTYPE html<br />
<html>
    <head>
        <title>TODO supply a title</title>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <script type="text/javascript">
            (function (m, a, g, n, e, w, s) {
                m[e] = m[e] || function () {
                    (m[e].q = m[e].q || []).push([arguments[0], arguments[1], 1 * (new Date()).getTime()]);
                };
                w = a.createElement(g), s = a.getElementsByTagName(g)[0];
                w.async = 1;
                w.src = n;
                s.parentNode.insertBefore(w, s);
            })(window, document, 'script', '//customerhost.com/webtracking/js/webtracking.js', 'mna');
            mna('init', {sendbeacon: true, apikey: '17begbfa4a6f', trackerhostname: 'customerhost.com', sessionTimeout: 20});
        </script>
    </head>
    <body>
        <a href="javascript: void(0)" onclick="submitWithContactIdentity()" />
        <script type="text/javascript">
            function submitWithContactIdentity() {
                if (!mna.getContactId) {
                    // webtracking.js is loaded asynchronously, so the mna.getContactId function could not have been declared at this time.
                    return;
                }
                var contactId = mna.getContactId();
                if (!contactId) {
                    // contactId can be null if no session has been started.
                    return;
                }

                [..]
                Do your AJAX request
            }
        </script>
    </body>
</html>