Referenčná príručka k snippetu: konfigurácia a prispôsobenie

aidisclose.js je skript na webe, ktorý číta váš manifest ai-disclosure.json a zobrazuje informácie vyžadované zákonom: interakčný banner pre chatboty, trvalé upozornenie o obsahu, viditeľné štítky na označených médiách a strojovo čitateľné metadáta stránky. Nemá žiadne závislosti, má približne 8.2 KB v komprimovanom formáte gzip a spĺňa WCAG 2.1 AA.

Táto stránka je úplnou referenčnou príručkou na konfiguráciu a prispôsobenie. Postup inštalácie pre jednotlivé platformy (WordPress, Shopify, Webflow, správcovia značiek) nájdete v návode na inštaláciu. Tento dokument si môžete prečítať aj ako surový markdown.

Prehľad

Všetko riadi jediná značka skriptu. Po načítaní snippet stiahne váš manifest a potom zobrazí len to, čo manifest deklaruje:

Interakčný banner pre systém typu conversational: upozornenie, že návštevník komunikuje s UI.
Upozornenie o obsahu pre systém typu content-generation s scope: site alebo scope: page: malý trvalý čip. Po kliknutí sa otvorí stručné vysvetlenie s textom upozornenia, vaším menom vydavateľa a účelom systému z manifestu a s odkazom na súbor manifestu; text upozornenia odkazuje na zrozumiteľné vysvetlenie na aidisclose.io. Odznak „made by humans“ otvorí tú istú kartu s menom vydavateľa.
Štítky na jednotlivých prvkoch na každom prvku, ktorý označíte pomocou data-ai-content: viditeľný odznak „AI“ a strojovo čitateľný atribút data-digital-source-type.
Metadáta stránky: prvky <link rel="ai-disclosure"> a <meta name="ai-disclosure"> odkazujúce na váš manifest.
Odznak „made by humans“, keď manifest nastaví noAiDeclared.

Všetko nižšie je voliteľné. Bez akejkoľvek konfigurácie snippet číta váš súbor /.well-known/ai-disclosure.json, zobrazuje sa v jazyku návštevníka v 28 lokalitách, riadi sa svetlým alebo tmavým nastavením operačného systému a ukladá sa nad známe lišty so súhlasom s cookies, aby sa navzájom neprekrývali.

Inštalácia

Značku pridajte raz do zdieľanej šablóny webu, hlavičky motívu alebo správcu značiek a doručí sa s každou stránkou. Môže byť umiestnená v <head> alebo kdekoľvek pred </body>; má atribút defer, takže umiestnenie nemení správanie:

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

Bez atribútov snippet číta manifest na adrese https://YOURDOMAIN/.well-known/ai-disclosure.json. Ak vaša platforma nedokáže sprístupniť súbor v koreni domény, hostujte manifest cez AIDisclose a nasmerujte naň značku pomocou kľúča:

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

Ak manifest nie je dostupný, snippet zapíše varovanie do konzoly a nezobrazí žiadne upozornenia riadené manifestom, takže zlyhanie stiahnutia nikdy nezobrazí odhadnuté upozornenie. Metadáta stránky, vaše štítky [data-ai-content] a banner vynútený pomocou data-banner="true" sa aj tak zobrazia.

Konfigurácia

Snippet možno nakonfigurovať tromi spôsobmi. Použite ten, ktorý vyhovuje vašej platforme.

1. Atribúty na značke skriptu. Najjednoduchšia cesta bez ďalšieho kódu:

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

2. Globálny konfiguračný objekt. Definujte window.AIDiscloseConfig pred spustením skriptu. Sprístupňuje celú sadu možností vrátane možností výberu prvkov, ktoré nemajú podobu atribútu:

<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. Manuálna inicializácia. Pridajte data-manual, čím odložíte automatické spustenie, a potom sami zavolajte AIDisclose.init(), keď je vaša aplikácia pripravená (užitočné v jednostránkových aplikáciách):

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

Ak je prítomných viac zdrojov, prednosť má window.AIDiscloseConfig: prepíše aj atribúty značky skriptu, aj akýkoľvek objekt odovzdaný do AIDisclose.init().

Prehľad možností

Sada možností je stabilná pre celý rad 1.x.

Option	Attribute	Values	Default	Effect
`theme`	`data-theme`	`light`, `dark`, `auto`	`auto`	Farebná schéma. `auto` sa riadi nastavením operačného systému návštevníka.
`siteKey`	`data-aidisclose`	reťazec	žiadny	Načíta manifest hostovaný cez AIDisclose pre tento kľúč namiesto súboru well-known.
`manifestUrl`	`data-manifest-url`	URL	`/.well-known/ai-disclosure.json`	Číta manifest z vlastnej URL.
`lang`	`data-lang`	kód BCP-47	atribút `<html lang>` stránky, inak jazyk návštevníka	Vynúti jazyk zobrazenia.
`banner`	`data-banner`	`true`, `false`	auto	Vynúti zapnutie alebo vypnutie interakčného banneru. Ak sa nenastaví, zobrazí sa len vtedy, keď váš manifest deklaruje konverzačný systém (chatbot).
`persistentChip`	—	`true`, `false`	`true`	Zobrazí alebo potlačí zbalený mini-čip interakčného banneru (malú pilulku, do ktorej sa banner zminimalizuje).
`alwaysShow`	—	`true`, `false`	`false`	Zobrazí banner znova pri každej návšteve, pričom ignoruje predchádzajúce zatvorenie návštevníkom (uložené v `localStorage` prehliadača).
`mountSelector`	—	selektor CSS	žiadny	Zobrazí banner priamo vnútri tohto prvku namiesto pevnej spodnej vrstvy.
`triggerSelector`	—	selektor CSS	žiadny	Zobrazí interakčný banner až po tom, čo návštevník klikne na tento prvok, napríklad na spúšťač chatu. Stránky bez zodpovedajúceho prvku nezobrazia žiadny banner, takže chatbot, ktorý existuje len na niektorých stránkach, informuje len tam. Spúšťače vložené po načítaní stále fungujú. Návštevník, ktorý banner predtým zatvoril, aj tak uvidí mini-čip.
`adjacentSelector`	—	selektor CSS	žiadny	Umiestni štítok vedľa prvku, ktorý nemôžete označiť priamo, napríklad vedľa zatvoreného widgetu alebo iframu.
`observe`	—	`true`, `false`	`true`	Sleduje DOM, či nepribudol obsah, a označí ho. Na úplne statických stránkach nastavte `false`.
`beaconUrl`	—	URL	žiadny	Odošle anonymný beacon `{siteKey, flag}` pri významných udalostiach. Žiadne cookies, žiadne osobné údaje.

data-manual nie je hodnota možnosti: jeho prítomnosť na značke odloží automatické spustenie, aby ste mohli sami zavolať AIDisclose.init().

Motív a vzhľad

Zabudovanú schému nastavte pomocou theme (light, dark alebo auto). Ak chcete presne zladiť vzhľad so svojou značkou, prepíšte vlastné vlastnosti CSS snippetu vo svojom vlastnom štýle. Sú definované na .aid-banner, .aid-chip:

Variable	Controls
`--aid-bg`	Pozadie
`--aid-fg`	Text
`--aid-line`	Orámovanie
`--aid-btn`	Orámovanie tlačidla na zatvorenie
`--aid-btnfg`	Text tlačidla na zatvorenie
`--aid-hov`	Prejdenie kurzorom nad tlačidlom na zatvorenie

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

Snippet nedodáva žiadne pravidlá !important a používa selektory s nízkou špecifickosťou, takže vaše CSS má prednosť. Triedy na napojenie sú .aid-banner, .aid-chip, .aid-badge, .aid-badge-inline, .aid-wrap, .aid-ai (upozornenie o obsahu) a .aid-hm („made by humans“). Odsadenie, zaoblenie a tieň upravte priamo na týchto triedach.

Predvolene je banner pevnou vrstvou v spodnej časti zobrazenia. Nastavením mountSelector ho zobrazíte priamo a staticky vnútri prvku, ktorý ovládate, takže sa umiestni v rámci vášho vlastného rozloženia.

Vlastné texty

Banner a čip obsahujú presný lokalizovaný text v 28 jazykoch už od začiatku. Na prepísanie textu:

Pre jednotlivé jazyky v manifeste. Pridajte do systému disclosure.texts s kľúčom podľa kódu jazyka. Snippet použije váš text pre zodpovedajúci jazyk návštevníka:

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

Pre jednotlivé prvky. Pridaním data-ai-label na označený prvok nastavíte štítok daného odznaku.

Keď systém nastaví editorialResponsibility.humanReview: true a jeho obsah nie je úplne vytvorený alebo upravený UI, upozornenie automaticky znie „AI-assisted, human-reviewed“ v jazyku návštevníka namiesto „AI-generated“.

Označovanie vášho obsahu vytvoreného UI

Snippet označí len to, čo označíte vy. Pridajte data-ai-content na každý prvok vytvorený UI:

<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>

Každý označený prvok dostane viditeľný odznak „AI“ a strojovo čitateľný atribút data-digital-source-type (predvolene trainedAlgorithmicMedia, hodnota kompatibilná s IPTC a schema.org). Pridaním data-ai-label nastavíte vlastný text štítku, alebo si sami nastavte data-digital-source-type, aby ste boli konkrétnejší.

Pre UI, ktoré nemôžete anotovať priamo, napríklad chatovací widget tretej strany v zatvorenom iframe, použite adjacentSelector na umiestnenie štítku vedľa neho alebo triggerSelector na zobrazenie interakčného banneru pri otvorení widgetu.

Upozornenie o generovanom obsahu môže pokrývať celý web (disclosure.scope: "site") alebo konkrétne stránky (disclosure.scope: "page" so zoznamom disclosure.pages s cestami vo forme glob, napríklad /blog/*). Zhoda na úrovni stránky má prednosť pred zhodou na úrovni webu a systém s rozsahom stránky bez zodpovedajúcej cesty tam nezobrazí nič.

Jednostránkové aplikácie a frameworky

Snippet sleduje DOM pomocou MutationObserver a pri zmene trasy prehodnotí príslušné upozornenie, takže obsah a stránky pridané po načítaní sú stále označené. V jednostránkovej aplikácii:

Ponechajte observe na predvolenej hodnote (true), aby sa zachytil obsah vykreslený na strane klienta.
Ak podmieňujete inicializáciu pripravenosťou aplikácie, pridajte data-manual a zavolajte AIDisclose.init() po pripojení vášho frameworku.
Upozornenia s rozsahom stránky sa aktualizujú automaticky pri zmene trasy; nie je potrebné volanie pri každej trase.

Nastavte observe: false len na úplne statických stránkach, kde sa po načítaní nič nevkladá.

Content Security Policy

Ak vynucujete Content Security Policy, snippet výslovne povoľte.

Dôležité

Prísne script-src 'self' blokuje snippet z CDN potichu a informácie sa nikdy nezobrazia. Toto je najčastejší dôvod, prečo správne deklarovaný web nedosiahne úroveň 2.

script-src: pridajte https://cdn.aidisclose.io, alebo hostujte aidisclose.js z vlastného pôvodu a ponechajte 'self'.
style-src: snippet vkladá svoje štýly priamo do stránky, takže postačuje 'unsafe-inline'. Ak nepovoľujete vložené štýly, snippet sa vráti k načítaniu aidisclose.css z adresára skriptu, takže povoľte aj https://cdn.aidisclose.io v style-src (alebo tento súbor hostujte spolu so skriptom).
connect-src: stiahnutie manifestu je pri súbore well-known z rovnakého pôvodu a nepotrebuje nič navyše. Ak načítavate manifest podľa kľúča, povoľte https://cdn.aidisclose.io.

Manifest sa sťahuje bez prihlasovacích údajov, takže ho sprístupnite verejne: koncový bod, ktorý vyžaduje cookies alebo overenie, ich nedostane.

Verzovanie a integrita

CDN poskytuje tri vetvy:

/v1/aidisclose.js sleduje najnovšie vydanie radu 1.x. Odporúčané pre väčšinu webov.
/v1.0.0/aidisclose.js je pevná, nemenná verzia, ktorú môžete pripnúť, s podporou Subresource Integrity:

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

/latest/aidisclose.js vždy sleduje najnovšie vydanie naprieč hlavnými verziami.

Ak chcete získať hash SRI na pripnutie, zostavte snippet: príkaz npm run build v packages/snippet ho vypíše (zdrojový kód je otvorený na GitHube).

Zostavenie vlastného rozhrania na informovanie

Namiesto zabudovaného rozhrania môžete zobraziť svoje vlastné rozhranie na informovanie. Neexistuje jediný vypínač: data-banner="false" a persistentChip: false potlačia len interakčný banner a jeho čip, zatiaľ čo upozornenia o obsahu, odznaky [data-ai-content] na jednotlivých prvkoch a odznak „made by humans“ sa aj tak zobrazia z vášho manifestu a značiek. Úplne vlastné rozhranie znamená nespoliehať sa na tieto prvky a zobraziť vlastné.

Poznámka

Kontrolný nástroj AIDisclose overuje zobrazenie tým, že rozpozná značky referenčného snippetu. Úplne ručne zostavené rozhranie na informovanie je platné, ale nie je automaticky rozpoznané, takže web zostáva na úrovni 1 (Deklarovaná) namiesto úrovne 2 (Zobrazená), pokiaľ vaše vlastné značky nereprodukujú to, čo kontrolný nástroj hľadá. Ak je pre vás úroveň 2 dôležitá, ponechajte zabudované zobrazenie a upravte jeho vzhľad pomocou CSS.

Prístupnosť

Vykreslené rozhranie spĺňa WCAG 2.1 AA: viditeľné obrysy :focus-visible na interaktívnych ovládacích prvkoch, správne roly a štítky, kontrast, ktorý sa udrží v svetlom aj tmavom režime, a animácie podmienené nastavením prefers-reduced-motion. Snippet tiež rozpozná známe lišty so súhlasom s cookies a ukladá sa nad ne, takže informácie nikdy nie sú skryté za CMP. Na veľmi úzkych obrazovkách sa interakčný banner otvorí ako kompaktný čip, aby nikdy neprekrýval obsah.

#Prehľad

#Inštalácia

#Konfigurácia

#Prehľad možností

#Motív a vzhľad

#Vlastné texty

#Označovanie vášho obsahu vytvoreného UI

#Jednostránkové aplikácie a frameworky

#Content Security Policy

#Verzovanie a integrita

#Zostavenie vlastného rozhrania na informovanie

#Prístupnosť