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, d’ora in poi definiti “interessati”.

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

  • scrittura diretta nelle API della Consent Solution (ad esempio per salvare il consenso);
  • scrittura in modo sincrono o asincrono, sfruttando opzionalmente il localStorage;
  • molteplici opzioni di monitoraggio del consenso. Non solo è possibile monitorare un modulo specifico e tenere traccia del consenso al momento dell’invio, ma è anche possibile tenere traccia del consenso in modo programmatico (ad esempio dopo una validazione o un altro evento);
  • supporto per la maggior parte dei browser (IE8+);
  • prevede delle callback;
  • offre funzioni di logging.
Attenzione

Il 03/04/2019 è stata rilasciata una nuova versione della libreria JavaScript della Consent Solution. Se hai installato la Consent Solution prima di quella data e vuoi passare alla nuova versione, segui le indicazioni presenti in fondo a questa guida.

1. Integrazione dello script

Per installare il widget JS della Consent Solution dovrai incollare il seguente codice all’interno di ogni pagina del sito, prima della chiusura del 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"}]);
</script>
<script type="text/javascript" src="https://cdn.iubenda.com/cons/iubenda_cons.js" async></script>

*La chiave API è il codice usato dall’SDK per comunicare con l’endpoint della nostra API. La tua chiave API (visualizzata come “YOUR_PUBLIC_API_API_KEY” nell’esempio qui sopra) è generata da iubenda in fase di attivazione della Consent Solution ed è riservata a quello specifico sito web.

Attenzione

Il codice indicato qui sopra è a puro scopo esemplificativo. Assicurati di usare il codice di integrazione della tua Consent Solution, è diverso per ogni sito. Puoi trovarlo in Dashboard > [Il tuo sito web] > Consent Solution > Integra.

2. Configurazione della funzione init

La funzione init (inclusa nello script mostrato in precedenza) definisce come viene istanziata la libreria ed è richiesta su ogni pagina che implementa la Consent Solution.

È possibile aggiungere una funzione di callback come secondo parametro della funzione init. La funzione di callback verrà richiamata una volta caricata la libreria.

Configurando la funzione init in questo modo (aggiungendo una funzione di callback, vedi “YOUR_CALLBACK” nell’esempio seguente) puoi impostare alcune azioni aggiuntive dopo che la libreria è stata caricata:

_iub.cons_instructions.push(["init", {
    api_key: "YOUR_PUBLIC_API_KEY"},
    function YOUR_CALLBACK() {
        //the library has been loaded
        ...
        //put you code here
	...
    }
]);

Seguono i parametri che puoi utilizzare all’interno dell’oggetto init per personalizzare (ad esempio) il logger o il comportamento della libreria:

Nome Richiesto Tipo Note
api_key Stringa La tua chiave pubblica
logger No Stringa Valori possibili: “none”, “console”. Default: “console”
log_level No Stringa Valori possibili: “none”, “debug”, “info”, “warn”, “error”, “fatal”. Default: “error”
sendFromLocalStorageAtLoad No Boolean Determina se lo script deve leggere il localStorage al caricamento e inviare tutto ciò che è incluso. Default: true
// An example configuration with optional parameters added (note: api_key parameter is always required)

_iub.cons_instructions.push(["init", {
    api_key: "YOUR_PUBLIC_API_KEY",
    logger: "console",
    log_level: "warn",
    sendFromLocalStorageAtLoad: false
}, ...]);

3. Associare la Consent Solution a un form

Per salvare i consensi prestati tramite form puoi usare le funzioni load o submit.

3.1 load

La funzione load permette di associare i parametri dell’oggetto consent ai campi del tuo <form> e salvare il consenso all’invio.

Nota: la funzione load può essere chiamata solo dopo la dichiarazione dell’oggetto form (come puoi vedere dall’esempio sottostante).

Ti suggeriamo di inserire il tag <script> subito dopo il <form>:

<form>
    <!-- Your form input fields -->
    <input type="submit" name="submit_button" />
</form>

<script type="text/javascript">
    _iub.cons_instructions.push(["load",
        {
            submitElement: document.getElementById("submit_button"), // if this line is missing, the consent is not automatically recorded at submit time; a call to _iub.cons.sendData (see section below) is needed instead
            form: {
                ...your form object
            },
            consent: {
                legal_notices: [{
                    identifier: "terms",
                    version: "1"
                }]
            }
        }
    ])
</script>

Parametri:

Nome Richiesto Tipo Note
submitElement No Oggetto del DOM Seleziona un elemento che farà scattare l’invio del consenso al momento del click. Se questo elemento non è specificato (o non è attivato) puoi usare _iub.cons.sendData() per salvare il consenso (vedi sotto).
form No/Sì se consent non è definito FormConfig Vedi la sezione dedicata all’oggetto form
consent No/Sì se form non è definito ConsentConfig Vedi la sezione dedicata all’oggetto consent
writeOnLocalStorage No Boolean Definisce se i dati devono essere inviati direttamente o scritti in localStorage. Default: true
autodetect_ip_address No Boolean Abilita o disabilita l’autodetect dell’IP. Default: true

Il codice dell’esempio precedente salverà automaticamente l’oggetto consent con associati i valori dei campi di inserimento:

  • quando il submitElement riceve un evento di click (se submitElement è stato specificato); oppure
  • quando la funzione _iub.cons.sendData() viene chiamata manualmente (dettagli a seguire)

3.1.1 sendData

La funzione sendData dev’essere usata in combinazione con la funzione load e attiva il salvataggio dell’oggetto consent con i valori dei campi di input chiamati dalla precedente funzione load.

Dev’essere utilizzata quando non viene fornito il submitElement (es. quando è necessario convalidare il modulo di input prima dell’invio) e devi attivare programmaticamente il recupero dei dati dal modulo e il conseguente salvataggio del consenso.

// your form handler function
function validateForm() {
    if (isValidForm()) {
        // the form has been validated
  	_iub.cons.sendData();
  	// ...
     }
}

3.1.2 sendFromLocalStorage

Per impostazione predefinita, l’oggetto consent creato dalla funzione load non viene inviato direttamente ai nostri server per l’archiviazione; viene infatti salvato 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.

Il consenso salvato in localStorage verrà automaticamente registrato (cioè inviato ai nostri server per l’archiviazione) al caricamento della pagina successiva.

Se si vuole disabilitare l’invio automatico del consenso salvato in localStorage al caricamento della pagina, dovrai aggiungere sendFromLocalStorageAtLoad = false alla funzione init.

In questi casi, per inviare il consenso salvato in localStorage ai nostri server è necessario richiamare esplicitamente la funzione _iub.cons.sendFromLocalStorage (vedi sotto):

_iub.cons.sendFromLocalStorage()

3.2 submit

La funzione submit consente di inviare i dati del consenso alle API di iubenda, quindi di salvarlo in modo programmatico (ad esempio all’interno di un gestore di eventi o di una funzione di callback):

// An example of .submit scenario: inside the init callback function
$("#submit-btn").click(function(e) {
    e.preventDefault();
    // Synchronous call, it's sent immediately when this function is executed
    _iub.cons_instructions.push(["submit", {... your configuration object(see the examples below)},
      {
        success: function(response) {
          console.log(response);
        }, 
        error: function(response) {
          console.log(response);
        }
      }
    ])
 });

Può essere configurata in due modi:

  • specificando il parametro del selettore del form allo stesso modo della funzione load
  • specificando tutti i valori dell’oggetto consent

Vale la pena notare che, a differenza della funzione load, per impostazione predefinita la funzione submit non sfrutta il localStorage, inviando invece l’oggetto consent direttamente ai nostri server.

Parametri:

Nome Richiesto Tipo Note
form No/Sì se consent non è definito FormConfig (Vedi la sezione dedicata all’oggetto form)
consent No/Sì se form non è definito ConsentConfig (Vedi la sezione dedicata all’oggetto consent)
writeOnLocalStorage No Boolean Definisce se i dati devono essere inviati direttamente o scritti in localStorage. Default: false
autodetect_ip_address No Boolean Abilita o disabilita l’autodetect dell’IP. Default: true
Nota

Qualora vengano forniti sia i parametri del form che del consenso, questi verranno uniti per creare l’oggetto consent. In caso di conflitto tra i dati recuperati dal form e i dati specificati nell’oggetto consent, l’oggetto consent avrà la precedenza.

Callback

In caso di successo viene chiamata la callback .success, in caso di errore invece la callback .error

3.2.1 Quando viene fornito l’oggetto form

In questo esempio (in cui viene fornito l’oggetto form), la funzione submit si occuperà di popolare l’oggetto consent a partire dagli input del form:

_iub.cons_instructions.push(["submit",
{
    form: {"... your form object"},
    consent: {
      legal_notices: [{
        identifier: "terms",
        version: "1"
      }]
    }
},
{
    success: function(response) {
      console.log(response);
    },
    error: function(response) {
      console.log(response);
    }
}
])

3.2.2 Quando non viene fornito l’oggetto form

In alternativa puoi passare l’oggetto consent anche così:

_iub.cons_instructions.push(["submit",
  {
    consent: {
      subject: {
        id: "your-subject-id",
        email: "your-subject-email0@example.com"
      },
      preferences: {
        terms: true
      },
      legal_notices: [
        {
          identifier: "privacy_policy"
        }
      ],
      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) {
      console.log(response);
    },
    error: function(response) {
      console.log(response);
    }
  }
])

Ecco una risposta di esempio (in questo caso di successo) del server:

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

Se vuoi costruire programmaticamente il tuo oggetto consent e inviarlo all’API della Consent Solution, dovrai utilizzare la funzione submit come descritto al punto 3.2.2 Quando non viene fornito l’oggetto form.

5. FormConfig

Questa è la struttura dell’oggetto form passato alle funzioni load e submit:

Nome Tipo Note
selector Oggetto del DOM Selettore del form
map Oggetto Oggetto che permette di mappare gli attributi del consenso a specifici campi del form tramite gli attributi “name” anziché data-cons-x (vedi esempio più in basso)
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 dei campi che si desidera escludere dalla prova del consenso

5.1 Associare i campi del form all’oggetto consent

Puoi farlo in due modi:

1) Specificando il relativo attributo name nell’oggetto MAP (in questo caso non è possibile utilizzare l’id, ma solo l’attributo name):

form: {
  selector: document.getElementById("form"), // The selector of the form from which you'd like to detect the data
  map: { // optional: map consent attributes directly to the corresponding
         // input's "name" attribute, instead of using data-cons-x attributes
    subject: {
      id: "id-element-name"
      email: "email-element-name",
      first_name: "first-name-element-name",
      last_name: "last-name-element-name",
      full_name: "full-name-element-name"
    },
    preferences: {
      terms: "terms-checkbox-element-name"
    }
  }
}

2) Usando gli attributi data-cons-x nel campo di input:

<form>
  <!-- subject -->
  <input type="..." name="subject_name" data-cons-subject-name />
  
    <input type="hidden" name="id" value="12141412" data-cons-subject="id" />
    <p>
        First name:<br/>
        <input type="text" value="value" name="first_name" data-cons-subject="first_name" />
    </p>
    <p>
        Last name:<br/>
        <input type="text" name="last_name" data-cons-subject="last_name" />
    </p>
    <p>
        Full Name:<br/>
        <input type="text" name="full_name" data-cons-subject="full_name" />
    </p>
    <p>
        Email<br/>
        <input type="text" name="email" data-cons-subject="email" />
    </p>
    <p>
        Password<br/>
        <input type="password" name="password" data-cons-exclude />
    </p>
    
    <!-- preferences -->
    <p>
        <label><input type="hidden" name="terms-and-conditions" data-cons-preference="terms-and-conditions" value="value"/> 
        Accept terms and conditions</label>
    </p>
    <p>
        <label><input type="hidden" name="newsletter" value="newsletter" data-cons-preference="newsletter" /> newsletter</label>
    </p>
    <input type="submit" id="submit-btn"/>
</form>

Puoi escludere certi campi ( ad esempio quelli relativi alla password, o comunque non inerenti il consenso) in due modi:

1) Usando data-cons-exclude nei tuoi campi di input:

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

2) Usando exclude nell’oggetto map:

map: {
    .
    .
    // exclude fields by inserting inputs names in this array
    exclude: ['password']
}

6. ConsentConfig

L’oggetto consent possiede queste proprietà:

Nome Richiesto Tipo Note
timestamp No Stringa Timestamp ISO 8601 del momento in cui il consenso è stato prestato. Valore predefinito (se non specificato): ora corrente
subject Oggetto
id No Stringa Identifica l’interessato che ha prestato il consenso. Una volta passato un ID è possibile aggiornare le informazioni dell’interessato pubblicando nuovi consensi. Qualora non venga fornito un ID, l’API creerà un UUID casuale
email No Stringa
first_name No Stringa
last_name No Stringa
full_name No Stringa
verified No Boolean Campo riservato utilizzato per segnalare se un interessato è verificato, ad esempio tramite un double opt-in
legal_notices Array Array di oggetti contenente informazioni sui documenti legali
identifier No Stringa
version No Stringa Generato automaticamente (se non fornito)
proofs Array Array di oggetti contenente dati relativi alla prova
content No Stringa
form No Stringa
preferences Object 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: "your-subject-id",
    email: "your-subject-email0@example.com"
  },
  preferences: {
    terms: true
  },
  legal_notices: [
    {
      identifier: "privacy_policy"
    }
   ]},
   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>"
    }
   ]
}

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.

Vanno comunque dichiarati quali documenti legali sono stati accettati in fase di raccolta del consenso. L’array legal_notices andrà dunque popolato con l’identificatore e la versione dei documenti legali creati in precedenza.

Esempio:

consent: {
  legal_notices: [
    {
      identifier: "privacy_policy",
      version: "1" // auto-filled if not provided
    },
    {
      identifier: "another_legal_notice"
    },
    ...
  ]
}

8. Esempi di implementazione

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

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

8.2 Implementazione del submit (async)

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

8.3 Implementazione di form multipli

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

8.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 funzione di caricamento asincrono della versione più recente, devi aggiornare il modo in cui carichi le funzioni load e init.

Le funzioni init e load possono essere chiamate in due casi:

  • Prima che la libreria abbia terminato il caricamento (caricamento asincrono)
  • Al termine del caricamento della libreria (caricamento sincrono)

Load

Prima:

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

Ora:

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

Nota: questo codice deve precedere quello del vostro elemento, vedi quanto indicato in precedenza.

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]);

Nota: la funzione init è incorporata nello script di installazione e non dovrebbe richiedere alcun aggiornamento da parte dell’utente.

Leggi anche