Documentazione

Indice dei contenuti

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.
Attenzione

Se hai integrato la Consent Solution prima del 03/04/2019 e vuoi passare alla nuova versione, segui le istruzioni in fondo a questa guida.

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).

api_key richiesto stringa la tua chiave pubblica
logger opzionale stringa none, console (default)
log_level opzionale stringa none, debug, info, warn, error, fatal
In arrivo:
sendFromLocalStorageAtLoad opzionale boolean default: true (determina se lo script deve leggere il localStorage al caricamento e inviare tutto ciò che è incluso)

Consent

Condiviso tra i metodi record e load

Campi

Condivisi con le API HTTP:

timestamp auto generato (se non fornito) stringa timestamp ISO 8601 del momento in cui il consenso è stato prestato
subject oggetto
id auto generato (se non fornito) stringa
email opzionale stringa
first_name opzionale stringa
last_name opzionale stringa
full_name opzionale stringa
verified opzionale boolean campo riservato utilizzato per segnalare se un interessato è verificato, ad esempio tramite un double opt-in
legal_notices opzionale array array di stringhe
identifier opzionale testo
version auto generato (se non fornito) testo
proofs opzionale array array di oggetti contenente dati relativi alla prova
content opzionale testo
form opzionale testo
preferences opzionale oggetto set di coppie chiave-valore con le preferenze dell’utente per l’azione di consenso

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:

form oggetto
selector oggetto del DOM selettore del form
map oggetto oggetto che permette di associare gli attributi Consent a specifici campi del form con gli attributi “name” in alternativa agli attributi data-cons-x
subject oggetto
id stringa attributo name di un elemento del DOM presente nel form
email stringa attributo name di un elemento del DOM presente nel form
first_name stringa attributo name di un elemento del DOM presente nel form
last_name stringa attributo name di un elemento del DOM presente nel form
full_name stringa attributo name di un elemento del DOM presente nel form
preferences oggetto
preference_name stringa attributo name di un elemento del DOM presente nel form
exclude array elenco di nomi di campi che si desidera escludere dalla prova del consenso
In arrivo:
writeOnLocalStorage boolean definisce se i dati devono essere inviati direttamente o scritti in localStorage. Il valore predefinito cambia tra i metodi .record (false) e .load (true)

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:

submitElement opzionale seleziona un elemento che farà scattare l’invio del consenso al momento del click. Se questo elemento non è specificato, o non è attivato, si può sempre usare _iub.cons.sendData() per inviare il consenso con i parametri contenuti in _iub.cons.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]);