AIDisclose
Kezdés
ENFRHU

Dokumentáció

Az AIDisclose kódrészlet

Beállítási és testreszabási referencia

Megnyitás Markdown formátumban Telepítési útmutató Forráskód a GitHubon

Az aidisclose.js az a helyszíni szkript, amely beolvassa az ai-disclosure.json manifesztumot, és megjeleníti a jogszabály által előírt közzétételeket: interakciós sávot a chatbotokhoz, tartós tartalmi értesítést, látható címkéket a megjelölt médián, valamint géppel olvasható oldalmetaadatokat. Függőségektől mentes, gzip-tömörítve körülbelül 8.2 KB, és megfelel a WCAG 2.1 AA követelményeinek.

Ez az oldal a teljes beállítási és testreszabási referencia. A platformonkénti telepítési lépésekért (WordPress, Shopify, Webflow, címkekezelők) lásd a telepítési útmutatót. Ezt a dokumentumot nyers markdown formátumban is elolvashatja.

Áttekintés

Egyetlen szkriptcímke mindent vezérel. Betöltéskor a kódrészlet letölti a manifesztumot, majd csak azt jeleníti meg, amit a manifesztum bejelent:

  • Interakciós sáv, conversational rendszerhez: értesítés arról, hogy a látogató MI-vel beszélget.
  • Tartalmi értesítés, scope: site vagy scope: page beállítású content-generation rendszerhez: egy kis tartós jelvény. Rákattintva rövid magyarázat nyílik meg az értesítés szövegével, a manifesztumból származó kiadói névvel és rendszercéllal, valamint a manifesztumfájlra mutató hivatkozással; az értesítés szövege egy közérthető magyarázatra hivatkozik az aidisclose.io oldalon. Az „emberek készítették” jelvény ugyanezt a kártyát nyitja meg a kiadói névvel.
  • Elemenkénti címkék, minden olyan elemen, amelyet data-ai-content attribútummal jelöl meg: egy látható „MI” jelvény, valamint egy géppel olvasható data-digital-source-type.
  • Oldalmetaadatok: egy <link rel="ai-disclosure"> és egy <meta name="ai-disclosure">, amelyek a manifesztumra mutatnak.
  • „Emberek készítették” jelvény, ha a manifesztum beállítja a noAiDeclared értéket.

Az alábbiak mind opcionálisak. Beállítás nélkül a kódrészlet a /.well-known/ai-disclosure.json fájlt olvassa be, a látogató nyelvén jelenik meg 28 nyelven, követi az operációs rendszer világos vagy sötét beállítását, és az ismert cookie-hozzájárulási sávok fölé rendeződik, így a kettő soha nem fedi egymást.

Telepítés

Adja hozzá a címkét egyszer a webhely közös sablonjában, a téma fejlécében vagy a címkekezelőben, és minden oldallal együtt betöltődik. Elhelyezhető a <head> szakaszban vagy bárhol a </body> előtt; késleltetett (deferred) betöltésű, így az elhelyezés nem változtatja meg a viselkedést:

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

Attribútumok nélkül a kódrészlet a https://YOURDOMAIN/.well-known/ai-disclosure.json címen olvassa be a manifesztumot. Ha a platformja nem tud fájlt kiszolgálni a domain gyökeréből, tárolja a manifesztumot az AIDisclose-nál, és kulcs alapján hivatkozzon rá a címkében:

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

Ha a manifesztum nem érhető el, a kódrészlet figyelmeztetést ír a konzolra, és nem jelenít meg manifesztum-vezérelt értesítéseket, így egy sikertelen letöltés soha nem mutat kitalált értesítést. Az oldalmetaadatok, a [data-ai-content] címkéi és a data-banner="true" beállítással kikényszerített sáv továbbra is megjelennek.

Beállítás

A kódrészlet háromféleképpen állítható be. Használja azt, amelyik a platformjához illik.

1. Attribútumok a szkriptcímkén. A legegyszerűbb út, extra kód nélkül:

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

2. Globális konfigurációs objektum. Határozza meg a window.AIDiscloseConfig objektumot, mielőtt a szkript lefut. Ez a teljes beállításkészletet elérhetővé teszi, beleértve azokat a szelektor-beállításokat is, amelyeknek nincs attribútumos formája:

<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. Kézi inicializálás. Adja hozzá a data-manual attribútumot az automatikus indítás késleltetéséhez, majd hívja meg saját maga az AIDisclose.init() függvényt, amint az alkalmazása készen áll (egyoldalas alkalmazásokban hasznos):

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

Ha egynél több forrás van jelen, a window.AIDiscloseConfig az irányadó: felülírja mind a szkriptcímke attribútumait, mind az AIDisclose.init() függvénynek átadott objektumot.

Beállítások referenciája

A beállítási felület stabil az 1.x sorozatban.

Beállítás Attribútum Értékek Alapértelmezett Hatás
theme data-theme light, dark, auto auto Színséma. Az auto a látogató operációs rendszerének beállítását követi.
siteKey data-aidisclose szöveg nincs Az ehhez a kulcshoz tartozó, AIDisclose által tárolt manifesztum betöltése a well-known fájl helyett.
manifestUrl data-manifest-url URL /.well-known/ai-disclosure.json A manifesztum beolvasása egyéni URL-ről.
lang data-lang BCP-47 kód az oldal <html lang> értéke, egyébként a látogató nyelve Megjelenítési nyelv kényszerítése.
banner data-banner true, false auto Az interakciós sáv be- vagy kikapcsolásának kényszerítése. Beállítás nélkül csak akkor jelenik meg, ha a manifesztum társalgási (chatbot) rendszert jelent be.
persistentChip — true, false true Az interakciós sáv összecsukott mini-jelvényének (a kis pirula, amivé lekicsinyül) megjelenítése vagy elrejtése.
alwaysShow — true, false false A sáv újbóli megjelenítése minden látogatáskor, figyelmen kívül hagyva a látogató korábbi elutasítását (amelyet a böngésző localStorage-a tárol).
mountSelector — CSS-szelektor nincs A sáv beágyazott megjelenítése ezen az elemen belül a rögzített alsó átfedés helyett.
triggerSelector — CSS-szelektor nincs Az interakciós sáv csak azután jelenik meg, hogy a látogató erre az elemre kattint, például egy chatindítóra. Az egyező elemet nem tartalmazó oldalakon nem jelenik meg sáv, így egy csak bizonyos oldalakon létező chatbot csak ott közöl. A betöltés után beszúrt indítók is működnek. Az a látogató, aki korábban elutasította a sávot, továbbra is látja a mini-jelvényt.
adjacentSelector — CSS-szelektor nincs Címke elhelyezése olyan elem mellé, amelyet nem tud közvetlenül megjelölni, például egy zárt widget vagy egy iframe mellé.
observe — true, false true A DOM figyelése a később hozzáadott tartalmakért, és azok címkézése. Teljesen statikus oldalakon állítsa false értékre.
beaconUrl — URL nincs Anonim {siteKey, flag} jelzés küldése jelentős események esetén. Nincsenek cookie-k, nincsenek személyes adatok.

A data-manual nem beállításérték: jelenléte a címkén késlelteti az automatikus indítást, hogy saját maga hívhassa meg az AIDisclose.init() függvényt.

Témázás és megjelenés

A beépített sémát a theme beállítással adhatja meg (light, dark vagy auto). A márkájával való pontos egyezéshez írja felül a kódrészlet CSS egyéni tulajdonságait a saját stíluslapjában. Ezek a .aid-banner, .aid-chip szelektorokon vannak meghatározva:

Változó Vezérli
--aid-bg Háttér
--aid-fg Szöveg
--aid-line Szegély
--aid-btn Az elvetés gomb szegélye
--aid-btnfg Az elvetés gomb szövege
--aid-hov Az elvetés gomb hover állapota 
.aid-banner, .aid-chip {
  --aid-bg: #0b1020;
  --aid-fg: #e8eaed;
  --aid-line: #2a2f36;
}

A kódrészlet nem tartalmaz !important szabályokat, és alacsony specificitású szelektorokat használ, így az Ön CSS-e érvényesül. A kapaszkodó osztályok: .aid-banner, .aid-chip, .aid-badge, .aid-badge-inline, .aid-wrap, .aid-ai (tartalmi értesítés) és .aid-hm („emberek készítették”). A térközt, a lekerekítést és az árnyékot közvetlenül ezeken szabhatja át.

Alapértelmezés szerint a sáv egy rögzített átfedés a nézetablak alján. Állítsa be a mountSelector értékét, hogy beágyazottan és statikusan jelenjen meg egy Ön által vezérelt elemen belül, így a saját elrendezésébe illeszkedik.

Egyéni szövegezés

A sáv és a jelvény alapból pontos, honosított szöveget tartalmaz 28 nyelven. A szövegezés felülírásához:

  • Nyelvenként, a manifesztumban. Adja hozzá a disclosure.texts mezőt egy rendszerhez, nyelvi kód szerint kulcsolva. A kódrészlet az Ön szövegét használja az egyező látogatói nyelvhez:
{
  "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." }
  }
}
  • Elemenként. Adja hozzá a data-ai-label attribútumot egy megjelölt elemhez az adott jelvény címkéjének beállításához.

Ha egy rendszer beállítja az editorialResponsibility.humanReview: true értéket, és a tartalma nem teljesen MI által generált vagy manipulált, az értesítés automatikusan „MI-vel segített, ember által ellenőrzött” szöveget jelenít meg a látogató nyelvén, az „MI által generált” helyett.

Az MI-tartalom megjelölése

A kódrészlet csak azt címkézi, amit megjelöl. Adja hozzá a data-ai-content attribútumot bármely MI által generált elemhez:

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

Minden megjelölt elem kap egy látható „MI” jelvényt és egy géppel olvasható data-digital-source-type attribútumot (alapértelmezés szerint trainedAlgorithmicMedia, egy IPTC- és schema.org-kompatibilis érték). Egyéni címkeszöveghez adja hozzá a data-ai-label attribútumot, vagy állítsa be saját maga a data-digital-source-type értékét a pontosabb meghatározáshoz.

Az olyan MI-hez, amelyet nem tud közvetlenül megjelölni, például egy zárt iframe-ben lévő külső féltől származó chat-widgethez, használja az adjacentSelector beállítást címke elhelyezéséhez mellette, vagy a triggerSelector beállítást az interakciós sáv megjelenítéséhez, amikor a widget megnyílik.

Egy tartalomgenerálási értesítés kiterjedhet a teljes webhelyre (disclosure.scope: "site") vagy meghatározott oldalakra (disclosure.scope: "page" a disclosure.pages útvonalmintáinak listájával, például /blog/*). Az oldalszintű egyezés elsőbbséget élvez a webhelyszintűvel szemben, és egy oldalszintű rendszer, amelynek nincs egyező útvonala, ott semmit nem jelenít meg.

Egyoldalas alkalmazások és keretrendszerek

A kódrészlet egy MutationObserver segítségével figyeli a DOM-ot, és útvonalváltáskor újraértékeli az alkalmazandó értesítést, így a betöltés után hozzáadott tartalmak és oldalak is címkézésre kerülnek. Egy SPA esetén:

  • Hagyja az observe beállítást az alapértelmezett (true) értéken, hogy a kliensoldalon renderelt tartalmat is elkapja.
  • Ha az inicializálást az alkalmazás készenlétéhez köti, adja hozzá a data-manual attribútumot, és hívja meg az AIDisclose.init() függvényt, miután a keretrendszere csatlakozott (mount).
  • Az oldalszintű értesítések automatikusan frissülnek az útvonal változásakor; nincs szükség útvonalankénti hívásra.

Az observe: false beállítást csak teljesen statikus oldalakon használja, ahol a betöltés után semmit nem szúrnak be.

Content Security Policy

Ha Content Security Policy-t érvényesít, engedélyezze kifejezetten a kódrészletet.

Fontos

Egy szigorú script-src 'self' csendben blokkolja a CDN-ről betöltött kódrészletet, és a közzétételek soha nem jelennek meg. Ez a leggyakoribb oka annak, hogy egy helyesen bejelentett webhely nem éri el a 2. szintet.

  • script-src: adja hozzá a https://cdn.aidisclose.io címet, vagy tárolja saját maga az aidisclose.js fájlt a saját tartományában, és tartsa meg a 'self' értéket.
  • style-src: a kódrészlet beágyazottan (inline) szúrja be a stílusait, így az 'unsafe-inline' elegendő. Ha nem engedélyezi a beágyazott stílusokat, akkor tartalékként a szkript könyvtárából tölti be az aidisclose.css fájlt, ezért engedélyezze a https://cdn.aidisclose.io címet a style-src szabályban is (vagy tárolja saját maga ezt a fájlt a szkript mellett).
  • connect-src: a well-known fájl esetén a manifesztum letöltése azonos tartományból történik, és nincs szükség további engedélyre. Ha a manifesztumot kulcs alapján tölti be, engedélyezze a https://cdn.aidisclose.io címet.

A manifesztum letöltése hitelesítő adatok nélkül történik, ezért nyilvánosan szolgálja ki: egy olyan végpont, amely cookie-kat vagy hitelesítést igényel, nem fogja megkapni azokat.

Verziókezelés és integritás

A CDN három sávot szolgál ki:

  • A /v1/aidisclose.js a legújabb 1.x kiadást követi. A legtöbb webhely számára ez ajánlott.
  • A /v1.0.0/aidisclose.js egy rögzített, változatlan verzió, amelyet rögzíthet, Subresource Integrity támogatással:
<script src="https://cdn.aidisclose.io/v1.0.0/aidisclose.js"
        integrity="sha384-…" crossorigin="anonymous" defer></script>
  • A /latest/aidisclose.js mindig a legújabb kiadást követi, a fő verziókon átívelően.

A rögzítéshez szükséges SRI-hash megszerzéséhez fordítsa le a kódrészletet: a packages/snippet mappában futtatott npm run build kiírja azt (a forráskód nyíltan elérhető a GitHubon).

Saját közzétételi felület építése

A beépített helyett saját közzétételi felületet is megjeleníthet. Nincs egyetlen kikapcsológomb: a data-banner="false" és a persistentChip: false csak az interakciós sávot és annak jelvényét némítja el, míg a tartalmi értesítések, az elemenkénti [data-ai-content] jelvények és az „emberek készítették” jelvény továbbra is megjelennek a manifesztumból és a jelölésből. A teljesen egyéni felület azt jelenti, hogy nem támaszkodik ezekre, és a sajátját jeleníti meg.

Megjegyzés

Az AIDisclose ellenőrző a referencia-kódrészlet jelölésének felismerésével igazolja a megjelenítést. Egy teljesen kézzel épített közzététel érvényes, de nem ismerhető fel automatikusan, így a webhely az 1. szinten (Bejelentett) marad a 2. szint (Megjelenített) helyett, hacsak az egyéni jelölése nem reprodukálja azt, amit az ellenőrző keres. Ha a 2. szint fontos Önnek, tartsa meg a beépített megjelenítést, és szabja át CSS-sel.

Akadálymentesség

A megjelenített felület megfelel a WCAG 2.1 AA követelményeinek: látható :focus-visible körvonalak az interaktív vezérlőkön, helyes szerepek és címkék, világos és sötét témában is megfelelő kontraszt, valamint a prefers-reduced-motion mögé zárt animáció. A kódrészlet felismeri az ismert cookie-hozzájárulási sávokat is, és föléjük rendeződik, így a közzétételeket soha nem takarja el egy CMP. Nagyon keskeny képernyőkön az interakciós sáv a kompakt jelvény formájában nyílik meg, így soha nem takarja el a tartalmat.