Snippetin ohjeistus: määritä ja mukauta

aidisclose.js on sivustolla toimiva skripti, joka lukee ai-disclosure.json-manifestisi ja näyttää lain edellyttämät ilmoitukset: chatboteille tarkoitetun vuorovaikutusbannerin, pysyvän sisältöilmoituksen, näkyvät merkinnät merkitylle medialle ja koneluettavan sivun metatiedon. Se on riippuvuudeton, gzip-pakattuna noin 8.2 KB, ja täyttää WCAG 2.1 AA -vaatimukset.

Tämä sivu on täydellinen asetusten ja mukauttamisen ohjeistus. Alustakohtaiset asennusvaiheet (WordPress, Shopify, Webflow, tunnistehallinta) löytyvät asennusoppaasta. Voit myös lukea tämän asiakirjan raakana Markdownina.

Yleiskatsaus

Yksi skriptitunniste ohjaa kaikkea. Latauksen yhteydessä snippet hakee manifestisi ja näyttää sitten vain sen, mitä manifesti julistaa:

Vuorovaikutusbanneri, conversational-järjestelmälle: ilmoitus siitä, että kävijä keskustelee tekoälyn kanssa.
Sisältöilmoitus, content-generation-järjestelmälle asetuksella scope: site tai scope: page: pieni pysyvä siru. Sitä napsauttamalla avautuu lyhyt selitys, jossa on ilmoitusteksti, manifestista poimittu julkaisijan nimi ja järjestelmän tarkoitus sekä linkki manifestitiedostoon; ilmoitusteksti linkittää selkokieliseen selitteeseen osoitteessa aidisclose.io. "Made by humans" -merkki avaa saman kortin julkaisijan nimen kera.
Elementtikohtaiset merkinnät, jokaisessa elementissä, jonka merkitset attribuutilla data-ai-content: näkyvä "AI"-merkki sekä koneluettava data-digital-source-type.
Sivun metatieto: manifestiisi osoittava <link rel="ai-disclosure"> ja <meta name="ai-disclosure">.
"Made by humans" -merkki, kun manifesti asettaa noAiDeclared.

Kaikki alla oleva on valinnaista. Ilman asetuksia snippet lukee /.well-known/ai-disclosure.json-tiedostosi, näyttää sisällön kävijän kielellä 28 kielialueella, noudattaa käyttöjärjestelmän vaaleaa tai tummaa asetusta ja asettuu tunnettujen evästesuostumuspalkkien yläpuolelle, jotta ne eivät koskaan mene päällekkäin.

Asennus

Lisää tunniste kerran sivustosi jaettuun mallipohjaan, teeman ylätunnisteeseen tai tunnistehallintaan, niin se toimitetaan jokaisella sivulla. Se voi sijaita elementissä <head> tai missä tahansa ennen elementtiä </body>; se on viivästetty, joten sijainti ei muuta toimintaa:

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

Ilman attribuutteja snippet lukee manifestin osoitteesta https://YOURDOMAIN/.well-known/ai-disclosure.json. Jos alustasi ei voi tarjoilla tiedostoa verkkotunnuksen juuresta, isännöi manifesti AIDisclosen kautta ja osoita tunniste siihen avaimella:

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

Jos manifestiin ei saada yhteyttä, snippet kirjaa konsolivaroituksen eikä näytä manifestipohjaisia ilmoituksia, joten haun epäonnistuminen ei koskaan näytä arvattua ilmoitusta. Sivun metatieto, [data-ai-content]-merkintäsi ja attribuutilla data-banner="true" pakotettu banneri näytetään silti.

Asetukset

Snippetin voi määrittää kolmella tavalla. Käytä sitä, joka sopii alustallesi.

1. Attribuutit skriptitunnisteessa. Yksinkertaisin tapa, ei lisäkoodia:

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

2. Globaali asetusobjekti. Määritä window.AIDiscloseConfig ennen skriptin suoritusta. Se tarjoaa koko asetusvalikoiman, mukaan lukien valitsinasetukset, joilla ei ole attribuuttimuotoa:

<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. Manuaalinen alustus. Lisää data-manual viivästääksesi automaattista käynnistystä, ja kutsu sitten itse AIDisclose.init() kun sovelluksesi on valmis (hyödyllistä yhden sivun sovelluksissa):

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

Jos useampi kuin yksi lähde on läsnä, window.AIDiscloseConfig voittaa: se ohittaa sekä skriptitunnisteen attribuutit että kaiken, mikä välitetään metodille AIDisclose.init().

Asetusten ohjeistus

Asetusrajapinta on vakaa 1.x-sarjassa.

Option	Attribute	Values	Default	Effect
`theme`	`data-theme`	`light`, `dark`, `auto`	`auto`	Väriteema. `auto` noudattaa kävijän käyttöjärjestelmän asetusta.
`siteKey`	`data-aidisclose`	merkkijono	ei mitään	Lataa tälle avaimelle AIDisclosen isännöimä manifesti well-known-tiedoston sijaan.
`manifestUrl`	`data-manifest-url`	URL	`/.well-known/ai-disclosure.json`	Lue manifesti mukautetusta URL-osoitteesta.
`lang`	`data-lang`	BCP-47-koodi	sivun `<html lang>`, muutoin kävijän kieli	Pakota näyttökieli.
`banner`	`data-banner`	`true`, `false`	auto	Pakota vuorovaikutusbanneri päälle tai pois. Ilman asetusta se näytetään vain, kun manifestisi julistaa conversational-järjestelmän (chatbot).
`persistentChip`	—	`true`, `false`	`true`	Näytä tai piilota vuorovaikutusbannerin pienennetty minisiru (pieni pilleri, johon se pienenee).
`alwaysShow`	—	`true`, `false`	`false`	Näytä banneri uudelleen jokaisella käynnillä ohittaen kävijän aiemman sulkemisen (muistetaan selaimen `localStorage`-tallennuksessa).
`mountSelector`	—	CSS-valitsin	ei mitään	Näytä banneri sisäkkäin tämän elementin sisällä kiinteän alareunan peittokuvan sijaan.
`triggerSelector`	—	CSS-valitsin	ei mitään	Näytä vuorovaikutusbanneri vasta, kun kävijä napsauttaa tätä elementtiä, esimerkiksi chatin käynnistintä. Sivuilla, joilla ei ole vastaavaa elementtiä, ei näytetä banneria, joten vain joillakin sivuilla oleva chatbot ilmoittaa vain siellä. Latauksen jälkeen lisätyt käynnistimet toimivat silti. Kävijä, joka sulki bannerin aiemmin, näkee edelleen minisirun.
`adjacentSelector`	—	CSS-valitsin	ei mitään	Sijoita merkintä sellaisen elementin viereen, jota et voi merkitä suoraan, kuten suljettu widget tai iframe.
`observe`	—	`true`, `false`	`true`	Tarkkaile DOMia myöhemmin lisätyn sisällön varalta ja merkitse se. Aseta arvoon `false` täysin staattisilla sivuilla.
`beaconUrl`	—	URL	ei mitään	Lähetä anonyymi `{siteKey, flag}`-signaali merkittävistä tapahtumista. Ei evästeitä, ei henkilötietoja.

data-manual ei ole asetusarvo: sen läsnäolo tunnisteessa viivästää automaattista käynnistystä, jotta voit itse kutsua metodia AIDisclose.init().

Teemoitus ja ulkoasu

Aseta sisäänrakennettu teema asetuksella theme (light, dark tai auto). Jotta ulkoasu vastaisi brändiäsi tarkasti, ohita snippetin CSS-mukautetut ominaisuudet omassa tyylitiedostossasi. Ne on määritetty valitsimissa .aid-banner, .aid-chip:

Variable	Controls
`--aid-bg`	Tausta
`--aid-fg`	Teksti
`--aid-line`	Reunus
`--aid-btn`	Sulkupainikkeen reunus
`--aid-btnfg`	Sulkupainikkeen teksti
`--aid-hov`	Sulkupainikkeen osoitus

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

Snippet ei toimita !important-sääntöjä ja käyttää matalan spesifisyyden valitsimia, joten oma CSS-tyylisi voittaa. Luokkakoukut ovat .aid-banner, .aid-chip, .aid-badge, .aid-badge-inline, .aid-wrap, .aid-ai (sisältöilmoitus) ja .aid-hm ("made by humans"). Muotoile välistys, kulmapyöristys ja varjo suoraan näihin.

Oletuksena banneri on kiinteä peittokuva näkymän alareunassa. Aseta mountSelector, niin se näytetään sisäkkäin ja staattisesti hallinnassasi olevan elementin sisällä, jolloin se asettuu omaan asetteluusi.

Mukautettu teksti

Banneri ja siru sisältävät oletuksena tarkan lokalisoidun tekstin 28 kielellä. Tekstin ohittaminen:

Kielikohtaisesti manifestissa. Lisää järjestelmään disclosure.texts kielikoodilla avainnettuna. Snippet käyttää tekstiäsi kävijän kielelle:

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

Elementtikohtaisesti. Lisää merkittyyn elementtiin data-ai-label asettaaksesi kyseisen merkin tekstin.

Kun järjestelmä asettaa editorialResponsibility.humanReview: true eikä sen sisältö ole täysin tekoälyn tuottamaa tai muokkaamaa, ilmoituksessa lukee automaattisesti "AI-assisted, human-reviewed" kävijän kielellä tekstin "AI-generated" sijaan.

Tekoälysisällön merkitseminen

Snippet merkitsee vain sen, minkä itse merkitset. Lisää data-ai-content mihin tahansa tekoälyn tuottamaan elementtiin:

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

Jokainen merkitty elementti saa näkyvän "AI"-merkin ja koneluettavan data-digital-source-type-attribuutin (oletusarvona trainedAlgorithmicMedia, joka on IPTC- ja schema.org-yhteensopiva arvo). Lisää data-ai-label mukautettua merkintätekstiä varten tai aseta data-digital-source-type itse ollaksesi tarkempi.

Tekoälylle, jota et voi merkitä suoraan, kuten kolmannen osapuolen chat-widget suljetussa iframessa, käytä adjacentSelector-asetusta sijoittaaksesi merkinnän sen viereen tai triggerSelector-asetusta paljastaaksesi vuorovaikutusbannerin, kun widget avataan.

Sisällöntuotannon ilmoitus voi kattaa koko sivuston (disclosure.scope: "site") tai tietyt sivut (disclosure.scope: "page" yhdessä disclosure.pages-listan kanssa, joka sisältää polkujokerimerkkejä, kuten /blog/*). Sivukohtainen osuma ohittaa sivustolaajuisen, ja sivukohtainen järjestelmä, jolla ei ole vastaavaa polkua, ei näytä siellä mitään.

Yhden sivun sovellukset ja kehykset

Snippet tarkkailee DOMia MutationObserver-tarkkailijalla ja arvioi sovellettavan ilmoituksen uudelleen reittimuutosten yhteydessä, joten latauksen jälkeen lisätyt sisällöt ja sivut merkitään edelleen. Yhden sivun sovelluksessa:

Pidä observe oletusarvossaan (true), jotta asiakaspäässä renderöity sisältö tunnistetaan.
Jos rajoitat alustuksen sovelluksen valmiuteen, lisää data-manual ja kutsu AIDisclose.init() kehyksesi kiinnittymisen jälkeen.
Sivukohtaiset ilmoitukset päivittyvät automaattisesti reitin muuttuessa; reittikohtaista kutsua ei tarvita.

Aseta observe: false vain täysin staattisilla sivuilla, joilla mitään ei lisätä latauksen jälkeen.

Sisällön suojauskäytäntö

Jos otat käyttöön sisällön suojauskäytännön, salli snippet erikseen.

Tärkeää

Tiukka script-src 'self' estää CDN-snippetin äänettömästi, eikä ilmoituksia koskaan näytetä. Tämä on yleisin syy siihen, ettei oikein julistettu sivusto yllä tasolle 2.

script-src: lisää https://cdn.aidisclose.io tai isännöi aidisclose.js omalta lähtöpaikaltasi ja säilytä 'self'.
style-src: snippet lisää tyylinsä sisäisesti, joten 'unsafe-inline' riittää. Jos et salli sisäisiä tyylejä, se turvautuu lataamaan aidisclose.css-tiedoston skriptin hakemistosta, joten salli myös https://cdn.aidisclose.io kohdassa style-src (tai isännöi kyseinen tiedosto skriptin rinnalla).
connect-src: manifestin haku on well-known-tiedostolle samalta lähtöpaikalta eikä vaadi mitään ylimääräistä. Jos lataat manifestin avaimella, salli https://cdn.aidisclose.io.

Manifesti haetaan ilman tunnistetietoja, joten tarjoile se julkisesti: päätepiste, joka vaatii evästeitä tai todennusta, ei niitä saa.

Versiointi ja eheys

CDN tarjoilee kolme raidetta:

/v1/aidisclose.js seuraa uusinta 1.x-julkaisua. Suositellaan useimmille sivustoille.
/v1.0.0/aidisclose.js on kiinteä, muuttumaton versio, jonka voit lukita, alaresurssin eheydellä (Subresource Integrity):

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

/latest/aidisclose.js seuraa aina uusinta julkaisua pääversioiden yli.

Saadaksesi lukittavan SRI-tiivisteen, rakenna snippet: npm run build hakemistossa packages/snippet tulostaa sen (lähdekoodi on avoimena GitHubissa).

Oman ilmoituskäyttöliittymän rakentaminen

Voit renderöidä oman ilmoituskäyttöliittymän sisäänrakennetun sijaan. Yksittäistä katkaisinta ei ole: data-banner="false" ja persistentChip: false piilottavat vain vuorovaikutusbannerin ja sen sirun, kun taas sisältöilmoitukset, elementtikohtaiset [data-ai-content]-merkit ja "made by humans" -merkki näytetään edelleen manifestisi ja merkintöjesi perusteella. Täysin mukautettu käyttöliittymä tarkoittaa, ettei näihin turvauduta vaan renderöidään oma.

Huomautus

AIDisclosen tarkistin varmentaa renderöinnin tunnistamalla referenssisnippetin merkinnän. Täysin käsin rakennettu ilmoitus on pätevä, mutta sitä ei tunnisteta automaattisesti, joten sivusto pysyy tasolla 1 (julistettu) tason 2 (renderöity) sijaan, ellei mukautettu merkintäsi toista sitä, mitä tarkistin etsii. Jos taso 2 on sinulle tärkeä, säilytä sisäänrakennettu renderöinti ja muotoile se uudelleen CSS:llä.

Saavutettavuus

Renderöity käyttöliittymä täyttää WCAG 2.1 AA -vaatimukset: näkyvät :focus-visible-ääriviivat vuorovaikutteisissa säätimissä, oikeat roolit ja nimikkeet, kontrasti joka säilyy vaaleassa ja tummassa teemassa sekä animaatio, jota ohjaa prefers-reduced-motion. Snippet myös tunnistaa tunnetut evästesuostumuspalkit ja asettuu niiden yläpuolelle, jotta ilmoitukset eivät koskaan jää suostumushallinnan taakse. Hyvin kapeilla näytöillä vuorovaikutusbanneri avautuu kompaktina siruna, jotta se ei koskaan peitä sisältöä.

#Yleiskatsaus

#Asennus

#Asetukset

#Asetusten ohjeistus

#Teemoitus ja ulkoasu

#Mukautettu teksti

#Tekoälysisällön merkitseminen

#Yhden sivun sovellukset ja kehykset

#Sisällön suojauskäytäntö

#Versiointi ja eheys

#Oman ilmoituskäyttöliittymän rakentaminen

#Saavutettavuus