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:
localStorage
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).
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.
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.
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
}, ...]);
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
.
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:
submitElement
recebe o evento click
(se submitElement
foi especificado); ou_iub.cons.sendData()
for manualmente adicionada (veja abaixo)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();
// ...
}
}
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()
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:
selector
parâmetro da mesma maneira que a função load
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 |
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.
O callback .success
é chamado em casos de sucesso, o callback .error
é chamado em casos de erro.
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);
}
}
])
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"
}
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.
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 |
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 |
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']
}
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ê. |
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>"
}
]
}
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"
},
...
]
}
Abaixo estão alguns exemplos práticos de como você pode implementar a Consent Solution.
Veja a Pen [iubenda Cons] (async) Função load pela iubenda (@iubenda) em CodePen.
Veja a Pen [iubenda Cons] (async) Função load e opção Map pela iubenda (@iubenda) em CodePen.
Veja a Pen [iubenda Cons] (async) Submeter implementação pela iubenda (@iubenda) em CodePen.
Veja a Pen [iubenda Cons] (async) Implementação de formulários múltiplos pela iubenda (@iubenda) em CodePen.
Veja a Pen [iubenda Cons] (async) Função load com validação.js pela iubenda (@iubenda) em CodePen.
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:
_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.
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.