AIDisclose
Începeți
ENFRRO

Documentație

Fragmentul de cod AIDisclose

Referință de configurare și personalizare

Citește în format Markdown Ghid de instalare Sursa pe GitHub

aidisclose.js este scriptul de pe site care citește manifestul ai-disclosure.json și afișează divulgările impuse de lege: un banner de interacțiune pentru chatboturi, o notificare persistentă privind conținutul, etichete vizibile pe media marcată și metadate de pagină care pot fi citite automat. Nu are dependențe, cântărește circa 8.2 KB comprimat gzip și respectă WCAG 2.1 AA.

Această pagină este referința completă de configurare și personalizare. Pentru pașii de instalare platformă cu platformă (WordPress, Shopify, Webflow, managere de etichete), consultați ghidul de instalare. Puteți citi acest document și în format markdown brut.

Prezentare generală

O singură etichetă de script pune totul în funcțiune. La încărcare, fragmentul de cod preia manifestul, apoi afișează doar ceea ce declară manifestul:

  • Banner de interacțiune, pentru un sistem conversational: o notificare că vizitatorul discută cu o IA.
  • Notificare privind conținutul, pentru un sistem content-generation cu scope: site sau scope: page: un mic jeton persistent. Un clic pe el deschide o scurtă explicație cu textul notificării, numele editorului și scopul sistemului preluate din manifest, precum și un link către fișierul manifestului; textul notificării trimite către o explicație pe înțelesul tuturor pe aidisclose.io. Insigna „made by humans” deschide aceeași fișă cu numele editorului.
  • Etichete per element, pe orice element pe care îl marcați cu data-ai-content: o insignă „AI” vizibilă, plus un data-digital-source-type care poate fi citit automat.
  • Metadate de pagină: un <link rel="ai-disclosure"> și un <meta name="ai-disclosure"> care indică manifestul.
  • Insigna „Made by humans”, atunci când manifestul setează noAiDeclared.

Tot ce urmează este opțional. Fără nicio configurare, fragmentul de cod citește fișierul dumneavoastră /.well-known/ai-disclosure.json, se afișează în limba vizitatorului în 28 de limbi, respectă preferința sistemului de operare pentru modul luminos sau întunecat și se așază deasupra barelor cunoscute de consimțământ pentru cookieuri, astfel încât cele două să nu se suprapună niciodată.

Instalare

Adăugați eticheta o singură dată, în șablonul comun al site-ului, în antetul temei sau în managerul de etichete, iar aceasta se livrează cu fiecare pagină. Poate sta în <head> sau oriunde înainte de </body>; este amânată (deferred), astfel încât plasarea nu îi schimbă comportamentul:

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

Fără atribute, fragmentul de cod citește manifestul de la https://YOURDOMAIN/.well-known/ai-disclosure.json. Dacă platforma dumneavoastră nu poate servi un fișier la rădăcina domeniului, găzduiți manifestul la AIDisclose și direcționați eticheta către el prin cheie:

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

Dacă manifestul nu poate fi accesat, fragmentul de cod înregistrează un avertisment în consolă și nu afișează nicio notificare bazată pe manifest, astfel încât o eroare de preluare nu arată niciodată o notificare presupusă. Metadatele de pagină, etichetele dumneavoastră [data-ai-content] și un banner forțat cu data-banner="true" se afișează în continuare.

Configurare

Există trei modalități de a configura fragmentul de cod. Folosiți-o pe cea care se potrivește platformei dumneavoastră.

1. Atribute pe eticheta de script. Calea cea mai simplă, fără cod suplimentar:

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

2. Un obiect global de configurare. Definiți window.AIDiscloseConfig înainte ca scriptul să ruleze. Acesta expune întregul set de opțiuni, inclusiv opțiunile de selector care nu au o formă de atribut:

<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. Inițializare manuală. Adăugați data-manual pentru a amâna pornirea automată, apoi apelați chiar dumneavoastră AIDisclose.init() odată ce aplicația este pregătită (util în aplicațiile de tip single-page):

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

Dacă este prezentă mai mult de o singură sursă, window.AIDiscloseConfig are prioritate: suprascrie atât atributele etichetei de script, cât și orice obiect transmis către AIDisclose.init().

Referința opțiunilor

Suprafața opțiunilor este stabilă pentru linia 1.x.

Option Attribute Values Default Effect
theme data-theme light, dark, auto auto Schema de culori. auto respectă preferința sistemului de operare al vizitatorului.
siteKey data-aidisclose șir de caractere niciuna Încarcă manifestul găzduit de AIDisclose pentru această cheie în locul fișierului well-known.
manifestUrl data-manifest-url URL /.well-known/ai-disclosure.json Citește manifestul de la un URL personalizat.
lang data-lang cod BCP-47 <html lang> al paginii, altfel limba vizitatorului Forțează o limbă de afișare.
banner data-banner true, false auto Forțează afișarea sau ascunderea bannerului de interacțiune. Lăsat nesetat, apare doar când manifestul declară un sistem conversațional (chatbot).
persistentChip — true, false true Afișează sau suprimă mini-jetonul restrâns al bannerului de interacțiune (mica pastilă în care se minimizează).
alwaysShow — true, false false Afișează bannerul din nou la fiecare vizită, ignorând respingerea de către vizitator (reținută în localStorage al browserului).
mountSelector — selector CSS niciuna Afișează bannerul integrat în interiorul acestui element în locul suprapunerii fixe din partea de jos.
triggerSelector — selector CSS niciuna Afișează bannerul de interacțiune doar după ce vizitatorul face clic pe acest element, cum ar fi un buton de lansare a chatului. Paginile fără un element corespunzător nu afișează niciun banner, astfel încât un chatbot prezent pe unele pagini divulgă doar acolo. Butoanele de lansare injectate după încărcare funcționează în continuare. Un vizitator care a respins bannerul mai devreme vede în continuare mini-jetonul.
adjacentSelector — selector CSS niciuna Plasează o etichetă lângă un element pe care nu îl puteți marca direct, cum ar fi un widget închis sau un iframe.
observe — true, false true Urmărește DOM-ul pentru conținut adăugat ulterior și îl etichetează. Setați false pe paginile complet statice.
beaconUrl — URL niciuna Trimite un semnal anonim {siteKey, flag} la evenimente notabile. Fără cookieuri, fără date personale.

data-manual nu este o valoare de opțiune: prezența sa pe etichetă amână pornirea automată pentru a putea apela chiar dumneavoastră AIDisclose.init().

Temă și aspect

Setați schema încorporată cu theme (light, dark sau auto). Pentru a se potrivi exact cu brandul dumneavoastră, suprascrieți proprietățile CSS personalizate ale fragmentului de cod în propria foaie de stil. Acestea sunt definite pe .aid-banner, .aid-chip:

Variable Controls
--aid-bg Fundal
--aid-fg Text
--aid-line Chenar
--aid-btn Chenarul butonului de respingere
--aid-btnfg Textul butonului de respingere
--aid-hov Efectul de hover al butonului de respingere 
.aid-banner, .aid-chip {
  --aid-bg: #0b1020;
  --aid-fg: #e8eaed;
  --aid-line: #2a2f36;
}

Fragmentul de cod nu livrează nicio regulă !important și folosește selectori cu specificitate scăzută, astfel încât CSS-ul dumneavoastră are prioritate. Punctele de ancorare pentru clase sunt .aid-banner, .aid-chip, .aid-badge, .aid-badge-inline, .aid-wrap, .aid-ai (notificare privind conținutul) și .aid-hm („made by humans”). Restilizați direct pe acestea spațierea, raza și umbra.

În mod implicit, bannerul este o suprapunere fixă în partea de jos a ferestrei de vizualizare. Setați mountSelector pentru a-l afișa integrat și static în interiorul unui element pe care îl controlați, astfel încât să se încadreze în propriul dumneavoastră aspect.

Text personalizat

Bannerul și jetonul poartă implicit text localizat exact în 28 de limbi. Pentru a suprascrie textul:

  • Per limbă, în manifest. Adăugați disclosure.texts la un sistem, indexat după codul de limbă. Fragmentul de cod folosește textul dumneavoastră pentru limba corespunzătoare a vizitatorului:
{
  "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 element. Adăugați data-ai-label la un element marcat pentru a stabili eticheta acelei insigne.

Când un sistem setează editorialResponsibility.humanReview: true, iar conținutul său nu este generat sau manipulat integral de IA, notificarea afișează automat „AI-assisted, human-reviewed” în limba vizitatorului, în locul „AI-generated”.

Marcarea conținutului dumneavoastră IA

Fragmentul de cod etichetează doar ceea ce marcați. Adăugați data-ai-content la orice element generat de 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>

Fiecare element marcat primește o insignă „AI” vizibilă și un data-digital-source-type care poate fi citit automat (implicit trainedAlgorithmicMedia, o valoare compatibilă IPTC și schema.org). Adăugați data-ai-label pentru text de etichetă personalizat sau setați chiar dumneavoastră data-digital-source-type pentru a fi mai specific.

Pentru IA pe care nu o puteți adnota direct, cum ar fi un widget de chat terț într-un iframe închis, folosiți adjacentSelector pentru a plasa o etichetă lângă el sau triggerSelector pentru a dezvălui bannerul de interacțiune când widgetul se deschide.

O notificare de generare a conținutului poate acoperi întregul site (disclosure.scope: "site") sau pagini specifice (disclosure.scope: "page" cu o listă disclosure.pages de tipare de cale, cum ar fi /blog/*). O potrivire la nivel de pagină are prioritate față de una la nivel de site, iar un sistem la nivel de pagină fără o cale corespunzătoare nu afișează nimic acolo.

Aplicații de tip single-page și framework-uri

Fragmentul de cod urmărește DOM-ul cu un MutationObserver și reevaluează notificarea aplicabilă la schimbările de rută, astfel încât conținutul și paginile adăugate după încărcare sunt etichetate în continuare. Într-un SPA:

  • Păstrați observe la valoarea sa implicită (true), astfel încât conținutul redat pe client să fie surprins.
  • Dacă restricționați inițializarea în funcție de gradul de pregătire al aplicației, adăugați data-manual și apelați AIDisclose.init() după ce framework-ul dumneavoastră se montează.
  • Notificările la nivel de pagină se actualizează automat pe măsură ce se schimbă ruta; nu este nevoie de niciun apel per rută.

Setați observe: false doar pe paginile complet statice, unde nu se injectează nimic după încărcare.

Politica de securitate a conținutului

Dacă impuneți o Politică de securitate a conținutului, permiteți fragmentul de cod în mod explicit.

Important

Un script-src 'self' strict blochează fragmentul de cod de pe CDN în tăcere, iar divulgările nu se afișează niciodată. Acesta este cel mai frecvent motiv pentru care un site declarat corect nu atinge Nivelul 2.

  • script-src: adăugați https://cdn.aidisclose.io sau găzduiți chiar dumneavoastră aidisclose.js de pe propria origine și păstrați 'self'.
  • style-src: fragmentul de cod își injectează stilurile inline, deci 'unsafe-inline' este suficient. Dacă nu permiteți stiluri inline, recurge la încărcarea aidisclose.css din directorul scriptului, deci permiteți și https://cdn.aidisclose.io în style-src (sau găzduiți chiar dumneavoastră acel fișier alături de script).
  • connect-src: preluarea manifestului este de aceeași origine pentru fișierul well-known și nu necesită nimic suplimentar. Dacă încărcați manifestul prin cheie, permiteți https://cdn.aidisclose.io.

Manifestul este preluat fără acreditări, deci serviți-l public: un endpoint care necesită cookieuri sau autentificare nu le va primi.

Versionare și integritate

CDN-ul servește trei canale:

  • /v1/aidisclose.js urmează cea mai recentă versiune 1.x. Recomandat pentru majoritatea site-urilor.
  • /v1.0.0/aidisclose.js este o versiune fixă, imuabilă, pe care o puteți fixa, cu Subresource Integrity:
<script src="https://cdn.aidisclose.io/v1.0.0/aidisclose.js"
        integrity="sha384-…" crossorigin="anonymous" defer></script>
  • /latest/aidisclose.js urmărește întotdeauna cea mai nouă versiune de-a lungul versiunilor majore.

Pentru a obține hash-ul SRI de fixat, construiți fragmentul de cod: npm run build în packages/snippet îl afișează (sursa este deschisă pe GitHub).

Construirea propriei interfețe de divulgare

Puteți afișa propria interfață de divulgare în locul celei încorporate. Nu există un singur comutator de oprire: data-banner="false" și persistentChip: false suprimă doar bannerul de interacțiune și jetonul său, în timp ce notificările privind conținutul, insignele per element [data-ai-content] și insigna „made by humans” se afișează în continuare pe baza manifestului și a marcajului dumneavoastră. O interfață complet personalizată înseamnă să nu vă bazați pe acestea și să vă afișați propria interfață.

Notă

Verificatorul AIDisclose verifică afișarea prin detectarea marcajului fragmentului de cod de referință. O divulgare construită integral manual este validă, dar nu este detectată automat, deci site-ul rămâne la Nivelul 1 (Declarat) în loc de Nivelul 2 (Afișat), cu excepția cazului în care marcajul dumneavoastră personalizat reproduce ceea ce caută verificatorul. Dacă Nivelul 2 contează pentru dumneavoastră, păstrați afișarea încorporată și restilizați-o cu CSS.

Accesibilitate

Interfața afișată respectă WCAG 2.1 AA: contururi vizibile :focus-visible pe controalele interactive, roluri și etichete corecte, contrast care se menține în modul luminos și întunecat, iar animația este condiționată de prefers-reduced-motion. Fragmentul de cod detectează totodată barele cunoscute de consimțământ pentru cookieuri și se așază deasupra lor, astfel încât divulgările să nu fie niciodată ascunse în spatele unui CMP. Pe ecrane foarte înguste, bannerul de interacțiune se deschide sub forma jetonului compact, astfel încât să nu acopere niciodată conținutul.