Iubenda logo
Crie Agora

Documentação

Tabela de conteúdos

Consent Solution – Documentação JS

A biblioteca JavaScript da Consent Solution permite que você grave ações de consentimento realizadas por seus usuários, que serão referidas como “assuntos” durante o resto deste guia.

A biblioteca JavaScript da Consent Solution tem as seguintes funcionalidades:

  • Escreve diretamente para a API da Consent Solution (ou seja, registra o consentimento)
  • Escreve tanto sincronizadamente quanto assincronicamente, permitindo a escolha localStorage
  • Várias opções de rastreamento de consentimento. Você não só pode monitorar um formulário específico e acompanhar o consentimento no envio, você também pode acompanhar o consentimento por outros meios programáticos (por exemplo, após um processo de validação ou após algum outro evento).
  • Suporta a maioria dos navegadores (IE8+)
  • Providencia callbacks
  • Recursos de registro
Aviso

Em 03/04/2019 foi lançada uma nova versão da Consent Solution JS; se você tiver instalado a solução antes dessa data e deseja passar para a nova versão, consulte esta seção (no final deste post).

1. Configurar o script

Para instalar o widget JS da Consent Solution, insira seu código da solução em cada página do seu site, antes de fechar a tag HEAD (veja o código do 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 API é um código único que o SDK usa para se comunicar com a nossa API. Sua chave de API (exibida como “YOUR_PUBLIC_API_KEY” no exemplo acima) é gerada por nós durante a ativação da Consent Solution e é específica para esse site em particular.

Atenção

O código acima é apenas um exemplo. Por favor, certifique-se de usar seu próprio código da Consent Solution, pois o código é específico para o seu site em particular. Você pode encontrar seu trecho de código indo para Dashboard > [área do seu site] > Consent Solution > INTEGRAR. Depois, apenas copie a informação necessária.

2. Configuração da função init

A função init (incluída no script de configuração acima) define como a biblioteca será instantânea e será necessária em todas as páginas que implementam o Consent Solution widget.

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

Configurar a função init desta forma (adicionando uma função de callback — veja “YOUR_CALLBACK” no exemplo abaixo) pode ser útil para definir uma 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 tecla API) para customizar, por exemplo, o logger ou o comportamento (funcionamento) da biblioteca.

Veja a tabela e exemplo de código abaixo:

Nome Exigido Tipo Observações
api_key sim String Sua chave pública
logger não String Valores possíveis: “none”, “console”. Padrão: “console”
log_level não String Valores possíveis: “none”, “debug”, “info”, “warn”, “error”, “fatal”. Padrão: “error”
sendFromLocalStorageAtLoad não boolean Determina se o script está como localStorage e envia o que está incluído. Padrão: 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 a Consent Solution a um formulário de submissão

Para registrar automaticamente os consentimentos fornecidos através de um formulário de submissão, você pode usar a função load ou a função submit.

3.1 load

A função load permite vincular campos do objeto consent aos campos de entrada do seu <form> e registrar automaticamente o consentimento no momento do envio.

Observação: a função load deve ser apenas invocada depois da declaração do objeto form (como pode ser visto no exemplo abaixo).

Sugerimos inserir a tag <script> depois da tag <form> como mostrado abaixo:

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

Nome Exigido Tipo Observações
submitElement não String ou elemento DOM Passe a string de Id ou o elemento DOM de um elemento que acionará o envio do consentimento, quando clicado. Se esse elemento não for especificado ou não for acionado, você precisa chamar _iub.cons.sendData() para registrar o consentimento (veja também abaixo).
form Não/Sim se consent não for definido FormConfig Confira a seção do objeto form
consentimento Não/Sim se form não for definido ConsentConfig Confira a seção do objeto consent
writeOnLocalStorage não boolean Define se os dados devem ser enviados diretamente ou escritos em localStorage. Padrão: true
autodetect_ip_address não boolean Um parâmetro que habilite ou desabilite o autodetect ip. Padrão: true

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

  • quando o submitElement recebe o evento click (se submitElement foi especificado); ou
  • quando a função _iub.cons.sendData() for manualmente adicionada (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 vinculados por uma chamada anterior à função load.

Ela deve ser usada 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 o consequente registro 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 aos nossos servidores para armazenamento; ele é salvo no localStorage para proteger de qualquer perda de dados caso uma nova página for carregada antes que o JavaScript termine de executar. O consentimento salvo no localStorage será gravado automaticamente (ou seja, enviado aos nossos servidores para armazenamento) na próxima carga da página.

Se você deseja desativar o envio automático do consentimento salvo no localStorage carga da página, você precisa fornecer o parâmetro sendFromLocalStorageAtLoad = false na configuração do objeto init; nesses casos, para enviar o consentimento armazenado no 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 enviar os dados de consentimento para APIs da iubenda, ou seja, registrar o consentimento, programaticamente (por exemplo, dentro de um manipulador de eventos ou uma função de retorno de chamada):

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

Isso pode ser configurado de duas maneiras:

  • Especificando o form selector parâmetro da mesma maneira que a função load
  • Especificando todos os valores do objeto consent

Vale ressaltar 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 objeto consent para o nosso servidor para armazenamento.

Parâmetros:

Nome Exigido Tipo Observações
form Não/Sim se consent não for definido FormConfig (Veja a seção do objeto form abaixo)
consent Não/Sim se form não for definido ConsentConfig (Veja a seção do objeto consent abaixo)
writeOnLocalStorage Não boolean Define se os dados devem ser enviados diretamente ou escritos para localStorage. Padrão: false
autodetect_ip_address Não boolean Permite que você habilite ou desabilitar o autodetect ip. Padrão: true
Observação

Nos casos em que você fornece o form e o parâmetro de consentimento, eles serão fundidos para criar o objeto consent. Nos casos em que houver conflito entre dados recuperados do form e os dados especificados diretamente no objeto consent, o objeto consent terá precedência.

Callbacks

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

3.2.1 Quando o objeto form é fornecido

No exemplo abaixo (onde o objeto form é fornecido), a função submit cuidará de preencher o objeto consent a partir das entradas de 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 o objeto form não é fornecido

Alternativamente, você também pode passar o objeto consent como 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"
}

4. Construa programaticamente e registre seu objeto de consentimento

Se você quiser construir programaticamente seu objeto consent e enviá-lo para a API da Consent Solution, você precisará usar a função submit como descrito anteriormente em 3.2.2 Quando o objeto de formulário não for fornecido.

5. FormConfig

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

Nome Tipo Observações
selector String ou elemento DOM O ID (string) do form ou o form do elemento DOM
map Objeto Objeto que permite mapear atributos consent para campos de formulário específicos por seus atributos de “nome” como uma alternativa aos atributos data-cons-x (veja exemplo abaixo)
subject Objeto
id String atributo nome de um elemento DOM presente no form
email String atributo nome de um elemento DOM presente no form
first_name String atributo nome de um elemento DOM presente no form
last_name Last_name atributo nome de um elemento DOM presente no form
full_name String atributo nome de um elemento DOM presente no form
preferences Objeto
preference_name String atributo nome de um elemento DOM presente no form
exclude Array Uma lista de nomes de campos que gostaríamos de excluir de provas

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

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

1) Especificando o atributo name relevante 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 certos 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']
}

6. ConsentConfig

O objeto consent é composto pelos seguintes campos:

Nome Exigido Tipo Observações
subject Sim Objeto
id Não String Identificador para identificar o titular que enviou o consentimento. Se um ID for aprovado, ele é usado e você pode atualizar uma informação de titular postando novos consentimentos usando o mesmo ID do titular. No entanto, se você não fornecer um ID de um titular específico, o API criará um UUID aleatório seguro para você.
email Não String
first_name Não String
last_name Não String
full_name Não String
verified Não Boolean Campo reservado usado para sinalizar se um titular é verificado, por exemplo, através do método de dupla inscrição (opt-in)
legal_notices Sim Array Matriz de objetos contendo dados legal_notices
identifier Não String
version Não String Preenchido automaticamente caso não for fornecido
proofs Sim Array Matriz de objetos contendo dados de prova
content Não String
form Não String
preferences Sim Objeto Conjunto de pares de valor-chave com preferências do usuário para a ação de consentimento

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

7. Avisos legais

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

No entanto, você ainda deve declarar quais legal_notices estão sendo acordados em cada criação de consentimento, portanto, se você estiver usando avisos legais, você deve preencher o array legal_notices com o identificador e a versão de seus avisos legais criados antecipadamente.

Exemplo:

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

8. Exemplos de implementação

Abaixo estão alguns exemplos práticos de como você pode implementar a Consent Solution.

8.1 Funcionalidade MAP

Função load

Veja a Pen [iubenda Cons] (async) Função load pela iubenda (@iubenda) em CodePen.

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

Veja a Pen [iubenda Cons] (async) Função load e opção Map pela iubenda (@iubenda) em CodePen.

8.2 Submeter a implementação (async)

Veja a Pen [iubenda Cons] (async) Submeter implementação pela iubenda (@iubenda) em CodePen.

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

Veja a Pen [iubenda Cons] (async) Implementação de formulários múltiplos pela iubenda (@iubenda) em CodePen.

8.4 Ferramentas de validação externa (Função load com validação.js)

Veja a Pen [iubenda Cons] (async) Função load com validação.js pela iubenda (@iubenda) em CodePen.

Como atualizar as instalações da ConS realizadas antes de 03/04/2019

Se você instalou a Consent Solution da iubenda antes de 03/04/2019, a fim de usar a versão atual, atualize as funções init e load para acomodar a nova funcionalidade de carregamento assíncrono.

As funções init ou load podem ser chamadas em dois cenários:

  • Antes que a biblioteca termine o carregamento (carregamento assíncrono)
  • Depois que a biblioteca terminar o carregamento (carregamento síncronos)

Load

Antes:

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

Depois:

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

Observação: este código deve ser colocado após o seu elemento, ref. para a seção load acima.

Init

Antes:

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

Depois:

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

Observação: a função init está integrada ao seu script de configuração e não deve precisar de nenhuma atualização sua.

Veja também