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

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