Iubenda logo
Genera tus documentos

Documentación

Tabla de contenidos

Consent Solution: Documentación de JS

La biblioteca de JavaScript de la Consent Solution te permite registrar las acciones de consentimiento realizadas por los usuarios, a los que nos referiremos como “interesados” durante el resto de esta guía.

La biblioteca de JavaScript de la Consent Solution tiene las siguientes funciones:

  • Escribe directamente en la API de la Consent Solution (es decir, registra el consentimiento)
  • Escribe tanto de forma sincrónica como de forma asincrónica, aprovechando opcionalmente localStorage
  • Varias opciones de seguimiento del consentimiento. No solo puedes supervisar un formulario específico y rastrear el consentimiento en el momento del envío, sino que también puedes seguir el consentimiento por otros medios programáticos (por ejemplo, después de un proceso de validación o después de algún otro evento).
  • Es compatible con la mayoría de navegadores (IE8+)
  • Proporciona callbacks
  • Funciones de registro
Nota informativa

El 03/04/2019 se publicó una nueva versión del JS de la Consent Solution. Si instalaste la Consent Solution antes de esta fecha y quieres conseguir la última versión, consulta esta sección (al final de este artículo).

1. Script de configuración

Para instalar el widget del JS de la Consent Solution, inserta el código de la Consent Solution 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 usa para comunicarse con el punto final 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 Solution y es específica para ese sitio web en concreto.

Advertencia

El código anterior es solo un ejemplo. Asegúrate de estar utilizando tu propio código de la Consent Solution, ya que este código es específico para tu sitio web en concreto. Puedes encontrar tu fragmento de código entrando en tu Dashboard > [área de tu sitio web] > Consent Solution > INTEGRAR. Una vez allí, simplemente copia la información que necesites.

2. Configuración init

La función init (incluida en el script de configuració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 Solution.

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:

Nombre Obligatorio Tipo Notas
api_key Cadena de caracteres Tu clave pública
logger no Cadena de caracteres Valores posibles: “none”, “console”. Valor predeterminado: “console”
log_level no Cadena de caracteres Valores posibles: “none”, “debug”, “info”, “warn”, “error”, “fatal”. Valor predeterminado: “error”
sendFromLocalStorageAtLoad no boolean Determina si el script se lee localStorage al cargar y envía lo que esté incluido. Valor predeterminado: 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. Conectar la Consent Solution a un formulario de envío

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 campos del objeto consent a campos de entrada de tu <form> 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 ejemplo a continuación).

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:

Nombre Obligatorio Tipo Notas
submitElement no Cadena de caracteres o elemento DOM Pasa la cadena de caracteres ID o el elemento DOM de un elemento que activará el envío del consentimiento cuando se haga clic en él. Si este elemento no se especifica o no se activa, tienes que llamar _iub.cons.sendData() para registrar el consentimiento (puedes verlo también a continuación).
form No/Sí si consent no está definido FormConfig Consulta la sección del objeto form
consentimiento No/Sí si form no está definido ConsentConfig Consulta la sección del objeto consent
writeOnLocalStorage no boolean Define si los datos deberían enviarse directamente o escribirse en localStorage. Valor predeterminado: true
autodetect_ip_address no boolean Un parámetro que activa o desactiva la detección automática de la dirección IP. Valor predeterminado: true

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 especificó 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 el 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 en la carga de 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):

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

Se puede configurar de dos formas distintas:

  • Especificando el parámetro de formulario selector 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 localStorage y, en cambio, envía directamente el objeto consent a nuestro servidor para su almacenamiento.

Parámetros:

Nombre Obligatorio Tipo Notas
form No/Sí si consent no está definido FormConfig (Consulta la sección del objeto form a continuación)
consentimiento No/Sí si form no está definido ConsentConfig (Consulta la sección del objeto consent a continuación)
writeOnLocalStorage No boolean Define si los datos deberían enviarse directamente o escribirse en localStorage. Valor predeterminado: false
autodetect_ip_address No boolean Te permite activar o desactivar la detección automática de la dirección IP. Valor predeterminado: true
Nota

En aquellos casos en los que proporciones tanto el formulario como el parámetro de consentimiento, se combinarán para crear el objeto consent. En aquellos casos en los que haya un conflicto entre los datos recuperados del formulario y los datos especificados directamente en el objeto consent, el objeto consent tendrá preferencia.

Callbacks

El callback .success se llama en casos de éxito, el callback .error se llama en casos de error.

3.2.1 Cuando se proporciona el objeto de formulario

En el ejemplo a continuación (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 tu objeto consent y enviarlo a la API de la Consent Solution, 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.

5. FormConfig

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

Nombre Tipo Notas
selector Cadena de caracteres o elemento DOM El ID (cadena de caracteres) del formulario o el formulario del elemento DOM
map Objeto Objeto que te permite asignar los atributos consent a campos específicos del formulario a través de los atributos “nombre” en lugar de data-cons-x (consulta el ejemplo a continuación)
subject Objeto
id Cadena de caracteres atributo de nombre de un elemento DOM presente en el formulario
email Cadena de caracteres atributo de nombre de un elemento DOM presente en el formulario
first_name Cadena de caracteres atributo de nombre de un elemento DOM presente en el formulario
last_name Cadena de caracteres atributo de nombre de un elemento DOM presente en el formulario
full_name Cadena de caracteres atributo de nombre de un elemento DOM presente en el formulario
preferences Objeto
preference_name Cadena de caracteres atributo de nombre de un elemento DOM presente en el formulario
exclude Array Una lista de nombres de campos que nos gustaría excluir de las pruebas

5.1 Vincular los campos del formulario a tu objeto de consentimiento

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 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 campos determinados (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']
}

6. ConsentConfig

El objeto consent está compuesto por los siguientes campos:

Nombre Obligatorio Tipo Notas
subject Objeto
id No Cadena de caracteres Identificador para identificar al interesado que envió el consentimiento. Si se pasa un ID, se utiliza ese ID, y puedes actualizar la información de un interesado publicando nuevos consentimientos usando el mismo ID del interesado. Sin embargo, si no proporcionas un ID del interesado específico, la API creará al azar un UUID seguro.
email No Cadena de caracteres
first_name No Cadena de caracteres
last_name No Cadena de caracteres
full_name No Cadena de caracteres
verified No Boolean Campo reservado que indica si un interesado está verificado, por ejemplo, mediante el método de suscripción doble
legal_notices Array Array de objetos que contienen datos de legal_notices
identifier No Cadena de caracteres
version No Cadena de caracteres Se completa automáticamente si no se proporciona
proofs Array Array de objetos que contienen datos de las pruebas
content No Cadena de caracteres
form No Cadena de caracteres
preferences Objeto Conjunto de pares clave-valor con las preferencias del usuario para la acción de consentimiento

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 que declares 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"
    },
    ...
  ]
}

8. Ejemplos de implementación

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

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 (asincrónica)

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

8.3 Implementación de formularios múltiples

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

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

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

Cómo actualizar las instalaciones de la Consent Solution previas al 03/04/2019

Si has instalado la Consent Solution de iubenda antes del 03/04/2019, para usar la versión actual, tienes que actualizar el uso de las funciones init y load para incorporar la nueva función de carga asincrónica.

Se puede llamar a las funciones init o load en dos situaciones distintas:

  • Antes de que la biblioteca haya terminado de cargarse (carga asincrónica)
  • Después de que la biblioteca haya terminado de cargarse (carga síncrona)

Load

Antes:

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

Después:

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

Nota: este código debe colocarse después de tu elemento, como puedes ver en la sección anterior.

Init

Antes:

_iub.cons.init({api_key: "YOUR_PUBLIC_API_KEY"}, YOUR_CALLBACK_FUNCTION);

Después:

_iub.cons_instructions.push(["init", {api_key: "YOUR_PUBLIC_API_KEY"}, YOUR_CALLBACK_FUNCTION]);

Nota: la función init está integrada en tu script de configuración y no debería necesitar ninguna actualización por tu parte.

Más información