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, sfruttando opzionalmente 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">
    var _iub = _iub || {};
    _iub.cons_instructions = _iub.cons_instructions || [];
    _iub.cons_instructions.push(["init", {api_key: "YOUR_PUBLIC_API_KEY"}, YOUR_CALLBACK_FUNCTION]);
</script>
<script type="text/javascript" src="https://cdn.iubenda.com/cons/iubenda_cons.js" async></script>

Istruzioni per il consenso

_iub.cons_instruction è un array dove le istruzioni possono essere inserite prima che la Consent Solution sia stata caricata. Dopo il caricamento, tutte le istruzioni contenute nell’array verranno eseguite.

Le istruzioni devono seguire questa sintassi (vedi gli esempi a seguire):
[<nome della funzione>, [Parametro1][, Parametro2] … ]

Funzione di callback init

Il secondo parametro della funzione init è la funzione di callback. La funzione di callback sarà chiamata solo dopo che la libreria è stata caricata (vedi questo esempio).

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:

_iub.cons_instructions.push(["load",
    {
      submitElement: document.getElementById("submit_button"), // if this line is missing, the consent is sent only when _iub.cons.sendData is triggered
      // WHAT FOLLOWS IS IDENTICAL TO THE .submit call
      form: {
        selector: document.getElementById("form"), // The selector of the form where to detect the data
      },
      consent: {
        subject: {
          id: "08487b19456ec8f7678f",
          email: "user@example.com"  // This will overwrite the subject email that is passed via the 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>"
          }
        ]
      }
    }])

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] (async) Load function by iubenda (@iubenda) on CodePen.

Funzione Load con Map (senza data-attribute)

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

2. Implementazione del Submit

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

3. Implementazione di form multipli

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

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

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

Come aggiornare le installazioni della Consent Solution precedenti il 03/04/2019

Se hai installato la Consent Solution prima del 03/04/2019 e vuoi utilizzare la versione più recente, devi aggiornare il modo in cui si caricano i metodi load e init.

Load

Prima:

_iub.cons.load({ ... your options })

Ora:

_iub.cons_instructions.push(["load", { ... your options })

Init

Prima:

_iub.cons.init({api_key: "YOUR_PUBLIC_API_KEY"}, YOUR_CALLBACK_FUNCTION]);

Ora:

_iub.cons_instructions.push(["init", {api_key: "YOUR_PUBLIC_API_KEY"}, YOUR_CALLBACK_FUNCTION]);