Referenční příručka snippetu: konfigurace a přizpůsobení

aidisclose.js je skript na webu, který čte váš manifest ai-disclosure.json a vykresluje informace o UI vyžadované zákonem: interakční banner pro chatboty, trvalé upozornění na obsah, viditelné štítky u označených médií a strojově čitelná metadata stránky. Nemá žádné závislosti, má přibližně 8.2 KB v komprimaci gzip a splňuje WCAG 2.1 AA.

Tato stránka je úplná referenční příručka ke konfiguraci a přizpůsobení. Postup instalace pro jednotlivé platformy (WordPress, Shopify, Webflow, správci značek) najdete v průvodci instalací. Tento dokument si můžete přečíst také jako surový markdown.

Přehled

Vše řídí jediná značka skriptu. Po načtení snippet stáhne váš manifest a poté vykreslí pouze to, co manifest deklaruje:

Interakční banner pro systém typu conversational: upozornění, že návštěvník komunikuje s UI.
Upozornění na obsah pro systém typu content-generation s scope: site nebo scope: page: malý trvalý čip. Kliknutím se otevře krátké vysvětlení s textem upozornění, jménem vydavatele a účelem systému z manifestu a s odkazem na soubor manifestu; text upozornění odkazuje na srozumitelné vysvětlení na aidisclose.io. Odznak „vytvořeno lidmi“ otevírá stejnou kartu se jménem vydavatele.
Štítky u jednotlivých prvků u každého prvku, který označíte pomocí data-ai-content: viditelný odznak „UI“ a strojově čitelný atribut data-digital-source-type.
Metadata stránky: prvky <link rel="ai-disclosure"> a <meta name="ai-disclosure"> odkazující na váš manifest.
Odznak „vytvořeno lidmi“, když manifest nastaví noAiDeclared.

Vše níže je volitelné. Bez jakékoli konfigurace snippet čte váš soubor /.well-known/ai-disclosure.json, vykresluje se v jazyce návštěvníka napříč 28 jazyky, řídí se světlým nebo tmavým nastavením operačního systému a řadí se nad známé lišty se souhlasem s cookies, aby se ty dva prvky nikdy nepřekrývaly.

Instalace

Přidejte značku jednou, do sdílené šablony webu, hlavičky motivu nebo správce značek, a poběží na každé stránce. Může být umístěna v <head> nebo kdekoli před </body>; je odložená (deferred), takže umístění nemění chování:

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

Bez atributů snippet čte manifest na adrese https://YOURDOMAIN/.well-known/ai-disclosure.json. Pokud vaše platforma nedokáže servírovat soubor v kořeni domény, hostujte manifest u AIDisclose a nasměrujte na něj značku pomocí klíče:

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

Pokud manifest nelze načíst, snippet zapíše varování do konzole a nevykreslí žádná upozornění řízená manifestem, takže selhání stažení nikdy nezobrazí odhadované upozornění. Metadata stránky, vaše štítky [data-ai-content] a banner vynucený pomocí data-banner="true" se přesto vykreslí.

Konfigurace

Snippet lze nakonfigurovat třemi způsoby. Použijte ten, který vyhovuje vaší platformě.

1. Atributy na značce skriptu. Nejjednodušší cesta, bez dalšího kódu:

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

2. Globální konfigurační objekt. Definujte window.AIDiscloseConfig před spuštěním skriptu. Zpřístupňuje úplnou sadu možností včetně možností pro výběr prvků, které nemají podobu atributu:

<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. Ruční inicializace. Přidejte data-manual pro odložení automatického spuštění a poté sami zavolejte AIDisclose.init(), jakmile je vaše aplikace připravena (užitečné v jednostránkových aplikacích):

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

Pokud je přítomen více než jeden zdroj, vítězí window.AIDiscloseConfig: přepisuje jak atributy na značce skriptu, tak jakýkoli objekt předaný do AIDisclose.init().

Přehled možností

Sada možností je stabilní pro řadu 1.x.

Option	Attribute	Values	Default	Effect
`theme`	`data-theme`	`light`, `dark`, `auto`	`auto`	Barevné schéma. `auto` se řídí nastavením OS návštěvníka.
`siteKey`	`data-aidisclose`	řetězec	žádná	Načte manifest hostovaný u AIDisclose pro tento klíč místo souboru well-known.
`manifestUrl`	`data-manifest-url`	URL	`/.well-known/ai-disclosure.json`	Čte manifest z vlastní URL.
`lang`	`data-lang`	kód BCP-47	atribut stránky `<html lang>`, jinak jazyk návštěvníka	Vynutí jazyk zobrazení.
`banner`	`data-banner`	`true`, `false`	auto	Vynutí zapnutí nebo vypnutí interakčního banneru. Bez nastavení se zobrazí, jen když váš manifest deklaruje konverzační systém (chatbot).
`persistentChip`	—	`true`, `false`	`true`	Zobrazí nebo potlačí sbalený mini-čip interakčního banneru (malou pilulku, do které se banner minimalizuje).
`alwaysShow`	—	`true`, `false`	`false`	Zobrazí banner znovu při každé návštěvě a ignoruje předchozí zavření návštěvníkem (uložené v prohlížeči v `localStorage`).
`mountSelector`	—	selektor CSS	žádný	Vykreslí banner vloženě uvnitř tohoto prvku místo pevného překryvu u dolního okraje.
`triggerSelector`	—	selektor CSS	žádný	Zobrazí interakční banner až poté, co návštěvník klikne na tento prvek, například na spouštěč chatu. Stránky bez odpovídajícího prvku nezobrazí žádný banner, takže chatbot, který existuje jen na některých stránkách, zveřejní informaci pouze tam. Spouštěče vložené po načtení stále fungují. Návštěvník, který banner dříve zavřel, stále vidí mini-čip.
`adjacentSelector`	—	selektor CSS	žádný	Umístí štítek vedle prvku, který nelze označit přímo, například vedle zavřeného widgetu nebo prvku iframe.
`observe`	—	`true`, `false`	`true`	Sleduje DOM kvůli obsahu přidanému později a označuje jej. Na zcela statických stránkách nastavte `false`.
`beaconUrl`	—	URL	žádná	Odešle anonymní beacon `{siteKey, flag}` při významných událostech. Žádné cookies, žádné osobní údaje.

data-manual není hodnota možnosti: jeho přítomnost na značce odloží automatické spuštění, abyste mohli sami zavolat AIDisclose.init().

Motiv a vzhled

Vestavěné schéma nastavíte pomocí theme (light, dark nebo auto). Pro přesnou shodu s vaší značkou přepište vlastní vlastnosti CSS snippetu ve svém stylopise. Jsou definovány na .aid-banner, .aid-chip:

Variable	Controls
`--aid-bg`	Pozadí
`--aid-fg`	Text
`--aid-line`	Ohraničení
`--aid-btn`	Ohraničení tlačítka zavření
`--aid-btnfg`	Text tlačítka zavření
`--aid-hov`	Najetí myší na tlačítko zavření

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

Snippet neobsahuje žádná pravidla !important a používá selektory s nízkou specificitou, takže vaše CSS vítězí. Třídy pro napojení jsou .aid-banner, .aid-chip, .aid-badge, .aid-badge-inline, .aid-wrap, .aid-ai (upozornění na obsah) a .aid-hm („vytvořeno lidmi“). Odsazení, zaoblení a stín upravujte přímo na nich.

Ve výchozím nastavení je banner pevný překryv u dolního okraje výřezu. Nastavením mountSelector jej vykreslíte vloženě a staticky uvnitř prvku, který ovládáte, takže bude umístěn v rámci vašeho vlastního rozvržení.

Vlastní texty

Banner a čip obsahují přesný lokalizovaný text ve 28 jazycích rovnou po instalaci. Pro přepsání textu:

Podle jazyka, v manifestu. Přidejte k systému disclosure.texts s klíči podle kódu jazyka. Snippet použije váš text pro odpovídající jazyk návštěvní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." }
  }
}

Podle prvku. Přidejte data-ai-label k označenému prvku pro nastavení textu daného štítku.

Když systém nastaví editorialResponsibility.humanReview: true a jeho obsah není zcela vytvořen nebo upraven UI, upozornění automaticky uvádí „vytvořeno s pomocí UI, zkontrolováno člověkem“ v jazyce návštěvníka, místo „vytvořeno UI“.

Značení vašeho obsahu vytvořeného UI

Snippet označuje pouze to, co označíte vy. Přidejte data-ai-content k jakémukoli prvku vytvořenému 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ý prvek dostane viditelný odznak „UI“ a strojově čitelný atribut data-digital-source-type (ve výchozím nastavení trainedAlgorithmicMedia, hodnota kompatibilní s IPTC a schema.org). Přidejte data-ai-label pro vlastní text štítku, nebo sami nastavte data-digital-source-type pro větší přesnost.

Pro UI, které nemůžete anotovat přímo, například chatovací widget třetí strany v zavřeném prvku iframe, použijte adjacentSelector k umístění štítku vedle něj, nebo triggerSelector k zobrazení interakčního banneru při otevření widgetu.

Upozornění na generovaný obsah může pokrývat celý web (disclosure.scope: "site") nebo konkrétní stránky (disclosure.scope: "page" se seznamem disclosure.pages globů cest, například /blog/*). Shoda na úrovni stránky má přednost před shodou na úrovni webu a systém s rozsahem stránky bez odpovídající cesty tam nevykreslí nic.

Jednostránkové aplikace a frameworky

Snippet sleduje DOM pomocí MutationObserver a při změnách trasy znovu vyhodnocuje příslušné upozornění, takže obsah a stránky přidané po načtení jsou stále označeny. V jednostránkové aplikaci (SPA):

Ponechte observe ve výchozím nastavení (true), aby byl zachycen obsah vykreslovaný na straně klienta.
Pokud podmiňujete inicializaci připraveností aplikace, přidejte data-manual a zavolejte AIDisclose.init() po připojení vašeho frameworku.
Upozornění s rozsahem stránky se aktualizují automaticky při změně trasy; žádné volání pro každou trasu není potřeba.

Nastavte observe: false pouze na zcela statických stránkách, kde se po načtení nic nevkládá.

Content Security Policy

Pokud vynucujete Content Security Policy, povolte snippet výslovně.

Důležité

Striktní script-src 'self' tiše zablokuje snippet z CDN a informace o UI se nikdy nevykreslí. Toto je nejčastější důvod, proč správně deklarovaný web nedosáhne úrovně 2.

script-src: přidejte https://cdn.aidisclose.io, nebo hostujte aidisclose.js z vlastního původu a ponechte 'self'.
style-src: snippet vkládá své styly inline, takže 'unsafe-inline' postačí. Pokud inline styly nepovolíte, přejde na načtení aidisclose.css z adresáře skriptu, takže povolte také https://cdn.aidisclose.io v style-src (nebo tento soubor hostujte vedle skriptu sami).
connect-src: stažení manifestu je pro soubor well-known ze stejného původu a nevyžaduje nic navíc. Pokud načítáte manifest podle klíče, povolte https://cdn.aidisclose.io.

Manifest se stahuje bez přihlašovacích údajů, proto jej servírujte veřejně: koncový bod, který vyžaduje cookies nebo autentizaci, je neobdrží.

Správa verzí a integrita

CDN nabízí tři varianty:

/v1/aidisclose.js sleduje nejnovější vydání řady 1.x. Doporučeno pro většinu webů.
/v1.0.0/aidisclose.js je pevná, neměnná verze, kterou můžete připnout, se 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 nejnovější vydání napříč hlavními verzemi.

Pro získání hashe SRI k připnutí sestavte snippet: npm run build v packages/snippet jej vypíše (zdrojový kód je otevřený na GitHubu).

Sestavení vlastního rozhraní pro zveřejňování

Místo vestavěného rozhraní si můžete vykreslit vlastní rozhraní pro zveřejňování. Neexistuje jediný vypínač: data-banner="false" a persistentChip: false potlačí pouze interakční banner a jeho čip, zatímco upozornění na obsah, odznaky [data-ai-content] u jednotlivých prvků a odznak „vytvořeno lidmi“ se z vašeho manifestu a značek stále vykreslují. Zcela vlastní rozhraní znamená se na ně nespoléhat a vykreslit vlastní.

Poznámka

Nástroj pro kontrolu AIDisclose ověřuje vykreslení tím, že detekuje značky referenčního snippetu. Zcela ručně vytvořené zveřejnění je platné, ale není automaticky detekováno, takže web zůstane na úrovni 1 (deklarováno) místo úrovně 2 (vykresleno), pokud vaše vlastní značky nereprodukují to, co nástroj hledá. Pokud je pro vás úroveň 2 důležitá, ponechte vestavěné vykreslení a upravte jej pomocí CSS.

Přístupnost

Vykreslené rozhraní splňuje WCAG 2.1 AA: viditelné obrysy :focus-visible na interaktivních ovládacích prvcích, správné role a popisky, kontrast, který drží ve světlém i tmavém režimu, a animace podmíněná nastavením prefers-reduced-motion. Snippet také detekuje známé lišty se souhlasem s cookies a řadí se nad ně, takže informace o UI nikdy nezůstanou skryté za CMP. Na velmi úzkých obrazovkách se interakční banner otevírá jako kompaktní čip, takže nikdy nezakrývá obsah.

#Přehled

#Instalace

#Konfigurace

#Přehled možností

#Motiv a vzhled

#Vlastní texty

#Značení vašeho obsahu vytvořeného UI

#Jednostránkové aplikace a frameworky

#Content Security Policy

#Správa verzí a integrita

#Sestavení vlastního rozhraní pro zveřejňování

#Přístupnost