Consent Database: Documentación de JS

Para instalar el widget de JS de la Consent Database, inserta el código de la Consent Database dentro de todas las páginas de tu web antes de cerrar la etiqueta HEAD (consulta el código de ejemplo a continuación).

<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 clave API es un código único que el SDK utiliza para comunicarse con el endpoint de nuestra API. Nosotros generamos tu clave API (que aparece como “YOUR_PUBLIC_API_KEY” en el ejemplo anterior) durante la activación de la Consent Database y es específica para ese sitio web en concreto.

La función init (incluida en el script de instalación anterior) define cómo se crea una instancia de la biblioteca y debe incluirse en cada página que implementa el widget de la Consent Database.

Es posible añadir una función callback como un segundo parámetro de la función init. Se llamará a la función callback una vez que se haya cargado la biblioteca.

Al configurar la función init de esta manera (añadiendo una función de callback, consulta “YOUR_CALLBACK” en el ejemplo a continuación) puedes establecer algunas acciones adicionales después de que se haya cargado la biblioteca.

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

A continuación, se muestran los parámetros que puedes utilizar dentro del objeto de configuración init (es decir, el primer parámetro en la función init que contiene la clave API) para personalizar, por ejemplo, el logger o el comportamiento de la biblioteca.

Consulta la tabla y el ejemplo de código a continuación:

// 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
}, ...]);

Para registrar automáticamente los consentimientos proporcionados a través de un formulario de envío, puedes usar la función load o la función submit.

3.1 load

La función load te permite vincular los campos del objeto consent a los campos de entrada de tu

y registrar automáticamente el consentimiento en el momento del envío.

Nota: la función load tan solo se debe invocar después de la declaración del objeto form (tal y como se puede ver en el siguiente ejemplo).

Te recomendamos insertar la etiqueta <script> después de la etiqueta <form>, así:

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

Parámetros:

El código en el ejemplo anterior registrará automáticamente el objeto consent con los valores de los campos de entrada vinculados:

• cuando submitElement recibe un evento click (si se ha especificado submitElement); o
• cuando se llama a la función _iub.cons.sendData() manualmente (ver a continuación)

3.1.1 sendData

La función sendData debe utilizarse junto con la función load y activa el registro del objeto consent con los valores de los campos de entrada que han sido vinculados por una llamada anterior a la función load.

Debe utilizarse cuando no se proporcione submitElement (por ejemplo, cuando tengas que validar un formulario de entrada antes del envío), y tienes que activar mediante programación la obtención de los datos del formulario y el consiguiente registro del consentimiento.

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

3.1.2 sendFromLocalStorage

De forma predeterminada, el objeto consent creado por la función load no se envía directamente a nuestros servidores para su almacenamiento. De hecho, se guarda en localStorage para protegerlo de cualquier pérdida de datos en caso de que se cargue una nueva página antes de que JavaScript haya terminado de ejecutarse. El consentimiento guardado en localStorage se registrará automáticamente (es decir, se enviará a nuestros servidores para su almacenamiento) en la siguiente carga de la página.

Si quieres desactivar el envío automático del consentimiento guardado en localStorage al cargar la página, tienes que proporcionar el parámetro sendFromLocalStorageAtLoad = false dentro de la configuración del objeto init. En estos casos, para enviar el consentimiento almacenado en localStorage a nuestros servidores, tendrás que llamar explícitamente a la función _iub.cons.sendFromLocalStorage (como puedes ver a continuación).

_iub.cons.sendFromLocalStorage()

3.2 submit

La función submit te permite enviar los datos de consentimiento a las API de iubenda, es decir, registrar el consentimiento de forma programática (por ejemplo, dentro de un controlador de eventos o una función de callback):

Se puede configurar de dos formas distintas:

• Especificando el parámetro selector del formulario de la misma manera que la función load.
• Especificando todos los valores del objeto consent.

Merece la pena destacar que, a diferencia de la función load, de forma predeterminada, la función submit no aprovecha la función localStorage y, en cambio, envía directamente el objeto consent a nuestro servidor para su almacenamiento.

Parámetros:

Callbacks

El callback .success se llama en caso de éxito y el callback .error se llama en caso de error.

3.2.1 Cuando se proporciona el objeto de formulario

En el siguiente ejemplo (en el que se proporciona el objeto form), la función submit se encargará de completar el objeto consent a partir de las entradas del formulario.

_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 Cuando no se proporciona el objeto de formulario

Alternativamente, también puedes pasar el objeto consent como se muestra en el siguiente ejemplo:

_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=\"/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);
    }
  }
])

Este es un ejemplo de una respuesta (en este caso, es una respuesta de éxito) del servidor:

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

Si quieres construir programáticamente el objeto consent y enviarlo a la API de la Consent Database, tienes que utilizar la función submit, tal y como se describió previamente en el apartado 3.2.2 Cuando no se proporciona el objeto de formulario.

Esta es la estructura del objeto form pasado a las funciones load y submit:

5.1 Vincular los campos del formulario al objeto consent

Los campos del formulario se pueden vincular a tu objeto consent de dos formas distintas:

1) Especificando el atributo name relevante en el objeto MAP (ten en cuenta que no puedes utilizar id aquí, tan solo el atributo 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) Utilizando los atributos data-cons-x en tu campo de entrada:

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

También puedes excluir ciertos campos (como por ejemplo, la contraseña o campos no relacionados con el consentimiento) de dos formas distintas:

1) Utilizando data-cons-exclude en tu campo de entrada:

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

2) Utilizando el objeto exclude dentro del mapa:

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

El objeto consent está compuesto por los siguientes campos:

Nota: en la biblioteca JS, todas las propiedades deben estar especificadas desde dentro del objeto consent. Ejemplo:

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=\"/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>"
    }
   ]
}

Si utilizas iubenda para generar tus documentos legales, nosotros actualizaremos automáticamente los contenidos de legal_notices por ti cada vez que cambien tus documentos legales. Puedes consultar cómo activar esta función aquí.

Sin embargo, todavía es obligatorio declarar qué legal_notices se aceptaron en cada creación de consentimiento, por lo tanto, si estás utilizando avisos legales, debes completar el array legal_notices con el identificador y la versión de tus avisos legales creados de antemano.

Ejemplo:

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

A continuación, se incluyen algunos ejemplos prácticos de cómo puedes implementar la Consent Database.

8.1 Función MAP

Función load

Consulta el Pen [Iubenda Cons] (async) Load function por iubenda (@iubenda) en CodePen.

Función load con Mapa (sin atributo de datos)

Consulta el Pen [Iubenda Cons] (async) Load function and Map option por iubenda (@iubenda) en CodePen.

8.2 Implementación del submit (asíncrona)

Consulta el Pen [Iubenda Cons] (async) Submit implementation por iubenda (@iubenda) en CodePen.

8.3 Implementación de varios formularios

Consulta el Pen [Iubenda Cons] (async)Multiple Form implementation por iubenda (@iubenda) en CodePen.

8.4 Herramientas de validación externas (función Load con validate.js)

Consulta el Pen [Iubenda Cons] (async) load function with validate.js por iubenda (@iubenda) en CodePen.