Koodijupi teatmik: seadistamine ja kohandamine

aidisclose.js on saidil töötav skript, mis loeb teie ai-disclosure.json manifesti ja kuvab seadusega nõutud avalikustused: vestlusrobotite interaktsiooniriba, püsiva sisuteatise, nähtavad sildid märgistatud meedial ning masinloetavad lehe metaandmed. See on sõltuvusteta, umbes 8.2 KB gzip-pakituna, ja vastab standardile WCAG 2.1 AA.

See leht on täielik seadistuse ja kohanduse teatmik. Platvormipõhiste paigaldussammude jaoks (WordPress, Shopify, Webflow, sildihaldurid) vaadake paigaldusjuhendit. Selle dokumendi saab lugeda ka toorel Markdown-kujul.

Ülevaade

Kõike juhib üksainus skriptisilt. Laadimisel toob koodijupp teie manifesti ja kuvab seejärel ainult selle, mida manifest deklareerib:

Interaktsiooniriba conversational süsteemi jaoks: teatis, et külastaja suhtleb TI-ga.
Sisuteatis content-generation süsteemi jaoks, millel on scope: site või scope: page: väike püsiv kiip. Sellele klõpsates avaneb lühike selgitus koos teatise teksti, teie manifestist pärit avaldaja nime ja süsteemi otstarbega ning lingiga manifestifailile; teatise tekst lingib arusaadavas keeles selgitusele saidil aidisclose.io. Märk „made by humans” avab sama kaardi koos avaldaja nimega.
Elemendipõhised sildid igal elemendil, mille märgistate atribuudiga data-ai-content: nähtav märk „AI” ja masinloetav data-digital-source-type.
Lehe metaandmed: teie manifestile osutavad <link rel="ai-disclosure"> ja <meta name="ai-disclosure">.
Märk „made by humans”, kui manifest määrab noAiDeclared.

Kõik allpool kirjeldatu on valikuline. Seadistuseta loeb koodijupp teie /.well-known/ai-disclosure.json, kuvab sisu külastaja keeles 28 lokaadis, järgib operatsioonisüsteemi heledat või tumedat eelistust ning paigutub tuntud küpsisenõusoleku ribade kohale, nii et need kaks kunagi ei kattu.

Paigaldamine

Lisage silt üks kord oma saidi ühismalli, teemapäisesse või sildihaldurisse ning see läheb kaasa iga lehega. See võib asuda <head> sees või kus tahes enne </body>; see on edasilükatud, seega paigutus ei muuda käitumist:

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

Atribuutideta loeb koodijupp manifesti aadressilt https://YOURDOMAIN/.well-known/ai-disclosure.json. Kui teie platvorm ei saa serveerida faili domeeni juurkataloogis, majutage manifest AIDisclose'i juures ja suunake silt sellele võtme kaudu:

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

Kui manifestini ei jõuta, logib koodijupp konsoolihoiatuse ega kuva ühtki manifestist juhitud teatist, nii et toomistõrge ei näita kunagi oletatud teatist. Lehe metaandmed, teie [data-ai-content] sildid ja atribuudiga data-banner="true" sunniviisiliselt kuvatud riba renderdatakse ikkagi.

Seadistamine

Koodijupi seadistamiseks on kolm viisi. Kasutage seda, mis teie platvormile sobib.

1. Atribuudid skriptisildil. Lihtsaim tee, ilma lisakoodita:

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

2. Globaalne seadistusobjekt. Määrake window.AIDiscloseConfig enne skripti käivitumist. See avab kogu valikute komplekti, sealhulgas selektorivalikud, millel puudub atribuudivorm:

<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äsitsi lähtestamine. Lisage data-manual, et lükata automaatkäivitus edasi, ja kutsuge seejärel ise välja AIDisclose.init(), kui teie rakendus on valmis (kasulik ühelehelistes rakendustes):

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

Kui kohal on rohkem kui üks allikas, võidab window.AIDiscloseConfig: see alistab nii skriptisildi atribuudid kui ka AIDisclose.init()-le edastatud objekti.

Valikute teatmik

Valikute komplekt on 1.x liinis stabiilne.

Option	Attribute	Values	Default	Effect
`theme`	`data-theme`	`light`, `dark`, `auto`	`auto`	Värviskeem. `auto` järgib külastaja operatsioonisüsteemi eelistust.
`siteKey`	`data-aidisclose`	sõne	puudub	Laadi selle võtme jaoks AIDisclose'i majutatud manifest well-known faili asemel.
`manifestUrl`	`data-manifest-url`	URL	`/.well-known/ai-disclosure.json`	Loe manifest kohandatud aadressilt.
`lang`	`data-lang`	BCP-47 kood	lehe `<html lang>`, muidu külastaja keel	Sunni kuvakeel.
`banner`	`data-banner`	`true`, `false`	automaatne	Sunni interaktsiooniriba sisse või välja. Määramata jätmisel kuvatakse see ainult siis, kui teie manifest deklareerib vestlusliku (vestlusroboti) süsteemi.
`persistentChip`	—	`true`, `false`	`true`	Kuva või peida interaktsiooniriba kokkuvolditud minikiip (väike pill, milleks see minimeerub).
`alwaysShow`	—	`true`, `false`	`false`	Kuva riba igal külastusel uuesti, eirates külastaja kõrvaldamist (jäetakse meelde brauseri `localStorage`-is).
`mountSelector`	—	CSS-selektor	puudub	Renderda riba tekstisiseselt selle elemendi sees fikseeritud alaservas oleva ülekatte asemel.
`triggerSelector`	—	CSS-selektor	puudub	Kuva interaktsiooniriba alles pärast seda, kui külastaja on sellele elemendile klõpsanud, näiteks vestluse käivitajale. Lehed, millel sobivat elementi pole, ei näita ühtki riba, nii et osal lehtedel eksisteeriv vestlusrobot avalikustatakse ainult seal. Ka pärast laadimist sisestatud käivitajad töötavad. Külastaja, kes riba varem kõrvaldas, näeb ikkagi minikiipi.
`adjacentSelector`	—	CSS-selektor	puudub	Paiguta silt sellise elemendi kõrvale, mida ei saa otse märgistada, näiteks suletud vidin või iframe.
`observe`	—	`true`, `false`	`true`	Jälgi DOM-i hiljem lisatud sisu suhtes ja märgista see. Määra `false` täielikult staatilistel lehtedel.
`beaconUrl`	—	URL	puudub	Saada oluliste sündmuste puhul anonüümne `{siteKey, flag}` majakas. Küpsiseid ega isikuandmeid ei kasutata.

data-manual ei ole valiku väärtus: selle olemasolu sildil lükkab automaatkäivituse edasi, nii et saate ise välja kutsuda AIDisclose.init().

Kujundus ja välimus

Määrake sisseehitatud skeem valikuga theme (light, dark või auto). Oma brändiga täpseks sobitamiseks alistage koodijupi CSS-i kohandatud atribuudid oma laadilehes. Need on määratletud elementidel .aid-banner, .aid-chip:

Variable	Controls
`--aid-bg`	Taust
`--aid-fg`	Tekst
`--aid-line`	Ääris
`--aid-btn`	Kõrvaldusnupu ääris
`--aid-btnfg`	Kõrvaldusnupu tekst
`--aid-hov`	Kõrvaldusnupu hõljumine

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

Koodijupp ei sisalda ühtki !important reeglit ja kasutab madala spetsiifilisusega selektoreid, nii et teie CSS võidab. Klassikonksud on .aid-banner, .aid-chip, .aid-badge, .aid-badge-inline, .aid-wrap, .aid-ai (sisuteatis) ja .aid-hm („made by humans”). Muutke vahesid, ümardusraadiust ja varju otse nendel.

Vaikimisi on riba fikseeritud ülekate vaateava alaservas. Määrake mountSelector, et renderdada see tekstisiseselt ja staatiliselt teie hallatava elemendi sees, nii et see paikneb teie enda paigutuses.

Kohandatud sõnastus

Riba ja kiip kannavad karbist väljas täpset lokaliseeritud teksti 28 keeles. Sõnastuse alistamiseks:

Keelte kaupa manifestis. Lisage süsteemile disclosure.texts, mis on võtmestatud keelekoodi järgi. Koodijupp kasutab sobiva külastaja keele jaoks teie teksti:

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

Elemendi kaupa. Lisage märgistatud elemendile data-ai-label, et määrata selle märgi silt.

Kui süsteem määrab editorialResponsibility.humanReview: true ja selle sisu ei ole täielikult TI loodud ega manipuleeritud, on teatise tekst külastaja keeles automaatselt „AI-assisted, human-reviewed” tähenduses, mitte „AI-generated”.

TI-sisu märgistamine

Koodijupp märgistab ainult seda, mille te märgistate. Lisage igale TI loodud elemendile data-ai-content:

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

Iga märgistatud element saab nähtava märgi „AI” ja masinloetava data-digital-source-type (vaikimisi trainedAlgorithmicMedia, mis on IPTC ja schema.org-iga ühilduv väärtus). Kohandatud sildi teksti jaoks lisage data-ai-label või määrake täpsuse huvides ise data-digital-source-type.

Sellise TI jaoks, mida ei saa otse annoteerida, näiteks kolmanda osapoole vestlusvidin suletud iframe'is, kasutage adjacentSelector, et paigutada silt selle kõrvale, või triggerSelector, et avada interaktsiooniriba, kui vidin avaneb.

Sisugenereerimise teatis võib katta kogu saidi (disclosure.scope: "site") või konkreetsed lehed (disclosure.scope: "page" koos disclosure.pages teekonnašabloonide loendiga, näiteks /blog/*). Lehepõhine vaste on ülimuslik saidipõhise ees ning lehepõhine süsteem, millel puudub sobiv teekond, ei renderda seal midagi.

Ühelehelised rakendused ja raamistikud

Koodijupp jälgib DOM-i MutationObserver-i abil ja hindab kohaldatava teatise marsruudi muutumisel uuesti, nii et pärast laadimist lisatud sisu ja lehed märgistatakse endiselt. Ühelehelises rakenduses:

Hoidke observe vaikeväärtusel (true), et kliendipoolel renderdatud sisu tabataks.
Kui piirate lähtestamist rakenduse valmisoleku alusel, lisage data-manual ja kutsuge AIDisclose.init() välja pärast oma raamistiku paigaldumist.
Lehepõhised teatised uuenevad marsruudi muutumisel automaatselt; marsruudipõhist väljakutset pole vaja.

Määrake observe: false ainult täielikult staatilistel lehtedel, kuhu pärast laadimist midagi ei sisestata.

Sisuturbepoliitika

Kui jõustate sisuturbepoliitika (Content Security Policy), lubage koodijupp selgesõnaliselt.

Tähtis

Range script-src 'self' blokeerib CDN-koodijupi vaikselt ning avalikustusi ei renderdata kunagi. See on kõige levinum põhjus, miks korrektselt deklareeritud sait ei jõua tasemele 2.

script-src: lisage https://cdn.aidisclose.io või majutage aidisclose.js oma päritolust ise ja hoidke 'self'.
style-src: koodijupp sisestab oma stiilid tekstisiseselt, seega 'unsafe-inline' on piisav. Kui te tekstisiseseid stiile ei luba, laadib see varuvõimalusena aidisclose.css skripti kataloogist, seega lubage ka https://cdn.aidisclose.io väärtuses style-src (või majutage see fail ise skripti kõrval).
connect-src: well-known faili puhul on manifesti toomine samast päritolust ega vaja midagi lisaks. Kui laadite manifesti võtme kaudu, lubage https://cdn.aidisclose.io.

Manifest tuuakse ilma mandaatideta, seega serveerige seda avalikult: lõpp-punkt, mis nõuab küpsiseid või autentimist, neid ei saa.

Versioonihaldus ja terviklikkus

CDN serveerib kolme rada:

/v1/aidisclose.js järgib uusimat 1.x väljalaset. Soovitatav enamikule saitidele.
/v1.0.0/aidisclose.js on fikseeritud, muutumatu versioon, mille saate kinnistada, koos alamressursi terviklikkusega (Subresource Integrity):

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

/latest/aidisclose.js jälgib alati uusimat väljalaset kõigi peaversioonide ulatuses.

Kinnistatava SRI-räsi saamiseks ehitage koodijupp: npm run build kataloogis packages/snippet prindib selle (lähtekood on avatud GitHubis).

Oma avalikustusliidese ehitamine

Sisseehitatud liidese asemel saate renderdada oma avalikustusliidese. Ühte väljalülitit pole: data-banner="false" ja persistentChip: false peidavad ainult interaktsiooniriba ja selle kiibi, samal ajal kui sisuteatised, elemendipõhised [data-ai-content] märgid ning märk „made by humans” renderdatakse teie manifestist ja märgistusest ikkagi. Täielikult kohandatud liides tähendab, et nendele ei toetuta ja renderdatakse omaenda liides.

Märkus

AIDisclose'i vastavuskontroll tuvastab renderdamise, tehes kindlaks võrdluskoodijupi märgistuse. Täielikult käsitsi ehitatud avalikustus on kehtiv, kuid seda ei tuvastata automaatselt, seega jääb sait tasemele 1 (Declared), mitte tasemele 2 (Rendered), välja arvatud juhul, kui teie kohandatud märgistus taastoodab seda, mida kontroll otsib. Kui tase 2 on teile oluline, hoidke sisseehitatud renderdust ja muutke selle kujundust CSS-i abil.

Ligipääsetavus

Renderdatud liides vastab standardile WCAG 2.1 AA: nähtavad :focus-visible piirjooned interaktiivsetel juhtelementidel, õiged rollid ja sildid, kontrast, mis püsib heleda ja tumeda puhul, ning animatsioon, mis on piiratud atribuudiga prefers-reduced-motion. Koodijupp tuvastab ka tuntud küpsisenõusoleku ribad ja paigutub nende kohale, nii et avalikustused pole kunagi CMP taha peidetud. Väga kitsastel ekraanidel avaneb interaktsiooniriba kompaktse kiibina, nii et see ei kata kunagi sisu.

#Ülevaade

#Paigaldamine

#Seadistamine

#Valikute teatmik

#Kujundus ja välimus

#Kohandatud sõnastus

#TI-sisu märgistamine

#Ühelehelised rakendused ja raamistikud

#Sisuturbepoliitika

#Versioonihaldus ja terviklikkus

#Oma avalikustusliidese ehitamine

#Ligipääsetavus