Consent Solution – Documentazione JS

Per installare il widget JS della Consent Solution, inserisci il codice della Consent Solution in ogni pagina del tuo sito, prima di chiudere il tag HEAD (vedi esempio di codice qui sotto).

<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 è un codice unico che l’SDK utilizza per comunicare con l’endpoint della nostra API. La chiave API (visualizzata come “YOUR_PUBLIC_API_KEY” nell’esempio precedente) viene generata da noi durante l’attivazione della Consent Solution ed è specifica per quel particolare sito.

La funzione init (inclusa nello script di installazione riportato sopra) definisce il modo in cui la libreria viene istanziata ed è necessaria in ogni pagina che implementa il widget Consent Solution.

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

Configurando la funzione init in questo modo (aggiungendo una funzione di callback, si veda “YOUR_CALLBACK” nell’esempio seguente) si possono impostare alcune azioni aggiuntive dopo il caricamento della libreria.

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

I seguenti sono i parametri che si possono usare all’interno dell’oggetto di configurazione init(cioè il primo parametro della funzione init che contiene la chiave API) per personalizzare, ad esempio, il logger o il comportamento della libreria.

Vedi la tabella e l’esempio di codice qui sotto:

// 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 registrare automaticamente i consensi forniti tramite un modulo di iscrizione è possibile utilizzare la funzione load o la funzione submit.

3.1 load

La funzione load consente di legare i campi dell’oggetto consent ai campi di input del tuo <form> e di registrare automaticamente il consenso al momento dell’iscrizione.

Nota: la funzione load deve essere richiamata solo dopo la definizione dell’oggetto form (come si può vedere nell’esempio seguente).

Suggeriamo di inserire il tag <script> dopo il tag <form> come segue:

<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: "term",
                    version: "1"
                }]
            }
        }
    ])
</script>

Parametri:

Il codice dell’esempio precedente registrerà automaticamente l’oggetto consent con i valori dei campi di input vincolati:

• quando la submitElement riceve un evento click (se submitElement è stato specificato); oppure
• quando la funzione _iub.cons.sendData() viene richiamata manualmente (vedi sotto)

3.1.1 sendData

La funzione sendData deve essere utilizzata insieme alla funzione load e attiva il salvataggio dell’oggetto consent con i valori dei campi di input che sono stati vincolati da una precedente chiamata alla funzione load.

Deve essere utilizzato nel caso in cui il submitElement non venga fornita (ad esempio, quando è necessario convalidare il modulo di input prima dell’iscrizione) ed è necessario attivare a livello programmatico il recupero dei dati dal form 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 invece salvato nella cartella localStorage, per evitare la perdita di dati nel caso in cui venga caricata una nuova pagina prima che il JavaScript abbia terminato l’esecuzione. Il consenso salvato in localStorage verrà automaticamente registrato (cioè inviato ai nostri server per l’archiviazione) al caricamento della pagina successiva.

Se vuoi disabilitare l’invio automatico del consenso salvato in localStorage al caricamento della pagina, è necessario indicare il parametro sendFromLocalStorageAtLoad = false all’interno della configurazione dell’oggetto init; in tal caso, per inviare il consenso salvato in localStorage ai nostri server sarà necessario richiamare esplicitamente la funzione _iub.cons.sendFromLocalStorage (vedere sotto).

_iub.cons.sendFromLocalStorage()

3.2 submit

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

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

Può essere configurata in due modi:

• specificando il parametro selector 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: "term",
        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 

_iub.cons_instructions.push(["submit",
  {
    consent: {
      subject: {
        id: "your-subject-id",
        email: "your-subject-email0@example.com"
      },
      preferences: {
        term: true
      },
      legal_notices: [
        {
          identifier: "privacy_policy"
        }
      ],
      proofs: [
        {
          content: "{ \"first_name\": \"John\", \"last_name\": \"Doe\", \"email\": \"john@example.com\" }"
          form: "<form action="%5C%22/action%5C%22" method="full_name5quot;POSTfull_name5quot;"><p><label>First Name</label><input type="full_name5quot;textfull_name5quot;" name="full_name5quot;first_namefull_name5quot;"></p><p><label>Last name</label><input type="full_name5quot;textfull_name5quot;" name="full_name5quot;last_namefull_name5quot;"></p><p><label>E-mail</label><input type="full_name5quot;emailfull_name5quot;" name="full_name5quot;emailfull_name5quot;"></p><input type="full_name5quot;submitfull_name5quot;"></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 nella sezione precedente al punto 3.2.2 Quando non viene fornito l’oggetto form.

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

5.1 Vincolare i campi del form all’oggetto consent

I campi del form possono essere legati al tuo oggetto consent in due modi:

1) Specificando l’attributo name pertinente nell’oggetto MAP (si noti che qui non si può usare 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: {
            term: "terms-checkbox-element-name"
        }
    }
}

2) Utilizzando 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">
    <p>
        First name:<br>
        <input type="text" value="value" name="first_name">
    </p>
    <p>
        Last name:<br>
        <input type="text" name="last_name">
    </p>
    <p>
        Full Name:<br>
        <input type="text" name="full_name">
    </p>
    <p>
        Email<br>
        <input type="text" name="email">
    </p>
    <p>
        Password<br>
        <input type="password" name="password">
    </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à:

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: {
    term: true
  },
  legal_notices: [
    {
      identifier: "privacy_policy"
    }
   ]},
   proofs: [
    {
      content: "{ \"first_name\": \"John\", \"last_name\": \"Doe\", \"email\": \"john@example.com\" }"
      form: "<form action="%5C%22/action%5C%22" method="email1quot;POSTemail1quot;"><p><label>First Name</label><input type="email1quot;textemail1quot;" name="email1quot;first_nameemail1quot;"></p><p><label>Last name</label><input type="email1quot;textemail1quot;" name="email1quot;last_nameemail1quot;"></p><p><label>E-mail</label><input type="email1quot;emailemail1quot;" name="email1quot;emailemail1quot;"></p><input type="email1quot;submitemail1quot;"></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 modificati. Puoi scoprire di più su questa funzionalità qui.

Tuttavia, è comunque necessario dichiarare quali legal_notices sono stati accettati in ogni raccolta di consenso; pertanto, se si utilizzano documenti legali, è necessario riempire l’array legal_notices 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"
    },
    ...
  ]
}

Di seguito sono riportati alcuni esempi pratici di come è possibile implementare nella pratica la Consent Solution.

8.1 Funzionalità MAP

Funzione load

Vedi la Pen [Iubenda Cons] (async) Funzione load di iubenda (@iubenda) su CodePen.

Funzione load con Map (senza data-attribute)

Vedi la Pen [Iubenda Cons] (async) Funzione load di iubenda (@iubenda) su CodePen.

8.2 Implementazione del submit (async)

Vedi la Pen [Iubenda Cons] (async) Implementazione submit di iubenda (@iubenda) su CodePen.

8.3 Implementazione di più form

Vedi la Pen [Iubenda Cons] (async) Multiple Form implementation di iubenda (@iubenda) su CodePen.

8.4 Strumenti di validazione esterni (Funzione load con validate.js)

Vedi la Pen [Iubenda Cons] (async) Funzione load con validate.js di iubenda (@iubenda) su CodePen.