Referência do snippet: configurar e personalizar

aidisclose.js é o script instalado no site que lê seu manifesto ai-disclosure.json e exibe as divulgações exigidas pela lei: um banner de interação para chatbots, um aviso de conteúdo persistente, rótulos visíveis em mídias marcadas e metadados de página legíveis por máquina. Ele não tem dependências, ocupa cerca de 8.2 KB compactado com gzip e atende à WCAG 2.1 AA.

Esta página é a referência completa de configuração e personalização. Para as etapas de instalação plataforma por plataforma (WordPress, Shopify, Webflow, gerenciadores de tags), consulte o guia de instalação. Você também pode ler este documento em markdown puro.

Visão geral

Uma única tag de script controla tudo. Ao carregar, o snippet busca seu manifesto e exibe apenas o que o manifesto declara:

Banner de interação, para um sistema conversational: um aviso de que o visitante está conversando 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 breve com o texto do aviso, o nome do publicador e a finalidade do sistema conforme o manifesto, além de um link para o arquivo do manifesto; o texto do aviso remete a uma explicação em linguagem simples em aidisclose.io. O selo "feito por humanos" abre o mesmo cartão com o nome do publicador.
Rótulos por elemento, em qualquer elemento que você 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"> apontando para seu manifesto.
Selo "feito por humanos", quando o manifesto define noAiDeclared.

Tudo abaixo é opcional. Sem nenhuma configuração, o snippet lê seu /.well-known/ai-disclosure.json, exibe o conteúdo no idioma do visitante em 28 localidades, segue a preferência de tema claro ou escuro do sistema operacional e se posiciona acima de barras conhecidas de consentimento de cookies, para que as duas nunca se sobreponham.

Instalação

Adicione a tag uma vez, no template compartilhado do site, no cabeçalho do tema ou no gerenciador de tags, e ela passa a acompanhar todas as páginas. Ela pode ficar no <head> ou em qualquer lugar antes de </body>; o carregamento é deferido, então a posição 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 sua plataforma não conseguir servir um arquivo na raiz do domínio, hospede o manifesto no AIDisclose e aponte a tag para ele pela chave:

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

Se o manifesto não puder ser acessado, o snippet registra um aviso no console e não exibe nenhum aviso baseado no manifesto, de modo que uma falha na busca nunca mostra um aviso adivinhado. Os metadados de página, seus rótulos [data-ai-content] e um banner forçado com data-banner="true" continuam sendo exibidos.

Configuração

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

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

<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 rodar. 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 início automático e, em seguida, chame AIDisclose.init() você mesmo assim que 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 mais de uma fonte estiver presente, window.AIDiscloseConfig prevalece: ela sobrepõe tanto os atributos da tag de script quanto 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 operacional do visitante.
`siteKey`	`data-aidisclose`	string	nenhum	Carrega o manifesto hospedado no AIDisclose para esta chave, em vez do arquivo well-known.
`manifestUrl`	`data-manifest-url`	URL	`/.well-known/ai-disclosure.json`	Lê o manifesto a partir de uma URL personalizada.
`lang`	`data-lang`	código BCP-47	`<html lang>` da página, senão o idioma do visitante	Força um idioma de exibição.
`banner`	`data-banner`	`true`, `false`	auto	Força a exibição ou não do banner de interação. Se não for definido, ele aparece somente quando seu manifesto declara um sistema conversacional (chatbot).
`persistentChip`	—	`true`, `false`	`true`	Exibe ou suprime o mini-chip recolhido do banner de interação (a pequena pílula em que ele é minimizado).
`alwaysShow`	—	`true`, `false`	`false`	Exibe o banner novamente a cada visita, ignorando a dispensa feita pelo visitante (registrada no `localStorage` do navegador).
`mountSelector`	—	seletor CSS	nenhum	Exibe o banner de forma embutida dentro deste elemento, em vez da sobreposição fixa na parte inferior.
`triggerSelector`	—	seletor CSS	nenhum	Exibe o banner de interação somente depois que o visitante clica neste elemento, como um acionador de chat. Páginas sem elemento correspondente não exibem banner, de modo que um chatbot presente em apenas algumas páginas faz a divulgação somente nelas. Acionadores injetados após o carregamento também funcionam. Um visitante que dispensou o banner antes continua vendo o mini-chip.
`adjacentSelector`	—	seletor CSS	nenhum	Coloca um rótulo ao lado de um elemento que você não consegue marcar diretamente, como um widget fechado ou um iframe.
`observe`	—	`true`, `false`	`true`	Observa o DOM em busca de conteúdo adicionado depois e o rotula. Defina como `false` em páginas totalmente estáticas.
`beaconUrl`	—	URL	nenhum	Envia um beacon anônimo `{siteKey, flag}` em eventos relevantes. Sem cookies, sem dados pessoais.

data-manual não é um valor de opção: sua presença na tag adia o início automático para que você possa chamar AIDisclose.init() você mesmo.

Tema e aparência

Defina o esquema integrado com theme (light, dark ou auto). Para reproduzir sua marca com exatidão, sobreponha as propriedades CSS personalizadas do snippet na sua própria folha de estilos. Elas são definidas em .aid-banner, .aid-chip:

Variable	Controls
`--aid-bg`	Fundo
`--aid-fg`	Texto
`--aid-line`	Borda
`--aid-btn`	Borda do botão de dispensar
`--aid-btnfg`	Texto do botão de dispensar
`--aid-hov`	Passagem do mouse sobre o botão de dispensar

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

O snippet não inclui nenhuma regra !important e usa seletores de baixa especificidade, então seu CSS prevalece. Os pontos de estilo por 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"). Ajuste espaçamento, raio e sombra diretamente nesses elementos.

Por padrão, o banner é uma sobreposição fixa na parte inferior da janela de visualização. Defina mountSelector para exibi-lo de forma embutida e estática dentro de um elemento que você controla, de modo que ele fique dentro do seu próprio layout.

Texto personalizado

O banner e o chip trazem, de fábrica, texto localizado e correto em 28 idiomas. Para substituir o texto:

Por idioma, no manifesto. Adicione disclosure.texts a um sistema, indexado pelo código de idioma. O snippet usa seu texto para o idioma 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 daquele selo.

Quando um sistema define editorialResponsibility.humanReview: true e seu conteúdo não é totalmente gerado ou manipulado por IA, o aviso passa automaticamente a exibir "IA assistida, revisada por humanos" no idioma do visitante, em vez de "gerado por IA".

Como marcar seu conteúdo de IA

O snippet rotula apenas o que você 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 padrão trainedAlgorithmicMedia, compatível com IPTC e schema.org). Adicione data-ai-label para um texto de rótulo personalizado ou defina você mesmo data-digital-source-type para ser mais específico.

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

Um aviso de geração de conteúdo pode cobrir o site inteiro (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 por página tem precedência sobre uma por site, e um sistema com escopo de página que não corresponde a nenhum caminho não exibe nada ali.

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, de modo que conteúdo e páginas adicionados após o carregamento continuam sendo rotulados. Em uma SPA:

Mantenha observe no valor padrão (true) para que o conteúdo renderizado no cliente seja capturado.
Se você condicionar a inicialização à prontidão da aplicação, adicione data-manual e chame AIDisclose.init() depois que seu framework montar.
Os avisos com escopo de página se atualizam automaticamente à medida que a rota muda; não é preciso uma chamada por rota.

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

Content Security Policy

Se você aplica uma Content Security Policy, permita o snippet explicitamente.

Importante

Um script-src 'self' estrito bloqueia o snippet do CDN silenciosamente, e as divulgações nunca são exibidas. Esse é o motivo mais comum para um site corretamente declarado não alcançar o Nível 2.

script-src: adicione https://cdn.aidisclose.io ou hospede o aidisclose.js na sua própria origem e mantenha 'self'.
style-src: o snippet injeta seus estilos de forma inline, então 'unsafe-inline' é suficiente. Se você não permite estilos inline, ele recorre a carregar o aidisclose.css a partir do diretório do script, então permita também https://cdn.aidisclose.io em style-src (ou hospede esse arquivo junto ao script).
connect-src: a busca do manifesto é da mesma origem para o arquivo well-known e não precisa de nada extra. Se você carrega o manifesto por chave, permita https://cdn.aidisclose.io.

O manifesto é buscado sem credenciais, então sirva-o publicamente: um endpoint que exige cookies ou autenticação não os 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 você 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 nova, atravessando versões principais.

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

Como criar sua própria interface de divulgação

Você pode renderizar sua própria interface de divulgação em vez da integrada. Não existe um único interruptor para desligá-la: data-banner="false" e persistentChip: false suprimem apenas o banner de interação e seu chip, enquanto os avisos de conteúdo, os selos por elemento [data-ai-content] e o selo "feito por humanos" continuam sendo exibidos a partir do seu manifesto e da sua marcação. Uma interface totalmente personalizada significa não depender desses recursos e renderizar a sua própria.

Nota

O verificador do AIDisclose confirma a renderização detectando a marcação do snippet de referência. Uma divulgação totalmente feita à mão é válida, mas não é detectada automaticamente, então o site permanece no Nível 1 (Declarado) em vez do Nível 2 (Renderizado), a menos que sua marcação personalizada reproduza o que o verificador procura. Se o Nível 2 for importante para você, mantenha a renderização integrada e reestilize-a com CSS.

Acessibilidade

A interface renderizada atende à WCAG 2.1 AA: contornos :focus-visible visíveis nos controles interativos, papéis e rótulos corretos, contraste que se mantém no tema claro e no escuro, e animação condicionada a prefers-reduced-motion. O snippet também detecta barras conhecidas de consentimento de cookies e se posiciona acima delas para que as divulgações nunca fiquem escondidas atrás de uma CMP. Em telas muito estreitas, 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

#Como marcar seu conteúdo de IA

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

#Content Security Policy

#Versionamento e integridade

#Como criar sua própria interface de divulgação

#Acessibilidade