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à:
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.
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.
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.
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 | Sì | 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
}, ...]);Per salvare i consensi prestati tramite form puoi usare le funzioni load o submit.
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" id="submit-btn" name="submit-button" />
</form>
<script type="text/javascript">
_iub.cons_instructions.push([ * "load" * ,
{
submitElement: "submit-btn", // 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 | Stringa o oggetto del DOM | Passa l’ID sotto forma di stringa o l’oggetto del DOM 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:
submitElement riceve un evento di click (se submitElement è stato specificato); oppure_iub.cons.sendData() viene chiamata manualmente (dettagli a seguire)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();
// ...
}
}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()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:
loadconsentVale 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 |
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.
In caso di successo viene chiamata la callback .success, in caso di errore invece la callback .error
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);
}
}
])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.
Questa è la struttura dell’oggetto form passato alle funzioni load e submit:
| Nome | Tipo | Note |
|---|---|---|
| selector | Stringa o oggetto del DOM | L’ID (in formato stringa) del form o l’oggetto form del DOM |
| 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 |
| 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 |
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: "form-id", // The string (ID) or the DOM element 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 id="form-id">
<!-- 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']
} L’oggetto consent possiede queste proprietà:
| Nome | Richiesto | Tipo | Note |
|---|---|---|---|
| subject | Sì | 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 |
| 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 | Sì | Array | Array di oggetti contenente informazioni sui documenti legali |
| identifier | No | Stringa | |
| version | No | Stringa | Generato automaticamente (se non fornito) |
| proofs | Sì | Array | Array di oggetti contenente dati relativi alla prova |
| content | No | Stringa | |
| form | No | Stringa | |
| preferences | Sì | 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"
},
...
]
}A seguire alcuni casi d’uso per la Consent Solution.
See the Pen [Iubenda Cons] (async) Load function by iubenda (@iubenda) on CodePen.
See the Pen [Iubenda Cons] (async) Load function and Map option by iubenda (@iubenda) on CodePen.
See the Pen [Iubenda Cons] (async) Submit implementation by iubenda (@iubenda) on CodePen.
See the Pen [Iubenda Cons] (async)Multiple Form implementation by iubenda (@iubenda) on CodePen.
See the Pen [Iubenda Cons] (async) load function with validate.js by iubenda (@iubenda) on CodePen.
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:
_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.
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.