Fragmento žinynas: konfigūravimas ir pritaikymas

aidisclose.js yra svetainėje veikiantis scenarijus, kuris nuskaito jūsų ai-disclosure.json manifestą ir atvaizduoja teisės aktų reikalaujamus atskleidimus: sąveikos juostą pokalbių robotams, nuolatinį turinio pranešimą, matomus pažymėto turinio ženklus ir kompiuterio skaitomus puslapio metaduomenis. Jis neturi priklausomybių, yra maždaug 8.2 KB gzip suglaudintas ir atitinka WCAG 2.1 AA.

Šis puslapis yra išsamus konfigūravimo ir pritaikymo žinynas. Diegimo žingsnius pagal platformą (WordPress, Shopify, Webflow, žymų tvarkyklės) rasite diegimo vadove. Šį dokumentą taip pat galite skaityti kaip neapdorotą Markdown.

Apžvalga

Viską valdo vienas scenarijaus žymuo. Įsikėlus fragmentas gauna jūsų manifestą ir atvaizduoja tik tai, ką manifestas deklaruoja:

Sąveikos juosta, skirta conversational sistemai: pranešimas, kad lankytojas bendrauja su DI.
Turinio pranešimas, skirtas content-generation sistemai su scope: site arba scope: page: mažas nuolatinis žetonas. Jį spustelėjus atsiveria trumpas paaiškinimas su pranešimo tekstu, jūsų leidėjo pavadinimu ir sistemos paskirtimi iš manifesto bei nuoroda į manifesto failą; pranešimo tekstas nukreipia į paprastos kalbos paaiškinimą aidisclose.io svetainėje. Ženklas „sukurta žmonių“ atveria tą pačią kortelę su leidėjo pavadinimu.
Atskirų elementų ženklai, ant bet kurio elemento, kurį pažymite su data-ai-content: matomas „DI“ ženklas ir kompiuterio skaitomas data-digital-source-type.
Puslapio metaduomenys: <link rel="ai-disclosure"> ir <meta name="ai-disclosure">, nukreipiantys į jūsų manifestą.
Ženklas „sukurta žmonių“, kai manifestas nustato noAiDeclared.

Viskas žemiau yra pasirenkama. Be jokios konfigūracijos fragmentas nuskaito jūsų /.well-known/ai-disclosure.json, atvaizduoja lankytojo kalba 28 kalbomis, laikosi operacinės sistemos šviesios arba tamsios temos nuostatos ir dedasi virš žinomų slapukų sutikimo juostų, kad jos niekada nepersidengtų.

Diegimas

Įtraukite žymą vieną kartą į bendrą svetainės šabloną, temos antraštę arba žymų tvarkyklę, ir ji bus pateikiama su kiekvienu puslapiu. Ji gali būti <head> dalyje arba bet kur prieš </body>; ji yra atidėta, todėl vieta nekeičia elgsenos:

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

Be atributų fragmentas nuskaito manifestą adresu https://YOURDOMAIN/.well-known/ai-disclosure.json. Jei jūsų platforma negali pateikti failo domeno šaknyje, talpinkite manifestą su AIDisclose ir nukreipkite žymą į jį pagal raktą:

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

Jei manifesto pasiekti nepavyksta, fragmentas įrašo įspėjimą į konsolę ir neatvaizduoja jokių iš manifesto kilusių pranešimų, todėl gavimo klaida niekada neparodo atspėto pranešimo. Puslapio metaduomenys, jūsų [data-ai-content] ženklai ir juosta, priverstinai įjungta su data-banner="true", vis tiek atvaizduojami.

Konfigūravimas

Yra trys būdai konfigūruoti fragmentą. Naudokite tą, kuris tinka jūsų platformai.

1. Atributai scenarijaus žymoje. Paprasčiausias būdas, be papildomo kodo:

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

2. Globalusis konfigūracijos objektas. Apibrėžkite window.AIDiscloseConfig prieš paleidžiant scenarijų. Jis atveria visą parinkčių rinkinį, įskaitant selektoriaus parinktis, kurios neturi atributo formos:

<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. Rankinis inicijavimas. Pridėkite data-manual, kad atidėtumėte automatinį paleidimą, tada patys iškvieskite AIDisclose.init(), kai jūsų programa bus paruošta (naudinga vienpuslapėse programose):

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

Jei yra daugiau nei vienas šaltinis, laimi window.AIDiscloseConfig: jis nustelbia ir scenarijaus žymos atributus, ir bet kurį objektą, perduotą į AIDisclose.init().

Parinkčių žinynas

Parinkčių sąsaja yra stabili 1.x linijoje.

Option	Attribute	Reikšmės	Numatytoji	Poveikis
`theme`	`data-theme`	`light`, `dark`, `auto`	`auto`	Spalvų schema. `auto` laikosi lankytojo OS nuostatos.
`siteKey`	`data-aidisclose`	eilutė	nėra	Įkelti AIDisclose talpinamą manifestą pagal šį raktą vietoj well-known failo.
`manifestUrl`	`data-manifest-url`	URL	`/.well-known/ai-disclosure.json`	Nuskaityti manifestą iš pasirinktinio URL.
`lang`	`data-lang`	BCP-47 kodas	puslapio `<html lang>`, priešingu atveju lankytojo kalba	Priverstinai nustatyti rodymo kalbą.
`banner`	`data-banner`	`true`, `false`	auto	Priverstinai įjungti arba išjungti sąveikos juostą. Nenustačius ji rodoma tik tada, kai jūsų manifestas deklaruoja pokalbių (chatbot) sistemą.
`persistentChip`	—	`true`, `false`	`true`	Rodyti arba slėpti sąveikos juostos suskleistą mažąjį žetoną (mažą piliulę, į kurią ji sumažinama).
`alwaysShow`	—	`true`, `false`	`false`	Rodyti juostą per kiekvieną apsilankymą, nepaisant lankytojo atmetimo (įsimenamo naršyklės `localStorage`).
`mountSelector`	—	CSS selektorius	nėra	Atvaizduoti juostą įterptinai šio elemento viduje, o ne kaip fiksuotą apatinį perdangą.
`triggerSelector`	—	CSS selektorius	nėra	Rodyti sąveikos juostą tik po to, kai lankytojas spustelėja šį elementą, pavyzdžiui, pokalbio paleidiklį. Puslapiai be atitinkančio elemento juostos nerodo, todėl pokalbių robotas, esantis tik kai kuriuose puslapiuose, atskleidžiamas tik ten. Paleidikliai, įterpti po įkėlimo, taip pat veikia. Lankytojas, anksčiau atmetęs juostą, vis tiek mato mažąjį žetoną.
`adjacentSelector`	—	CSS selektorius	nėra	Įdėti ženklą šalia elemento, kurio negalite pažymėti tiesiogiai, pavyzdžiui, uždaro valdiklio arba iframe.
`observe`	—	`true`, `false`	`true`	Stebėti DOM, ar nepridedamas turinys vėliau, ir jį pažymėti. Nustatykite `false` visiškai statiniuose puslapiuose.
`beaconUrl`	—	URL	nėra	Siųsti anoniminį `{siteKey, flag}` signalą svarbių įvykių metu. Jokių slapukų, jokių asmens duomenų.

data-manual nėra parinkties reikšmė: jos buvimas žymoje atideda automatinį paleidimą, kad galėtumėte patys iškviesti AIDisclose.init().

Temos ir išvaizda

Nustatykite integruotą schemą su theme (light, dark arba auto). Kad tiksliai atitiktų jūsų prekės ženklą, savo stiliaus lentelėje nustelbkite fragmento CSS pasirinktines savybes. Jos apibrėžtos .aid-banner, .aid-chip:

Kintamasis	Valdo
`--aid-bg`	Fonas
`--aid-fg`	Tekstas
`--aid-line`	Kraštinė
`--aid-btn`	Atmetimo mygtuko kraštinė
`--aid-btnfg`	Atmetimo mygtuko tekstas
`--aid-hov`	Atmetimo mygtuko užvedimas

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

Fragmentas nepateikia jokių !important taisyklių ir naudoja mažo specifiškumo selektorius, todėl jūsų CSS laimi. Klasių kabliukai yra .aid-banner, .aid-chip, .aid-badge, .aid-badge-inline, .aid-wrap, .aid-ai (turinio pranešimas) ir .aid-hm („sukurta žmonių“). Tarpus, apvalinimą ir šešėlį keiskite tiesiogiai šiuose.

Pagal numatytuosius nustatymus juosta yra fiksuota perdanga peržiūros srities apačioje. Nustatykite mountSelector, kad ją atvaizduotumėte įterptinai ir statiškai jūsų valdomo elemento viduje, kad ji būtų jūsų pačių išdėstyme.

Pasirinktinis tekstas

Juosta ir žetonas turi tikslų lokalizuotą tekstą 28 kalbomis iš karto. Kad pakeistumėte tekstą:

Pagal kalbą, manifeste. Pridėkite disclosure.texts prie sistemos, indeksuojant pagal kalbos kodą. Fragmentas naudoja jūsų tekstą atitinkamai lankytojo kalbai:

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

Pagal elementą. Pridėkite data-ai-label prie pažymėto elemento, kad nustatytumėte to ženklo etiketę.

Kai sistema nustato editorialResponsibility.humanReview: true ir jos turinys nėra visiškai sukurtas DI ar manipuliuotas, pranešimas automatiškai rodo „sukurta padedant DI, peržiūrėta žmogaus“ lankytojo kalba, o ne „sukurta DI“.

DI turinio žymėjimas

Fragmentas pažymi tik tai, ką pažymite jūs. Pridėkite data-ai-content prie bet kurio DI sukurto elemento:

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

Kiekvienas pažymėtas elementas gauna matomą „DI“ ženklą ir kompiuterio skaitomą data-digital-source-type (pagal numatytuosius nustatymus trainedAlgorithmicMedia, su IPTC ir schema.org suderinama reikšmė). Pridėkite data-ai-label pasirinktiniam etiketės tekstui arba patys nustatykite data-digital-source-type, kad būtų tiksliau.

DI, kurio negalite anotuoti tiesiogiai, pavyzdžiui, trečiosios šalies pokalbių valdiklio uždarame iframe, naudokite adjacentSelector, kad įdėtumėte ženklą šalia jo, arba triggerSelector, kad atskleistumėte sąveikos juostą, kai valdiklis atsidaro.

Turinio generavimo pranešimas gali apimti visą svetainę (disclosure.scope: "site") arba konkrečius puslapius (disclosure.scope: "page" su disclosure.pages kelių šablonų sąrašu, pavyzdžiui, /blog/*). Puslapio srities atitikmuo turi pirmenybę prieš svetainės srities atitikmenį, o puslapio srities sistema be atitinkančio kelio ten nieko neatvaizduoja.

Vienpuslapės programos ir karkasai

Fragmentas stebi DOM su MutationObserver ir iš naujo įvertina taikomą pranešimą pasikeitus maršrutui, todėl po įkėlimo pridėtas turinys ir puslapiai vis tiek pažymimi. SPA programoje:

Palikite observe numatytosios reikšmės (true), kad būtų aptiktas kliento pusėje atvaizduotas turinys.
Jei inicijavimą susiejate su programos parengtimi, pridėkite data-manual ir iškvieskite AIDisclose.init() po to, kai jūsų karkasas prisijungia.
Puslapio srities pranešimai atnaujinami automatiškai keičiantis maršrutui; atskiro iškvietimo kiekvienam maršrutui nereikia.

Nustatykite observe: false tik visiškai statiniuose puslapiuose, kuriuose po įkėlimo nieko neįterpiama.

Content Security Policy

Jei taikote Content Security Policy, aiškiai leiskite fragmentą.

Svarbu

Griežtas script-src 'self' tyliai blokuoja CDN fragmentą, ir atskleidimai niekada neatvaizduojami. Tai dažniausia priežastis, dėl kurios teisingai deklaruota svetainė nepasiekia 2 lygio.

script-src: pridėkite https://cdn.aidisclose.io arba talpinkite aidisclose.js savo paties šaltinyje ir palikite 'self'.
style-src: fragmentas įterpia savo stilius įterptinai, todėl 'unsafe-inline' pakanka. Jei neleidžiate įterptinių stilių, jis grįžta prie aidisclose.css įkėlimo iš scenarijaus katalogo, todėl style-src taip pat leiskite https://cdn.aidisclose.io (arba talpinkite tą failą kartu su scenarijumi).
connect-src: manifesto gavimas yra to paties šaltinio well-known failui ir nereikalauja nieko papildomo. Jei įkeliate manifestą pagal raktą, leiskite https://cdn.aidisclose.io.

Manifestas gaunamas be prisijungimo duomenų, todėl pateikite jį viešai: galinis taškas, kuriam reikia slapukų ar autentifikavimo, jų negaus.

Versijų valdymas ir vientisumas

CDN teikia tris kryptis:

/v1/aidisclose.js seka naujausią 1.x leidimą. Rekomenduojama daugumai svetainių.
/v1.0.0/aidisclose.js yra fiksuota, nekintanti versija, kurią galite prisegti, su Subresource Integrity:

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

/latest/aidisclose.js visada seka naujausią leidimą įvairiose pagrindinėse versijose.

Kad gautumėte SRI maišą prisegimui, sukompiliuokite fragmentą: npm run build kataloge packages/snippet jį atspausdina (šaltinis yra atviras GitHub).

Nuosavos atskleidimo sąsajos kūrimas

Galite atvaizduoti savo pačių atskleidimo sąsają vietoj integruotos. Nėra vieno išjungimo jungiklio: data-banner="false" ir persistentChip: false slopina tik sąveikos juostą ir jos žetoną, o turinio pranešimai, atskirų elementų [data-ai-content] ženklai ir ženklas „sukurta žmonių“ vis tiek atvaizduojami iš jūsų manifesto ir žymėjimo. Visiškai pasirinktinė sąsaja reiškia nesiremti jais ir atvaizduoti savo pačių.

Pastaba

AIDisclose tikrinimo įrankis patikrina atvaizdavimą aptikdamas etaloninio fragmento žymėjimą. Visiškai ranka sukurtas atskleidimas galioja, bet nėra automatiškai aptinkamas, todėl svetainė lieka 1 lygyje (deklaruota), o ne 2 lygyje (atvaizduota), nebent jūsų pasirinktinis žymėjimas atkuria tai, ko ieško tikrinimo įrankis. Jei jums svarbus 2 lygis, palikite integruotą atvaizdavimą ir perkurkite jo stilių su CSS.

Prieinamumas

Atvaizduota sąsaja atitinka WCAG 2.1 AA: matomi :focus-visible kontūrai ant interaktyvių valdiklių, teisingos rolės ir etiketės, kontrastas, išliekantis šviesioje ir tamsioje temoje, ir animacija, apribota prefers-reduced-motion. Fragmentas taip pat aptinka žinomas slapukų sutikimo juostas ir dedasi virš jų, kad atskleidimai niekada nebūtų paslėpti už CMP. Labai siauruose ekranuose sąveikos juosta atsidaro kaip kompaktiškas žetonas, kad niekada neuždengtų turinio.

#Apžvalga

#Diegimas

#Konfigūravimas

#Parinkčių žinynas

#Temos ir išvaizda

#Pasirinktinis tekstas

#DI turinio žymėjimas

#Vienpuslapės programos ir karkasai

#Content Security Policy

#Versijų valdymas ir vientisumas

#Nuosavos atskleidimo sąsajos kūrimas

#Prieinamumas