Riferimento dello snippet: configura e personalizza

aidisclose.js è lo script on-site che legge il tuo manifesto ai-disclosure.json e rende le disclosure richieste dalla legge: un banner di interazione per i chatbot, una notifica di contenuto persistente, etichette visibili sui media marcati e metadati di pagina leggibili dalle macchine. È privo di dipendenze, occupa circa 8.2 KB con compressione gzip e soddisfa il livello WCAG 2.1 AA.

Questa pagina è il riferimento completo per configurazione e personalizzazione. Per i passaggi di installazione piattaforma per piattaforma (WordPress, Shopify, Webflow, tag manager), consulta la guida all'installazione. Puoi anche leggere questo documento come markdown grezzo.

Panoramica

Un unico tag script gestisce tutto. Al caricamento lo snippet recupera il tuo manifesto, poi rende solo ciò che il manifesto dichiara:

Banner di interazione, per un sistema conversational: un avviso che il visitatore sta parlando con un'IA.
Notifica di contenuto, per un sistema content-generation con scope: site o scope: page: un piccolo chip persistente. Facendo clic si apre una breve spiegazione con il testo della notifica, il nome dell'editore e lo scopo del sistema tratti dal manifesto, e un link al file del manifesto; il testo della notifica rimanda a una spiegazione in linguaggio semplice su aidisclose.io. Il badge "made by humans" apre la stessa scheda con il nome dell'editore.
Etichette per elemento, su qualsiasi elemento che marchi con data-ai-content: un badge "AI" visibile, più un data-digital-source-type leggibile dalle macchine.
Metadati di pagina: un <link rel="ai-disclosure"> e un <meta name="ai-disclosure"> che puntano al tuo manifesto.
Badge "Made by humans", quando il manifesto imposta noAiDeclared.

Tutto ciò che segue è facoltativo. Senza alcuna configurazione lo snippet legge il tuo /.well-known/ai-disclosure.json, rende nella lingua del visitatore in 28 lingue, segue la preferenza chiara o scura del sistema operativo e si posiziona sopra le note barre di consenso ai cookie in modo che le due non si sovrappongano mai.

Installazione

Aggiungi il tag una sola volta, nel template condiviso del sito, nell'header del tema o nel tag manager, e verrà incluso in ogni pagina. Può stare nell'<head> o in qualsiasi punto prima di </body>; è differito, quindi la posizione non ne cambia il comportamento:

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

Senza attributi lo snippet legge il manifesto all'indirizzo https://YOURDOMAIN/.well-known/ai-disclosure.json. Se la tua piattaforma non può servire un file nella radice del dominio, ospita il manifesto con AIDisclose e fai puntare il tag a esso tramite chiave:

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

Se il manifesto non è raggiungibile, lo snippet registra un avviso nella console e non rende alcuna notifica derivata dal manifesto, così un errore di recupero non mostra mai una notifica ipotizzata. I metadati di pagina, le tue etichette [data-ai-content] e un banner forzato con data-banner="true" vengono comunque resi.

Configurazione

Ci sono tre modi per configurare lo snippet. Usa quello più adatto alla tua piattaforma.

1. Attributi sul tag script. Il percorso più semplice, senza codice aggiuntivo:

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

2. Un oggetto di configurazione globale. Definisci window.AIDiscloseConfig prima che lo script venga eseguito. Espone l'intero set di opzioni, incluse le opzioni di selettore che non hanno una forma come attributo:

<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. Inizializzazione manuale. Aggiungi data-manual per rinviare l'avvio automatico, poi chiama tu stesso AIDisclose.init() quando la tua app è pronta (utile nelle single-page app):

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

Se è presente più di una fonte, prevale window.AIDiscloseConfig: sovrascrive sia gli attributi del tag script sia qualsiasi oggetto passato a AIDisclose.init().

Riferimento delle opzioni

La superficie delle opzioni è stabile per la linea 1.x.

Option	Attribute	Valori	Predefinito	Effetto
`theme`	`data-theme`	`light`, `dark`, `auto`	`auto`	Schema di colori. `auto` segue la preferenza del sistema operativo del visitatore.
`siteKey`	`data-aidisclose`	stringa	nessuno	Carica il manifesto ospitato da AIDisclose per questa chiave invece del file well-known.
`manifestUrl`	`data-manifest-url`	URL	`/.well-known/ai-disclosure.json`	Legge il manifesto da un URL personalizzato.
`lang`	`data-lang`	codice BCP-47	`<html lang>` della pagina, altrimenti la lingua del visitatore	Forza una lingua di visualizzazione.
`banner`	`data-banner`	`true`, `false`	auto	Forza l'attivazione o la disattivazione del banner di interazione. Se non impostato, appare solo quando il manifesto dichiara un sistema conversazionale (chatbot).
`persistentChip`	—	`true`, `false`	`true`	Mostra o nasconde il mini-chip compresso del banner di interazione (la piccola pillola in cui si riduce).
`alwaysShow`	—	`true`, `false`	`false`	Mostra di nuovo il banner a ogni visita, ignorando la chiusura da parte del visitatore (memorizzata nel `localStorage` del browser).
`mountSelector`	—	selettore CSS	nessuno	Rende il banner in linea all'interno di questo elemento invece della sovrapposizione fissa in basso.
`triggerSelector`	—	selettore CSS	nessuno	Mostra il banner di interazione solo dopo che il visitatore ha fatto clic su questo elemento, come un avvio di chat. Le pagine senza un elemento corrispondente non mostrano alcun banner, così un chatbot presente solo su alcune pagine effettua la disclosure solo lì. Gli avviatori iniettati dopo il caricamento funzionano comunque. Un visitatore che ha chiuso il banner in precedenza vede comunque il mini-chip.
`adjacentSelector`	—	selettore CSS	nessuno	Colloca un'etichetta accanto a un elemento che non puoi marcare direttamente, come un widget chiuso o un iframe.
`observe`	—	`true`, `false`	`true`	Osserva il DOM per i contenuti aggiunti successivamente e li etichetta. Imposta `false` sulle pagine completamente statiche.
`beaconUrl`	—	URL	nessuno	Invia un beacon anonimo `{siteKey, flag}` in occasione di eventi rilevanti. Nessun cookie, nessun dato personale.

data-manual non è un valore di opzione: la sua presenza sul tag rinvia l'avvio automatico così puoi chiamare tu stesso AIDisclose.init().

Tema e aspetto

Imposta lo schema integrato con theme (light, dark o auto). Per abbinare esattamente il tuo marchio, sovrascrivi le proprietà CSS personalizzate dello snippet nel tuo foglio di stile. Sono definite su .aid-banner, .aid-chip:

Variabile	Controlla
`--aid-bg`	Sfondo
`--aid-fg`	Testo
`--aid-line`	Bordo
`--aid-btn`	Bordo del pulsante di chiusura
`--aid-btnfg`	Testo del pulsante di chiusura
`--aid-hov`	Passaggio del mouse sul pulsante di chiusura

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

Lo snippet non include regole !important e usa selettori a bassa specificità, così il tuo CSS prevale. Gli hook di classe sono .aid-banner, .aid-chip, .aid-badge, .aid-badge-inline, .aid-wrap, .aid-ai (notifica di contenuto) e .aid-hm ("made by humans"). Ristila spaziatura, raggio e ombra direttamente su questi.

Per impostazione predefinita il banner è una sovrapposizione fissa in fondo alla viewport. Imposta mountSelector per renderlo in linea e statico all'interno di un elemento che controlli tu, così si colloca nel tuo layout.

Testi personalizzati

Il banner e il chip riportano testi localizzati e accurati in 28 lingue di serie. Per sovrascrivere i testi:

Per lingua, nel manifesto. Aggiungi disclosure.texts a un sistema, indicizzato per codice di lingua. Lo snippet usa il tuo testo per la lingua corrispondente del visitatore:

{
  "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." }
  }
}

Per elemento. Aggiungi data-ai-label a un elemento marcato per impostare l'etichetta di quel badge.

Quando un sistema imposta editorialResponsibility.humanReview: true e il suo contenuto non è interamente generato o manipolato dall'IA, la notifica riporta automaticamente "IA assistita, revisionata da persone" nella lingua del visitatore, invece di "generato dall'IA".

Marcatura dei tuoi contenuti IA

Lo snippet etichetta solo ciò che marchi. Aggiungi data-ai-content a qualsiasi elemento generato dall'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>

Ogni elemento marcato riceve un badge "AI" visibile e un data-digital-source-type leggibile dalle macchine (con valore predefinito trainedAlgorithmicMedia, compatibile con IPTC e schema.org). Aggiungi data-ai-label per un testo di etichetta personalizzato, oppure imposta tu stesso data-digital-source-type per essere più specifico.

Per l'IA che non puoi annotare direttamente, come un widget di chat di terze parti in un iframe chiuso, usa adjacentSelector per collocare un'etichetta accanto a esso, oppure triggerSelector per mostrare il banner di interazione quando il widget si apre.

Una notifica di generazione di contenuti può coprire l'intero sito (disclosure.scope: "site") o pagine specifiche (disclosure.scope: "page" con un elenco disclosure.pages di glob di percorso, come /blog/*). Una corrispondenza per pagina ha precedenza su una per sito, e un sistema con ambito di pagina senza percorso corrispondente non rende nulla lì.

Single-page app e framework

Lo snippet osserva il DOM con un MutationObserver e rivaluta la notifica applicabile ai cambi di rotta, così i contenuti e le pagine aggiunti dopo il caricamento vengono comunque etichettati. In una SPA:

Mantieni observe al valore predefinito (true) così i contenuti resi lato client vengono rilevati.
Se subordini l'inizializzazione alla prontezza dell'app, aggiungi data-manual e chiama AIDisclose.init() dopo che il tuo framework è montato.
Le notifiche con ambito di pagina si aggiornano automaticamente al cambiare della rotta; non serve alcuna chiamata per rotta.

Imposta observe: false solo sulle pagine completamente statiche in cui nulla viene iniettato dopo il caricamento.

Content Security Policy

Se applichi una Content Security Policy, autorizza lo snippet in modo esplicito.

Importante

Un rigido script-src 'self' blocca in silenzio lo snippet del CDN, e le disclosure non vengono mai rese. Questo è il motivo più comune per cui un sito dichiarato correttamente non raggiunge il Livello 2.

script-src: aggiungi https://cdn.aidisclose.io, oppure ospita aidisclose.js sulla tua origine e mantieni 'self'.
style-src: lo snippet inietta i suoi stili in linea, quindi 'unsafe-inline' è sufficiente. Se non consenti gli stili in linea, ricorre al caricamento di aidisclose.css dalla directory dello script, perciò autorizza anche https://cdn.aidisclose.io in style-src (oppure ospita quel file insieme allo script).
connect-src: il recupero del manifesto è della stessa origine per il file well-known e non richiede nulla di aggiuntivo. Se carichi il manifesto tramite chiave, autorizza https://cdn.aidisclose.io.

Il manifesto viene recuperato senza credenziali, quindi pubblicalo pubblicamente: un endpoint che richiede cookie o autenticazione non li riceverà.

Versionamento e integrità

Il CDN serve tre canali:

/v1/aidisclose.js segue l'ultima release 1.x. Consigliato per la maggior parte dei siti.
/v1.0.0/aidisclose.js è una versione fissa e immutabile che puoi bloccare, con Subresource Integrity:

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

/latest/aidisclose.js traccia sempre la release più recente attraverso le versioni major.

Per ottenere l'hash SRI da bloccare, compila lo snippet: npm run build in packages/snippet lo stampa (il codice sorgente è aperto su GitHub).

Creazione di una tua UI di disclosure

Puoi rendere una tua UI di disclosure al posto di quella integrata. Non esiste un unico interruttore di disattivazione: data-banner="false" e persistentChip: false sopprimono solo il banner di interazione e il suo chip, mentre le notifiche di contenuto, i badge per elemento [data-ai-content] e il badge "made by humans" continuano a essere resi dal tuo manifesto e dal tuo markup. Una UI completamente personalizzata significa non affidarsi a questi e rendere la tua.

Nota

Il checker di AIDisclose verifica il rendering rilevando il markup dello snippet di riferimento. Una disclosure interamente costruita a mano è valida, ma non viene rilevata automaticamente, quindi il sito resta al Livello 1 (Dichiarato) anziché al Livello 2 (Reso) a meno che il tuo markup personalizzato non riproduca ciò che il checker cerca. Se il Livello 2 è importante per te, mantieni il rendering integrato e ristilalo con il CSS.

Accessibilità

La UI resa soddisfa il livello WCAG 2.1 AA: contorni :focus-visible visibili sui controlli interattivi, ruoli ed etichette corretti, contrasto che tiene in chiaro e in scuro, e animazioni subordinate a prefers-reduced-motion. Lo snippet rileva inoltre le note barre di consenso ai cookie e si posiziona sopra di esse così le disclosure non restano mai nascoste dietro una CMP. Sugli schermi molto stretti il banner di interazione si apre come chip compatto così non copre mai i contenuti.

#Panoramica

#Installazione

#Configurazione

#Riferimento delle opzioni

#Tema e aspetto

#Testi personalizzati

#Marcatura dei tuoi contenuti IA

#Single-page app e framework

#Content Security Policy

#Versionamento e integrità

#Creazione di una tua UI di disclosure

#Accessibilità