Referência do snippet: configurar e personalizar

aidisclose.js é o script que corre no site, lê o seu manifesto ai-disclosure.json e apresenta as divulgações que a lei exige: um banner de interação para chatbots, um aviso de conteúdo persistente, rótulos visíveis em conteúdos multimédia marcados e metadados de página legíveis por máquina. Não tem dependências, ocupa cerca de 8.2 KB comprimido em gzip e cumpre o nível WCAG 2.1 AA.

Esta página é a referência completa de configuração e personalização. Para os passos de instalação plataforma a plataforma (WordPress, Shopify, Webflow, gestores de etiquetas), consulte o guia de instalação. Também pode ler este documento em markdown simples.

Visão geral

Uma única tag de script comanda tudo. Ao carregar, o snippet obtém o seu manifesto e apresenta apenas aquilo que o manifesto declara:

Banner de interação, para um sistema conversational: um aviso de que o visitante está a falar com uma IA.
Aviso de conteúdo, para um sistema content-generation com scope: site ou scope: page: um pequeno chip persistente. Ao clicar nele, abre-se uma explicação curta com o texto do aviso, o nome do seu editor e a finalidade do sistema, obtidos do manifesto, e uma ligação para o ficheiro do manifesto; o texto do aviso liga a uma explicação em linguagem clara em aidisclose.io. O selo "feito por humanos" abre o mesmo cartão com o nome do editor.
Rótulos por elemento, em qualquer elemento que marque com data-ai-content: um selo "IA" visível, mais um data-digital-source-type legível por máquina.
Metadados de página: um <link rel="ai-disclosure"> e um <meta name="ai-disclosure"> que apontam para o seu manifesto.
Selo "feito por humanos", quando o manifesto define noAiDeclared.

Tudo o que se segue é opcional. Sem qualquer configuração, o snippet lê o seu /.well-known/ai-disclosure.json, apresenta o conteúdo na língua do visitante em 28 idiomas, segue a preferência de tema claro ou escuro do sistema operativo e empilha-se acima das barras de consentimento de cookies conhecidas, de modo a que as duas nunca se sobreponham.

Instalação

Adicione a tag uma única vez, no template partilhado do seu site, no cabeçalho do tema ou no gestor de etiquetas, e ela passa a acompanhar todas as páginas. Pode ficar no <head> ou em qualquer ponto antes de </body>; é diferida, por isso o posicionamento não altera o comportamento:

<script src="https://cdn.aidisclose.io/v1/aidisclose.js" defer></script>

Sem atributos, o snippet lê o manifesto em https://YOURDOMAIN/.well-known/ai-disclosure.json. Se a sua plataforma não conseguir servir um ficheiro na raiz do domínio, aloje o manifesto na AIDisclose e aponte a tag para ele por chave:

<script src="https://cdn.aidisclose.io/v1/aidisclose.js" data-aidisclose="YOUR_SITE_KEY" defer></script>

Se o manifesto não puder ser acedido, o snippet regista um aviso na consola e não apresenta nenhum aviso baseado no manifesto, pelo que uma falha de obtenção nunca mostra um aviso adivinhado. Os metadados de página, os seus rótulos [data-ai-content] e um banner forçado com data-banner="true" continuam a ser apresentados.

Configuração

Há três formas de configurar o snippet. Use a que melhor se adequar à sua plataforma.

1. Atributos na tag de script. O caminho mais simples, sem código adicional:

<script src="https://cdn.aidisclose.io/v1/aidisclose.js"
        data-theme="light" data-lang="fr" defer></script>

2. Um objeto de configuração global. Defina window.AIDiscloseConfig antes de o script correr. Ele expõe o conjunto completo de opções, incluindo as opções de seletor que não têm forma de atributo:

<script>
  window.AIDiscloseConfig = {
    theme: 'light',
    mountSelector: '#ai-disclosure-slot',
    triggerSelector: '#chat-launcher',
  };
</script>
<script src="https://cdn.aidisclose.io/v1/aidisclose.js" defer></script>

3. Inicialização manual. Adicione data-manual para adiar o arranque automático e, em seguida, chame AIDisclose.init() por si próprio, assim que a sua aplicação estiver pronta (útil em aplicações de página única):

<script src="https://cdn.aidisclose.io/v1/aidisclose.js" data-manual defer></script>
<script>
  AIDisclose.init({ theme: 'dark', persistentChip: false });
</script>

Se estiver presente mais do que uma fonte, prevalece window.AIDiscloseConfig: sobrepõe-se tanto aos atributos da tag de script como a qualquer objeto passado a AIDisclose.init().

Referência de opções

A superfície de opções é estável para a linha 1.x.

Option	Attribute	Values	Default	Effect
`theme`	`data-theme`	`light`, `dark`, `auto`	`auto`	Esquema de cores. `auto` segue a preferência do sistema operativo do visitante.
`siteKey`	`data-aidisclose`	string	none	Carrega o manifesto alojado na AIDisclose para esta chave, em vez do ficheiro well-known.
`manifestUrl`	`data-manifest-url`	URL	`/.well-known/ai-disclosure.json`	Lê o manifesto a partir de um URL personalizado.
`lang`	`data-lang`	código BCP-47	`<html lang>` da página, senão a língua do visitante	Força uma língua de apresentação.
`banner`	`data-banner`	`true`, `false`	auto	Força a ativação ou desativação do banner de interação. Se não for definido, aparece apenas quando o seu manifesto declara um sistema conversacional (chatbot).
`persistentChip`	—	`true`, `false`	`true`	Mostra ou suprime o mini-chip recolhido do banner de interação (a pequena pastilha para a qual ele é minimizado).
`alwaysShow`	—	`true`, `false`	`false`	Volta a mostrar o banner em cada visita, ignorando a dispensa do visitante (memorizada no `localStorage` do navegador).
`mountSelector`	—	seletor CSS	none	Apresenta o banner em linha dentro deste elemento, em vez da sobreposição fixa no fundo.
`triggerSelector`	—	seletor CSS	none	Mostra o banner de interação apenas depois de o visitante clicar neste elemento, como um botão de abertura do chat. As páginas sem elemento correspondente não mostram banner, pelo que um chatbot que exista apenas em algumas páginas só divulga nessas. Botões de abertura injetados após o carregamento também funcionam. Um visitante que tenha dispensado o banner anteriormente continua a ver o mini-chip.
`adjacentSelector`	—	seletor CSS	none	Coloca um rótulo junto a um elemento que não possa marcar diretamente, como um widget fechado ou um iframe.
`observe`	—	`true`, `false`	`true`	Observa o DOM à procura de conteúdo adicionado posteriormente e rotula-o. Defina como `false` em páginas totalmente estáticas.
`beaconUrl`	—	URL	none	Envia um beacon anónimo `{siteKey, flag}` em eventos relevantes. Sem cookies, sem dados pessoais.

data-manual não é um valor de opção: a sua presença na tag adia o arranque automático para que possa chamar AIDisclose.init() por si próprio.

Tema e aparência

Defina o esquema integrado com theme (light, dark ou auto). Para corresponder exatamente à sua marca, substitua as propriedades personalizadas CSS do snippet na sua própria folha de estilos. Estão definidas em .aid-banner, .aid-chip:

Variable	Controls
`--aid-bg`	Fundo
`--aid-fg`	Texto
`--aid-line`	Contorno
`--aid-btn`	Contorno do botão de dispensa
`--aid-btnfg`	Texto do botão de dispensa
`--aid-hov`	Passagem do rato sobre o botão de dispensa

.aid-banner, .aid-chip {
  --aid-bg: #0b1020;
  --aid-fg: #e8eaed;
  --aid-line: #2a2f36;
}

O snippet não inclui regras !important e usa seletores de baixa especificidade, por isso o seu CSS prevalece. Os ganchos de classe são .aid-banner, .aid-chip, .aid-badge, .aid-badge-inline, .aid-wrap, .aid-ai (aviso de conteúdo) e .aid-hm ("feito por humanos"). Redefina espaçamento, raio e sombra diretamente nestes.

Por predefinição, o banner é uma sobreposição fixa no fundo da janela de visualização. Defina mountSelector para o apresentar em linha e de forma estática dentro de um elemento que controle, de modo a que fique inserido na sua própria disposição.

Texto personalizado

O banner e o chip trazem texto localizado e correto em 28 idiomas de origem. Para substituir o texto:

Por idioma, no manifesto. Adicione disclosure.texts a um sistema, indexado por código de idioma. O snippet usa o seu texto para a língua correspondente do visitante:

{
  "disclosure": {
    "texts": { "en": "Some copy on this page was drafted with AI.", "fr": "Une partie du texte a été rédigée avec de l'IA." }
  }
}

Por elemento. Adicione data-ai-label a um elemento marcado para definir o rótulo desse selo.

Quando um sistema define editorialResponsibility.humanReview: true e o seu conteúdo não é totalmente gerado ou manipulado por IA, o aviso passa automaticamente a indicar "assistido por IA, revisto por humanos" na língua do visitante, em vez de "gerado por IA".

Marcar o seu conteúdo de IA

O snippet só rotula aquilo que marca. Adicione data-ai-content a qualquer elemento gerado por IA:

<img data-ai-content src="/img/generated.webp" alt="…">
<p data-ai-content>AI-drafted summary…</p>
<video data-ai-content src="/clip.mp4"></video>

Cada elemento marcado recebe um selo "IA" visível e um data-digital-source-type legível por máquina (com o valor predefinido trainedAlgorithmicMedia, compatível com IPTC e schema.org). Adicione data-ai-label para texto de rótulo personalizado, ou defina data-digital-source-type por si próprio para ser mais específico.

Para IA que não possa anotar diretamente, como um widget de chat de terceiros num iframe fechado, use adjacentSelector para colocar um rótulo ao lado, ou triggerSelector para revelar o banner de interação quando o widget abrir.

Um aviso de geração de conteúdo pode abranger todo o site (disclosure.scope: "site") ou páginas específicas (disclosure.scope: "page" com uma lista disclosure.pages de globs de caminho, como /blog/*). Uma correspondência de âmbito de página tem precedência sobre uma de âmbito de site, e um sistema de âmbito de página sem caminho correspondente não apresenta nada nessa página.

Aplicações de página única e frameworks

O snippet observa o DOM com um MutationObserver e reavalia o aviso aplicável nas mudanças de rota, pelo que o conteúdo e as páginas adicionados após o carregamento continuam a ser rotulados. Numa SPA:

Mantenha observe no seu valor predefinido (true) para que o conteúdo apresentado no cliente seja captado.
Se condicionar a inicialização à prontidão da aplicação, adicione data-manual e chame AIDisclose.init() depois de a sua framework montar.
Os avisos de âmbito de página atualizam-se automaticamente à medida que a rota muda; não é necessária qualquer chamada por rota.

Defina observe: false apenas em páginas totalmente estáticas, onde nada é injetado após o carregamento.

Política de Segurança de Conteúdo

Se aplicar uma Política de Segurança de Conteúdo, permita o snippet explicitamente.

Importante

Um script-src 'self' restrito bloqueia o snippet do CDN silenciosamente, e as divulgações nunca são apresentadas. Esta é a razão mais comum para um site corretamente declarado não atingir o Nível 2.

script-src: adicione https://cdn.aidisclose.io, ou aloje aidisclose.js na sua própria origem e mantenha 'self'.
style-src: o snippet injeta os seus estilos em linha, por isso 'unsafe-inline' é suficiente. Se não permitir estilos em linha, ele recorre ao carregamento de aidisclose.css a partir do diretório do script, pelo que também deve permitir https://cdn.aidisclose.io em style-src (ou alojar esse ficheiro junto do script).
connect-src: a obtenção do manifesto é da mesma origem para o ficheiro well-known e não precisa de nada adicional. Se carregar o manifesto por chave, permita https://cdn.aidisclose.io.

O manifesto é obtido sem credenciais, por isso sirva-o publicamente: um endpoint que exija cookies ou autenticação não os irá receber.

Versionamento e integridade

O CDN serve três canais:

/v1/aidisclose.js acompanha a versão 1.x mais recente. Recomendado para a maioria dos sites.
/v1.0.0/aidisclose.js é uma versão fixa e imutável que pode fixar, com Subresource Integrity:

<script src="https://cdn.aidisclose.io/v1.0.0/aidisclose.js"
        integrity="sha384-…" crossorigin="anonymous" defer></script>

/latest/aidisclose.js acompanha sempre a versão mais recente entre versões principais.

Para obter o hash SRI a fixar, compile o snippet: npm run build em packages/snippet imprime-o (o código-fonte está aberto no GitHub).

Construir a sua própria interface de divulgação

Pode apresentar a sua própria interface de divulgação em vez da integrada. Não existe um único interruptor para a desligar: data-banner="false" e persistentChip: false suprimem apenas o banner de interação e o seu chip, ao passo que os avisos de conteúdo, os selos [data-ai-content] por elemento e o selo "feito por humanos" continuam a ser apresentados a partir do seu manifesto e da sua marcação. Uma interface totalmente personalizada implica não depender destes e apresentar a sua própria.

Nota

O verificador da AIDisclose valida a apresentação detetando a marcação do snippet de referência. Uma divulgação totalmente construída à mão é válida, mas não é detetada automaticamente, pelo que o site permanece no Nível 1 (Declarado) em vez do Nível 2 (Apresentado), a menos que a sua marcação personalizada reproduza aquilo que o verificador procura. Se o Nível 2 for importante para si, mantenha a apresentação integrada e reestilize-a com CSS.

Acessibilidade

A interface apresentada cumpre o nível WCAG 2.1 AA: contornos :focus-visible visíveis em controlos interativos, funções e rótulos corretos, contraste que se mantém em tema claro e escuro, e animação condicionada por prefers-reduced-motion. O snippet também deteta barras de consentimento de cookies conhecidas e empilha-se acima delas, para que as divulgações nunca fiquem ocultas atrás de um CMP. Em ecrãs muito estreitos, o banner de interação abre como o chip compacto, para nunca cobrir o conteúdo.

#Visão geral

#Instalação

#Configuração

#Referência de opções

#Tema e aparência

#Texto personalizado

#Marcar o seu conteúdo de IA

#Aplicações de página única e frameworks

#Política de Segurança de Conteúdo

#Versionamento e integridade

#Construir a sua própria interface de divulgação

#Acessibilidade