Consent Solution – Documentazione JS

La libreria JavaScript della Consent Solution consente di registrare e recuperare le azioni di consenso eseguite dai propri utenti, che d’ora in poi saranno definiti “interessati”.

La libreria JavaScript della Consent Solution include le seguenti funzionalità:

• scrittura diretta nelle API della Consent Solution;
• scrittura in modo sincrono o asincrono, a scelta utilizzando il localStorage;
• configurazione volta a monitorare uno specifico modulo e a tracciare il consenso al momento dell’invio del modulo stesso, oppure in modo programmatico;
• supporto per la maggior parte dei browser (IE8+);
• prevede delle callback;
• offre funzioni di logging.

Configurazione

Per installare il widget JS della Consent Solution, occorre incollare il seguente codice all’interno di ogni pagina del sito, prima di chiudere il tag HEAD.

<script type="text/javascript" src="https://cdn.iubenda.com/consent_solution/iubenda_cons.js"></script>
<script type="text/javascript">
  _iub.cons.init({
    api_key: "YOUR_PUBLIC_API_KEY", *// IMPORTANTE: DA PERSONALIZZARE CON LA TUA CHIAVE API PUBBLICA*
  });
</script>

Consent

Condiviso tra i metodi record e load

Campi

Condivisi con le API HTTP:

Nota: nella libreria JS, tutte le proprietà devono essere specificate dall’interno dell’oggetto consent.

Esempio:

consent {
    subject: {
      id: "08487b19456ec8f7678f",
      email: "test10@iubenda.com"
    },
    preferences: {
      "terms": true
    }
}

Esclusivi della libreria JavaScript:

Informazioni aggiuntive sull’oggetto form

Utilizzando l’oggetto form, è possibile configurare la libreria Javascript per estrarre automaticamente i dati necessari da un form. Per segnalare alla libreria come abbinare campi specifici, è possibile utilizzare gli attributi data-, con il prefisso data-cons- oppure abbinare ogni campo con il suo attributo name usando l’oggetto map.

Ad esempio, questo è il modo in cui è possibile etichettare l’input dell’e-mail:

<input type="text" name="email" data-cons-subject="email"/>

È anche possibile escludere determinati campi:

<input type="password" name="password" data-cons-exclude/>

Altri esempi di attributi data-:

• data-cons-subject="first_name"
• data-cons-subject="last_name"
• data-cons-subject="full_name"
• data-cons-subject="email"
• data-cons-preference="privacy_policy"
• data-cons-exclude

In caso di conflitto tra i dati specificati dall’oggetto form e quelli specificati direttamente nell’oggetto consent, quest’ultimo avrà la precedenza.

Se è specificato un form, la libreria si occuperà anche di riempire automaticamente l’oggetto proof.

Risposta

200 OK
{
  "id": "de801ca9-abec-45e2-8f7c-729822cfffad",
  "timestamp": "2018-05-04T14:52:26Z",
  "subject_id": "J02eZvKYlo2ClwuJ1"
}

Submit

Il metodo submit permette di scrivere nell’API in modo sincrono.

<script type="text/javascript">
  _iub.cons.submit({
    form: {
      selector: document.getElementById("form"), // il selettore del form da cui rilevare i dati
      map: { // opzionale: abbina gli attributi del consenso direttamente ai corrispondenti attributi dell'input "name", anziché usare gli attributi data-cons-x
        subject: {
            email: "email-element-name",
            first_name: "first-name-element-name",
            last_name: "last-name-element-name"
        },
        preferences: {
            terms: "terms-checkbox-element-name"
        }
      }
    },
    consent: {
        subject: {
          id: "08487b19456ec8f7678f",
          email: "user@example.com"  // questo valore sovrascrive l'e-mail dell'interessato passata dal form
        },
        preferences: {
          terms: true
        },
        legal_notices: [
            {
              identifier: "privacy_policy",
              version: "12"
            }
        ],
        proofs: [
          {
            content: "{ \"first_name\": \"John\", \"last_name\": \"Doe\", \"email\": \"john@example.com\" }"
            form: "<form action=\"/action\" method=\"POST\"><p><label>First Name</label><input type=\"text\" name=\"first_name\" /></p><p><label>Last name</label><input type=\"text\" name=\"last_name\" /></p><p><label>E-mail</label><input type=\"email\" name=\"email\" /></p><input type=\"submit\" /></form>"
          }
        ]
    }
  })
  .success(function (response) {
    // Success callback
  })
  .error(function (response) {
    // Error callback
  });
</script>

Nota: Se usi iubenda per i tuoi documenti legali, aggiorneremo automaticamente i contenuti del metodo legal_notices ogni volta che i tuoi documenti legali vengono cambiati. Puoi scoprire di più su questa funzionalità qui.

Callback

La callback .success è disponibile in caso di successo, la callback .error è disponibile in caso di errore.

Load

Il metodo load permette di caricare valori nel metodo che possono essere scritti in un secondo momento, sia impostando una funzione trigger in submitElement: che in modo programmatico tramite un trigger dedicato. Per impostazione predefinita, questo metodo scrive in localStorage, così da proteggersi da qualsiasi perdita di dati nel caso in cui venga caricata una nuova pagina prima che il Javascript abbia finito di essere eseguito.

Specifici del metodo load:

<script type="text/javascript">
_iub.cons.load({
    submitElement: $("#submit_button"), *// se manca, il consenso viene inviato solo quando _iub.cons.sendData è attivato*
    *// QUANTO SEGUE È IDENTICO ALLA CHIAMATA .submit*
    form: {
      selector: $("#form"), *// il selettore del form da cui rilevare i dati*
    },
    consent: {
        subject: {
          id: "08487b19456ec8f7678f",
          email: "user@example.com"  *// questo valore sovrascrive l'e-mail dell'interessato passata dal form*

        },
        preferences: {
          "terms": true
        },
        legal_notices: [
          identifier: "privacy_policy",
          version: "12"
        ],
        proofs: [
          {
            content: "{ \"first_name\": \"John\", \"last_name\": \"Doe\", \"email\": \"john@example.com\" }"
            form: "<form action=\"/action\" method=\"POST\"><p><label>First Name</label><input type=\"text\" name=\"first_name\" /></p><p><label>Last name</label><input type=\"text\" name=\"last_name\" /></p><p><label>E-mail</label><input type=\"email\" name=\"email\" /></p><input type=\"submit\" /></form>"
          }
        ]
    }
  })
  .success(function (response) {
    *// callback success*

  })
  .error(function (response) {
    *// callback error*
  });
</script>

sendFromLocalStorage

Il metodo sendFromLocalStorage permette di inviare i dati del consenso precedentemente salvati nel local storage. Normalmente, l’init script spedirà ogni consenso memorizzato nel local storage ad ogni caricamento della pagina se sendFromLocalStorageAtLoad è impostato a true.

_iub.cons.sendFromLocalStorage()

Esempi di implementazione

A seguire alcuni casi d’uso per la Consent Solution.

1. Funzionalità MAP

Funzione Load

See the Pen [Iubenda Cons] Load function. by iubenda (@iubenda) on CodePen.

Funzione Load con Map (senza data-attribute)

See the Pen [Iubenda Cons] Load function and Map option by iubenda (@iubenda) on CodePen.

2. Implementazione del Submit

See the Pen [Iubenda Cons] Submit implementation by iubenda (@iubenda) on CodePen.

3. Implementazione di form multipli

See the Pen [Iubenda Cons] Multiple Form implementation by iubenda (@iubenda) on CodePen.

4. Strumenti di validazione esterni (funzione validate.js)

See the Pen [Iubenda Cons] load function with validate.js by iubenda (@iubenda) on CodePen.