Consent Database – Documentação JS

Para instalar o widget Consent Database JS, insira o seu código do Consent Database em cada página do seu site, antes de fechar a tag HEAD (veja o código de exemplo abaixo).

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

*A chave da API é um código exclusivo que o SDK usa para se comunicar com o endpoint da nossa API. Sua chave de API (exibida como “YOUR_PUBLIC_API_KEY” no exemplo acima) é gerada por nós durante a ativação do Consent Database e é específica para esse site.

A função init (incluída no script de configuração acima) define como a biblioteca é instanciada e é necessária em todas as páginas que implementam o widget do Consent Database.

É possível adicionar uma função de retorno de chamada como um segundo parâmetro da função init. A função de retorno de chamada será então chamada assim que a biblioteca for carregada.

Configurar a função init dessa maneira (adicionando uma função de retorno de chamada — veja “YOUR_CALLBACK” no exemplo abaixo) pode ser usado para definir alguma ação adicional após o carregamento da 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 seguir estão os parâmetros que você pode usar no objeto de configuração init (ou seja, o primeiro parâmetro na função init que contém a chave da API) para personalizar, por exemplo, o registrador ou o comportamento da biblioteca.

Veja a tabela e o exemplo de código abaixo:

// 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 automaticamente os consentimentos fornecidos por meio de um formulário de envio, você pode usar a função load ou a função submit.

3.1 load

A função load permite que você vincule campos do objeto consent aos campos de entrada do seu <form> e registre automaticamente o consentimento no momento do envio.

Observação: a função load deve ser invocada somente após a declaração do objeto form (como pode ser visto no exemplo abaixo).

Sugerimos inserir a tag <script> após a tag <form> da seguinte forma:

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

O código no exemplo acima gravará automaticamente o objeto consent com os valores dos campos de entrada vinculados:

• quando o submitElement recebe um evento click (se submitElement foi especificado); ou
• quando a função _iub.cons.sendData() é chamada manualmente (veja abaixo)

3.1.1 sendData

A função sendData deve ser usada em conjunto com a função load e aciona a gravação do objeto consent com os valores dos campos de entrada que foi vinculado por uma chamada anterior para a função load.

Deve ser usado caso o submitElement não seja fornecido (por exemplo, quando você precisa validar o formulário de entrada antes de enviar) e você precisa acionar programaticamente a busca dos dados do formulário e a conseqüente gravação do consentimento.

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

3.1.2 sendFromLocalStorage

Por padrão, o objeto consent criado pela função load não é enviado diretamente para nossos servidores para armazenamento; ele é realmente salvo no localStorage para proteger contra qualquer perda de dados caso uma nova página seja carregada antes que o JavaScript termine de executar. O consentimento salvo em localStorage será registrado automaticamente (ou seja, enviado para nossos servidores para armazenamento) no carregamento da próxima página.

Se você deseja desabilitar o envio automático do consentimento salvo em localStorage no carregamento da página, você precisa fornecer o parâmetro sendFromLocalStorageAtLoad = false dentro da configuração do objeto init; nesses casos, para enviar o consentimento armazenado em localStorage para nossos servidores, você precisará chamar explicitamente a função _iub.cons.sendFromLocalStorage (veja abaixo).

_iub.cons.sendFromLocalStorage()

3.2 submit

A função submit permite que você envie os dados de consentimento para as APIs iubenda, ou seja, para registrar o consentimento de forma programática (por exemplo, dentro de um manipulador de eventos ou uma função de retorno de chamada):

Pode ser configurado de duas maneiras:

• Especificando o parâmetro selector do formulário da mesma forma que a função load
• Especificando todos os valores do objeto consent

Vale a pena notar que, ao contrário da função load, por padrão a função submit não aproveita o localStorage e, em vez disso, envia diretamente o consent objeto ao nosso servidor para armazenamento.

Parâmetros:

Callbacks

O retorno de chamada .success é chamado em casos de sucesso, o retorno de chamada .error é chamado em casos de erro.

3.2.1 Quando o objeto de formulário é fornecido

No exemplo abaixo (onde o objeto form é fornecido), a função submit cuidará de preencher o objeto consent do entradas de formulário.

_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 o objeto de formulário não é fornecido

Alternativamente, você também pode passar o objeto consent conforme mostrado no exemplo abaixo:

_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 é um exemplo de resposta (neste caso, uma resposta de sucesso) do servidor:

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

Se você deseja construir o seu objeto consentprogramaticamente e enviá-lo para o Consent Database API, você precisará usar a função submit conforme descrito anteriormente em 3.2.2 Quando o objeto de formulário não é fornecido.

Esta é a estrutura do objeto form passado para load e funções submit:

5.1 Vinculando os campos do formulário ao seu objeto de consentimento

Os campos de formulário podem ser vinculados ao seu objeto consent de duas maneiras:

1) Ao especificar o atributo relevante name no objeto MAP (observe que id não pode ser usado aqui, apenas o 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) Usando atributos data-cons-x em seu 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>

Você também pode excluir determinados campos (ou seja, senha ou campos não relacionados ao consentimento) de duas maneiras:

1) Usando data-cons-exclude em seu campo de entrada:

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

2) Usando o objeto exclude dentro do mapa:

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

O objeto consent é composto pelos seguintes campos:

Observação: Na biblioteca JS, todas as propriedades devem ser especificadas de dentro do objeto consent. Exemplo:

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

Se você usar a iubenda para seus documentos legais, atualizaremos automaticamente o conteúdo do legal_notices para você sempre que os seus documentos legais forem alterados. Você pode ler sobre como habilitar esse recurso aqui.

No entanto, ainda é necessário que você declare quais legal_notices estão sendo acordados em cada criação de consentimento, portanto, se você estiver usando avisos legais, deverá preencher a matriz legal_notices com o identificador e a versão dos seus avisos legais criados previamente.

Exemplo:

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

Incluídos abaixo estão alguns exemplos práticos de como você pode realmente implementar o Consent Database.

8.1 MAP feature

Função Load

Veja a função Pen [Iubenda Cons] (async) Load function criada pela iubenda (@iubenda) no CodePen.

Função Load com Map (sem atributo de dados)

Veja a função Pen [Iubenda Cons] (async) Load function and Map option criada pela iubenda (@iubenda) no CodePen.

8.2 Enviar implementação (assíncrona)

Veja a implementação Pen [Iubenda Cons] (async) Submit criada pela iubenda (@iubenda) no CodePen.

8.3 Implementação de formulários múltiplos

Veja a implementação Pen [Iubenda Cons] (async)Multiple Form criada pela iubenda (@iubenda) no CodePen.

8.4 Ferramentas de validação externa (função Load com validate.js)

Veja a função de carregamento Pen [Iubenda Cons] (async) com validate.js criada pela iubenda (@iubenda) no CodePen.