Consentl para qualquer site

Acrescente uma tag script em primeiro lugar no <head> do seu site. O banner, os textos, as regiões, o Consent Mode e o bloqueio são configurados no painel.

Loader em primeiro lugar no <head>

Sim

O Consentl funciona em qualquer site que permita acrescentar um <script> ao <head>. Não há nada a instalar no seu servidor: tudo é configurado no painel do Consentl (site externo) e entregue pelo script do loader.

O que faz cada plano

No plano Free, as tags Google, o Meta Pixel e todas as outras tags são executadas logo que a página carrega, a menos que as marque manualmente.

1. Adicionar o seu site e copiar a chave

1. Inicie sessão no painel (ou crie uma conta gratuita) e adicione o seu site.
2. Adicione todos os nomes de anfitrião em que o site funciona no campo Domínios do site. www. e o domínio sem www contam como o mesmo site; adicione os domínios de staging separadamente.
3. Abra a página Configuração do site e copie o fragmento de instalação. A chave do site que contém começa por sk_ e é pública: identifica o seu site, não é uma palavra-passe.

2. Instalar o loader

<script src="https://api.consentl.com/v1/loader.js?k=SITE_KEY&l=LANG"></script>

• SITE_KEY: a sua chave do site (sk_ + 24 caracteres).
• LANG: o idioma da página, o mesmo valor de <html lang>: en, de, fr, pt-PT, pt-BR, fr-CA, … As variantes regionais recorrem automaticamente ao idioma base (de-AT → de). Omita &l= para utilizar o idioma predefinido do site definido no painel.

Onde: como primeiro elemento no <head>, imediatamente a seguir a <meta charset>. Tem de vir antes do Google Tag Manager, gtag.js, Meta Pixel, ferramentas de estatísticas, widgets de chat e ferramentas de testes A/B.

Como: síncrono: sem async, sem defer, sem type="module". O script é pequeno e fica em cache.

Porquê em primeiro lugar e síncrono:

1. As predefinições do Google Consent Mode v2 (Pro e superiores) têm de estar definidas antes de qualquer tag Google as ler.
2. O bloqueio impede a execução das tags até o visitante concordar. Os scripts acima do loader já foram executados.
3. A escolha de um visitante que regressa é aplicada de imediato: sem o banner a aparecer brevemente e sem tags acionadas antes de a escolha ser conhecida.

Se a sua plataforma não permitir colocar o script em primeiro lugar, o respetivo guia explica exatamente o que isso significa.

O que o bloqueio pode e não pode impedir

• As tags carregadas por código (Google Tag Manager, o loader JavaScript de um píxel, scripts que a sua aplicação acrescenta) são retidas antes de serem pedidas quando correspondem a um rastreador conhecido (Business) ou a uma das suas regras de bloqueio.
• As tags escritas no HTML da página (<script src>, píxeis <img>, <iframe>) são pedidas pelo navegador antes de qualquer script as poder travar: enquanto o loader é transferido, o navegador já obtém o que encontra mais abaixo na página. O Consentl continua a impedir a execução de um script reconhecido, mas o pedido, com o endereço IP do visitante, o endereço da página e eventuais cookies de terceiros, já foi enviado; no caso de um píxel de rastreio, o pedido é o próprio rastreio. Marque manualmente todas as tags escritas no HTML (secção 6) e elimine os píxeis de rastreio em <noscript>.
• Os sites gerados no servidor podem também incorporar o loader inline, o que elimina a espera pela transferência. As tags escritas no HTML continuam a ter de ser marcadas.

3. Verificar que funciona

1. Abra o site numa janela privada. O banner aparece.
2. Nas ferramentas de programador do navegador → Console:
   • Consentl.get() devolve as escolhas atuais;
   • Consentl.region() devolve o modelo jurídico aplicado ao visitante, por exemplo { mode: "opt_in", law: "gdpr", gpc: false, known: true }.
3. Em Network, antes de aceitar:
   • nenhum pedido para anfitriões de rastreio a partir de tags carregadas por código, quando o bloqueio automático está ativado (Business); com o Consent Mode, apenas os pings sem cookies da Google;
   • as tags escritas no HTML que não marcou são pedidas. Marque-as e verifique novamente.
4. Enquanto o site estiver em modo de teste, acrescente ?consentl=preview a um endereço para ver o banner sem guardar nem registar uma escolha. Não escolhe uma região: a Pré-visualização do painel mostra o banner de cada região.

Regiões: em cada visualização de página, o banner pede ao Consentl o país do visitante, que é determinado a partir do endereço IP do visitante. A consulta é feita em memória e não guarda nada, e o loader é o mesmo para todos os visitantes. Aplica-se a sua regra para esse país:

• Os estados dos EUA não são distinguidos: um visitante dos EUA recebe a sua regra para todos os EUA ou, se não existir, a sua primeira regra para um estado dos EUA (por exemplo, a Califórnia).
• Quando o país é desconhecido, aplica-se a sua regra para regiões desconhecidas (opt-in por predefinição).
• O código está no campo consentl.region da dataLayer (por exemplo, DE ou US). Para ver o banner de outra região, utilize a Pré-visualização do painel ou uma VPN.

4. Acrescentar uma ligação «Definições de cookies»

Retirar o consentimento tem de ser tão fácil como dá-lo. Utilize qualquer uma destas opções:

<a href="#consentl">Cookie settings</a>
<button type="button" data-consentl-open>Cookie settings</button>

window.Consentl.open("prefs");

As ligações cujo endereço termina em #consentl ou #consentl-preferences, e qualquer elemento com data-consentl-open, abrem as preferências em vez de navegar, também em elementos acrescentados mais tarde. As outras âncoras que apenas começam da mesma forma (como #consentl-api) não são afetadas. O painel também pode mostrar um ícone flutuante de preferências.

5. Declaração de cookies, pedidos relativos a dados pessoais e formulário de livre resolução da UE

<div data-consentl-declaration data-api="https://api.consentl.com" data-key="SITE_KEY" data-locale="LANG"></div>
<div data-consentl-request      data-api="https://api.consentl.com" data-key="SITE_KEY" data-locale="LANG"></div>
<div data-consentl-withdrawal   data-api="https://api.consentl.com" data-key="SITE_KEY" data-locale="LANG"></div>
<script src="https://api.consentl.com/v1/blocks.js" defer></script>

Inclua blocks.js uma vez por página, depois dos <div>. A declaração lista os cookies da página Cookies do painel: o analisador acrescenta o que encontra quando o site é criado, quando clica em Analisar agora e, no plano Business e superiores, todos os meses; pode acrescentar ou editar entradas pessoalmente (os pormenores são preenchidos a partir da Open Cookie Database). Os pedidos relativos a dados pessoais são verificados por e-mail e aparecem no painel com o respetivo prazo. O formulário de livre resolução da UE exige o plano Pro ou superior e tem de ser ativado no painel; caso contrário, o respetivo <div> fica vazio.

6. Reter tudo o que não é reconhecido automaticamente

<script type="text/plain" data-consentl="marketing" src="https://ads.example.com/tag.js"></script>
<script type="text/plain" data-consentl="analytics">/* inline code */</script>
<iframe data-consentl="marketing" data-src="https://www.youtube-nocookie.com/embed/ID" title="Video"></iframe>
<img data-consentl="marketing" data-src="https://tracker.example.com/pixel.gif" alt="" width="1" height="1">

• Categorias: preferences, analytics, marketing.
• Nada é pedido até a categoria ser concedida. Esta é a única forma de reter uma tag escrita no HTML.
• Acrescente data-consentl-type="module" a um script marcado que tenha de ser executado como módulo.
• O bloqueio manual funciona em todos os planos. O plano Business acrescenta o bloqueio automático de rastreadores conhecidos e regras de bloqueio («o URL contém») que acrescenta no painel sem mexer no site. As regras correspondem ao endereço de scripts, iframes e imagens, e aos scripts inline que carregam algo. Os dados de página de frameworks como Next.js, Nuxt, Remix ou SvelteKit nunca são retidos.
• Uma tag retida é executada uma vez após o consentimento, mesmo que a sua framework acrescente uma segunda cópia dela durante o arranque da página (o Nuxt fá-lo).

Aplicações de página única

• Não é preciso chamar nada nas mudanças de rota: o runtime é carregado uma vez por documento, a escolha é guardada no cookie próprio consentl e as tags retidas são libertadas sem recarregar a página.
• Os routers que substituem o corpo da página (Astro <ClientRouter />, Turbo, Swup, htmx hx-boost) mantêm o banner, o ícone flutuante e as ligações «Definições de cookies» a funcionar.
• Mantenha o endereço do loader igual em todas as páginas e não o carregue novamente durante a navegação. Se o seu criador de sites oferecer «carregar em todas as páginas», escolha «carregar uma vez».
• As tags que a sua aplicação insere mais tarde também são retidas quando correspondem a um rastreador conhecido (Business) ou a uma regra de bloqueio. No seu próprio código, verifique o consentimento. consentl:change é disparado em cada visualização de página com as escolhas atuais e novamente em cada alteração, pelo que deve iniciar tudo apenas uma vez:

let started = false;
const maybeStart = (c) => {
  if (c.analytics && !started) {
    started = true;
    startAnalytics();
  }
};
document.addEventListener("consentl:change", (e) => maybeStart(e.detail));
if (window.Consentl) maybeStart(window.Consentl.get());

• Depois de uma mudança de idioma sem recarregamento completo, o banner mantém o seu idioma até ao próximo carregamento de página.

Com o Google Tag Manager

O modelo Consentl para o GTM pode assumir o Google Consent Mode. Se o utilizar e também o fragmento de código, acrescente &gcm=ext ao endereço do loader, para que só o modelo envie comandos do Consent Mode:

<script src="https://api.consentl.com/v1/loader.js?k=SITE_KEY&l=LANG&gcm=ext"></script>

Bootstrap inline (do lado do servidor)

Se as suas páginas forem geradas num servidor que controla, pode escrever o loader inline em vez de o ligar, tal como fazem os plugins Consentl para WordPress, Shopware, PrestaShop e Magento:

1. No servidor, obtenha https://api.consentl.com/v1/loader.js?k=SITE_KEY&l=LANG.
2. Guarde a resposta em cache por chave do site e idioma durante 5 minutos (o respetivo Cache-Control); se uma obtenção posterior falhar, continue a servir a última cópia válida.
3. Escreva <script> + a resposta + </script> como primeiro elemento no <head>. Com uma Content Security Policy, acrescente o seu nonce (o conteúdo muda com as suas definições, pelo que um hash não funciona).
4. Se não existir nenhuma cópia em cache, escreva a tag normal <script src="…">.

// Node, simplified
const cache = new Map(); // url -> { body, until }
async function consentlHead(key, lang) {
  const url = `https://api.consentl.com/v1/loader.js?k=${encodeURIComponent(key)}&l=${encodeURIComponent(lang)}`;
  const hit = cache.get(url);
  if (!hit || hit.until < Date.now()) {
    try {
      const r = await fetch(url);
      if (r.ok) cache.set(url, { body: await r.text(), until: Date.now() + 300_000 });
    } catch {
      /* keep the stale copy */
    }
  }
  const body = cache.get(url)?.body;
  return body ? `<script>${body}</script>` : `<script src="${url}"></script>`;
}

Não altere a resposta: é gerada pelo Consentl para o seu site. Escreva-a no modelo HTML que o seu servidor gera, fora de qualquer framework do lado do cliente. Não se aplica ao App Router do Next.js: aí, o React enviaria o loader duas vezes em cada página; utilize a tag simples, como indicado em Next.js.

API JavaScript

Eventos em document (as escolhas estão em event.detail):

• consentl:change: em cada visualização de página depois de aplicada a regra da região, e em cada alteração;
• consentl:ready: uma vez por visualização de página, depois do primeiro consentl:change;
• consentl:ui-error: não foi possível carregar o banner (também após uma nova tentativa). As ligações para #consentl funcionam então como ligações normais, para que possa mostrar a sua própria alternativa.

A dataLayer recebe consentl_consent (em cada visualização de página e em cada alteração) e consentl_update (apenas alterações), cada um com consentl.preferences, analytics, marketing, sale, stored e region. Elementos marcados: data-consentl="<category>", type="text/plain", data-src, data-consentl-srcset (imagens com srcset), data-consentl-type. Acrescente data-consentl-noicon a um elemento nas páginas que têm o seu próprio botão «Definições de cookies», para ocultar aí o ícone flutuante.

Content Security Policy

Se o seu site enviar um cabeçalho Content-Security-Policy, permita a API do Consentl:

script-src  'self' https://api.consentl.com;
connect-src 'self' https://api.consentl.com;
img-src     'self' https://api.consentl.com data:;
style-src   'self' 'unsafe-inline';

• style-src 'unsafe-inline' é necessário porque o banner acrescenta os seus estilos durante a execução. Contacte o suporte se a sua política proibir estilos inline.
• Os scripts que o Consentl liberta após o consentimento continuam a precisar dos seus próprios anfitriões em script-src.
• Com uma política de nonce estrita, atribua o seu nonce à tag do loader e utilize 'strict-dynamic', para que os scripts que este carrega e liberta sejam considerados fiáveis. Sem 'strict-dynamic', atribua também o seu nonce aos scripts inline marcados.
• O Subresource Integrity (SRI) não pode ser utilizado no loader, porque o seu conteúdo muda quando altera as definições no painel.

Verificações do lado do servidor (opcional)

A escolha é guardada no cookie próprio consentl: 1.<id>.<timestamp>.<revision>.<flags>.<action>. flags tem quatro algarismos para preferences, analytics, marketing e sale (1 = concedido). A ausência de cookie significa que ainda não há decisão: trate-a como «não concedido». Um cookie com uma revisão mais antiga (depois de «Repor todos os consentimentos») deixa de contar. As páginas que dependem deste cookie não podem ser guardadas numa cache partilhada. Sempre que possível, prefira o controlo do lado do cliente (secção 6).

Limitações

• O banner não consegue controlar os scripts executados antes do loader: os scripts acima dele no <head> e os scripts que uma plataforma de alojamento injeta fora do seu controlo.
• As tags escritas no HTML da página são pedidas antes do consentimento, a menos que as marque.
• Os iframes de terceiros incorporados (vídeos, mapas) são retidos na totalidade até ao consentimento. O Consentl não consegue ver o que acontece dentro deles.
• O Consentl não implementa o IAB Transparency & Consent Framework (TCF).

Guias relacionados

• Google Tag Manager
• Next.js
• React, Vue, Angular (SPA)
• Webflow

Com dificuldades? Escreva para support@consentl.com — respondemos em inglês nos dias úteis.