Справочник за фрагмента: конфигуриране и персонализиране

aidisclose.js е скриптът на сайта, който чете вашия манифест ai-disclosure.json и визуализира разкриванията, изисквани от закона: банер за взаимодействие при чатботове, постоянна бележка за съдържанието, видими обозначения върху маркираните медии и машинночетими метаданни на страницата. Той е без зависимости, около 8.2 KB компресиран с gzip, и отговаря на WCAG 2.1 AA.

Тази страница е пълният справочник за конфигуриране и персонализиране. За стъпките по инсталиране за всяка платформа (WordPress, Shopify, Webflow, мениджъри на маркери) вижте ръководството за инсталиране. Можете да прочетете този документ и като суров markdown.

Общ преглед

Един скриптов маркер задвижва всичко. При зареждане фрагментът извлича вашия манифест и след това визуализира само това, което манифестът декларира:

Банер за взаимодействие за система тип conversational: бележка, че посетителят разговаря с ИИ.
Бележка за съдържанието за система тип content-generation със scope: site или scope: page: малък постоянен чип. При щракване върху него се отваря кратко обяснение с текста на бележката, името на вашия издател и предназначението на системата от манифеста, както и връзка към файла на манифеста; текстът на бележката води към общодостъпно обяснение на aidisclose.io. Значката „направено от хора“ отваря същата карта с името на издателя.
Обозначения за отделни елементи върху всеки елемент, който маркирате с data-ai-content: видима значка „AI“ и машинночетим data-digital-source-type.
Метаданни на страницата: <link rel="ai-disclosure"> и <meta name="ai-disclosure">, сочещи към вашия манифест.
Значка „направено от хора“, когато манифестът задава noAiDeclared.

Всичко по-долу е незадължително. Без конфигуриране фрагментът чете вашия /.well-known/ai-disclosure.json, визуализира на езика на посетителя на 28 локала, следва предпочитанието за светла или тъмна тема на операционната система и се подрежда над познатите ленти за съгласие за бисквитки, така че двете никога да не се припокриват.

Инсталиране

Добавете маркера веднъж в общия шаблон на сайта, в заглавната част на темата или в мениджъра на маркери, и той се включва на всяка страница. Може да стои в <head> или навсякъде преди </body>; той е с defer, така че разположението не променя поведението:

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

Без атрибути фрагментът чете манифеста на адрес https://YOURDOMAIN/.well-known/ai-disclosure.json. Ако вашата платформа не може да обслужва файл в корена на домейна, хоствайте манифеста при AIDisclose и насочете маркера към него чрез ключ:

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

Ако манифестът е недостъпен, фрагментът записва предупреждение в конзолата и не визуализира бележки, задвижвани от манифеста, така че неуспешно извличане никога не показва предполагаема бележка. Метаданните на страницата, вашите обозначения [data-ai-content] и банер, наложен с data-banner="true", все пак се визуализират.

Конфигуриране

Има три начина да конфигурирате фрагмента. Използвайте този, който подхожда на вашата платформа.

1. Атрибути върху скриптовия маркер. Най-простият път, без допълнителен код:

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

2. Глобален конфигурационен обект. Дефинирайте window.AIDiscloseConfig преди изпълнението на скрипта. Той предоставя пълния набор от опции, включително опциите за селектори, които нямат атрибутна форма:

<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. Ръчна инициализация. Добавете data-manual, за да отложите автоматичното стартиране, след което извикайте AIDisclose.init() сами, щом приложението ви е готово (полезно при едностранични приложения):

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

Ако присъства повече от един източник, надделява window.AIDiscloseConfig: той има предимство както пред атрибутите на скриптовия маркер, така и пред всеки обект, подаден на AIDisclose.init().

Справочник за опциите

Наборът от опции е стабилен за линията 1.x.

Option	Attribute	Values	Default	Effect
`theme`	`data-theme`	`light`, `dark`, `auto`	`auto`	Цветова схема. `auto` следва предпочитанието на операционната система на посетителя.
`siteKey`	`data-aidisclose`	символен низ	няма	Зарежда манифеста, хостван от AIDisclose за този ключ, вместо well-known файла.
`manifestUrl`	`data-manifest-url`	URL	`/.well-known/ai-disclosure.json`	Чете манифеста от персонализиран URL.
`lang`	`data-lang`	код по BCP-47	`<html lang>` на страницата, иначе езикът на посетителя	Налага език на показване.
`banner`	`data-banner`	`true`, `false`	auto	Налага включване или изключване на банера за взаимодействие. Ако не е зададено, той се показва само когато манифестът декларира conversational (чатбот) система.
`persistentChip`	—	`true`, `false`	`true`	Показва или скрива свития мини-чип на банера за взаимодействие (малката хапче форма, до която той се минимизира).
`alwaysShow`	—	`true`, `false`	`false`	Показва банера отново при всяко посещение, като пренебрегва отхвърлянето от посетителя (запомнено в `localStorage` на браузъра).
`mountSelector`	—	CSS селектор	няма	Визуализира банера вградено вътре в този елемент вместо като фиксиран долен наслагващ слой.
`triggerSelector`	—	CSS селектор	няма	Показва банера за взаимодействие едва след като посетителят щракне върху този елемент, например бутон за стартиране на чат. Страниците без съответстващ елемент не показват банер, така че чатбот, който съществува на някои страници, разкрива само там. Стартиращите бутони, вмъкнати след зареждане, също работят. Посетител, който е отхвърлил банера по-рано, все пак вижда мини-чипа.
`adjacentSelector`	—	CSS селектор	няма	Поставя обозначение до елемент, който не можете да маркирате директно, например затворена джаджа или iframe.
`observe`	—	`true`, `false`	`true`	Наблюдава DOM за съдържание, добавено по-късно, и го обозначава. Задайте `false` на изцяло статични страници.
`beaconUrl`	—	URL	няма	Изпраща анонимен маяк `{siteKey, flag}` при значими събития. Без бисквитки, без лични данни.

data-manual не е стойност на опция: присъствието му върху маркера отлага автоматичното стартиране, за да можете сами да извикате AIDisclose.init().

Тема и външен вид

Задайте вградената схема чрез theme (light, dark или auto). За да съответства точно на вашата марка, заменете персонализираните CSS свойства на фрагмента във вашата собствена таблица със стилове. Те са дефинирани върху .aid-banner, .aid-chip:

Variable	Controls
`--aid-bg`	Фон
`--aid-fg`	Текст
`--aid-line`	Рамка
`--aid-btn`	Рамка на бутона за отхвърляне
`--aid-btnfg`	Текст на бутона за отхвърляне
`--aid-hov`	Наведен курсор върху бутона за отхвърляне

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

Фрагментът не включва правила !important и използва селектори с ниска специфичност, така че вашият CSS надделява. Класовите куки са .aid-banner, .aid-chip, .aid-badge, .aid-badge-inline, .aid-wrap, .aid-ai (бележка за съдържанието) и .aid-hm („направено от хора“). Променете отстоянията, радиуса и сянката директно върху тях.

По подразбиране банерът е фиксиран наслагващ слой в долната част на изгледа. Задайте mountSelector, за да го визуализирате вградено и статично вътре в елемент, който контролирате, така че да стои в собствената ви подредба.

Персонализиран текст

Банерът и чипът носят точен локализиран текст на 28 езика по подразбиране. За да замените текста:

По език, в манифеста. Добавете disclosure.texts към система, ключирано по езиков код. Фрагментът използва вашия текст за съответстващия език на посетителя:

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

По елемент. Добавете data-ai-label към маркиран елемент, за да зададете обозначението на тази значка.

Когато система задава editorialResponsibility.humanReview: true и нейното съдържание не е изцяло генерирано или манипулирано от ИИ, бележката автоматично гласи „подпомогнато от ИИ, прегледано от човек“ на езика на посетителя, вместо „генерирано от ИИ“.

Маркиране на вашето ИИ съдържание

Фрагментът обозначава само това, което маркирате. Добавете 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>

Всеки маркиран елемент получава видима значка „AI“ и машинночетим data-digital-source-type (по подразбиране trainedAlgorithmicMedia, стойност, съвместима с IPTC и schema.org). Добавете data-ai-label за персонализиран текст на обозначението или задайте data-digital-source-type сами, за да бъдете по-конкретни.

За ИИ, който не можете да анотирате директно, например джаджа за чат от трета страна в затворен iframe, използвайте adjacentSelector, за да поставите обозначение до нея, или triggerSelector, за да покажете банера за взаимодействие, когато джаджата се отвори.

Бележка за генериране на съдържание може да обхваща целия сайт (disclosure.scope: "site") или конкретни страници (disclosure.scope: "page" със списък disclosure.pages от глобове на пътища, например /blog/*). Съвпадение на ниво страница има предимство пред съвпадение на ниво сайт, а система на ниво страница без съответстващ път не визуализира нищо там.

Едностранични приложения и рамки

Фрагментът наблюдава DOM чрез MutationObserver и преоценява приложимата бележка при промяна на маршрута, така че съдържание и страници, добавени след зареждане, също се обозначават. В едностранично приложение:

Оставете observe със стойността по подразбиране (true), за да се улавя съдържанието, визуализирано от клиента.
Ако обвързвате инициализацията с готовността на приложението, добавете data-manual и извикайте AIDisclose.init(), след като вашата рамка се монтира.
Бележките на ниво страница се обновяват автоматично при промяна на маршрута; не е нужно извикване за всеки маршрут.

Задайте observe: false само на изцяло статични страници, където нищо не се вмъква след зареждане.

Политика за сигурност на съдържанието

Ако прилагате политика за сигурност на съдържанието, разрешете фрагмента изрично.

Важно

Строгата script-src 'self' блокира фрагмента от CDN безшумно и разкриванията никога не се визуализират. Това е най-честата причина коректно деклариран сайт да не достигне Ниво 2.

script-src: добавете https://cdn.aidisclose.io или самостоятелно хоствайте aidisclose.js от собствения си произход и запазете 'self'.
style-src: фрагментът вмъква стиловете си вградено, така че 'unsafe-inline' е достатъчно. Ако не разрешавате вградени стилове, той преминава към зареждане на aidisclose.css от директорията на скрипта, затова разрешете и https://cdn.aidisclose.io в style-src (или хоствайте самостоятелно този файл до скрипта).
connect-src: извличането на манифеста е от същия произход за well-known файла и не се нуждае от нищо допълнително. Ако зареждате манифеста чрез ключ, разрешете https://cdn.aidisclose.io.

Манифестът се извлича без идентификационни данни, затова го обслужвайте публично: крайна точка, която изисква бисквитки или удостоверяване, няма да ги получи.

Версиониране и цялост

CDN обслужва три канала:

/v1/aidisclose.js следва последното издание от 1.x. Препоръчва се за повечето сайтове.
/v1.0.0/aidisclose.js е фиксирана, непроменима версия, която можете да закачите, с Subresource Integrity:

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

/latest/aidisclose.js винаги следва най-новото издание през основните версии.

За да получите SRI хеша за закачване, компилирайте фрагмента: npm run build в packages/snippet го отпечатва (изходният код е отворен в GitHub).

Изграждане на собствен интерфейс за разкриване

Можете да визуализирате собствен интерфейс за разкриване вместо вградения. Няма единствен изключвател: data-banner="false" и persistentChip: false потискат само банера за взаимодействие и неговия чип, докато бележките за съдържанието, значките за отделни елементи [data-ai-content] и значката „направено от хора“ все пак се визуализират от вашия манифест и разметка. Изцяло персонализиран интерфейс означава да не разчитате на тях и да визуализирате свой собствен.

Бележка

Проверката на AIDisclose потвърждава визуализацията, като разпознава разметката на референтния фрагмент. Изцяло ръчно изградено разкриване е валидно, но не се разпознава автоматично, така че сайтът остава на Ниво 1 (Декларирано), а не на Ниво 2 (Визуализирано), освен ако вашата персонализирана разметка не възпроизвежда това, което проверката търси. Ако Ниво 2 е важно за вас, запазете вградената визуализация и я стилизирайте наново чрез CSS.

Достъпност

Визуализираният интерфейс отговаря на WCAG 2.1 AA: видими контури :focus-visible върху интерактивните контроли, коректни роли и обозначения, контраст, който се запазва в светла и тъмна тема, и анимация, ограничена от prefers-reduced-motion. Фрагментът също разпознава познатите ленти за съгласие за бисквитки и се подрежда над тях, така че разкриванията никога да не са скрити зад CMP. На много тесни екрани банерът за взаимодействие се отваря като компактния чип, за да не покрива съдържанието.

#Общ преглед

#Инсталиране

#Конфигуриране

#Справочник за опциите

#Тема и външен вид

#Персонализиран текст

#Маркиране на вашето ИИ съдържание

#Едностранични приложения и рамки

#Политика за сигурност на съдържанието

#Версиониране и цялост

#Изграждане на собствен интерфейс за разкриване

#Достъпност