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.

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.

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:

// 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:

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:

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"
}

4. Creare e salvare l’oggetto consent in modo programmatico

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:

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à:

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>"
    }
   ]
}

7. Documenti legali

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

• Consent Solution – Introduzione e funzionamento
• Come implementare la Consent Solution con Contact Form 7