Dokumentacja snippetu: konfiguracja i dostosowywanie

aidisclose.js to skrypt działający na stronie, który odczytuje manifest ai-disclosure.json i wyświetla ujawnienia wymagane przez prawo: baner interakcji dla chatbotów, trwałą informację o treści, widoczne etykiety na oznaczonych multimediach oraz metadane strony nadające się do odczytu maszynowego. Nie ma zależności, waży około 8.2 KB po kompresji gzip i spełnia WCAG 2.1 AA.

Ta strona zawiera pełną dokumentację konfiguracji i dostosowywania. Kroki instalacji dla poszczególnych platform (WordPress, Shopify, Webflow, menedżery tagów) opisano w przewodniku instalacji. Ten dokument można też przeczytać jako surowy markdown.

Przegląd

Wszystkim steruje jeden tag skryptu. Po załadowaniu snippet pobiera manifest, a następnie wyświetla tylko to, co manifest deklaruje:

Baner interakcji, dla systemu conversational: informacja, że odwiedzający rozmawia z SI.
Informacja o treści, dla systemu content-generation z scope: site lub scope: page: mały, trwały znacznik. Kliknięcie otwiera krótkie wyjaśnienie z treścią informacji, nazwą wydawcy i celem systemu z manifestu oraz linkiem do pliku manifestu; treść informacji prowadzi do przystępnego wyjaśnienia na aidisclose.io. Plakietka „stworzone przez ludzi" otwiera tę samą kartę z nazwą wydawcy.
Etykiety na poszczególnych elementach, na każdym elemencie oznaczonym atrybutem data-ai-content: widoczna plakietka „SI" oraz nadający się do odczytu maszynowego data-digital-source-type.
Metadane strony: <link rel="ai-disclosure"> i <meta name="ai-disclosure"> wskazujące na manifest.
Plakietka „stworzone przez ludzi", gdy manifest ustawia noAiDeclared.

Wszystko poniżej jest opcjonalne. Bez żadnej konfiguracji snippet odczytuje /.well-known/ai-disclosure.json, wyświetla się w języku odwiedzającego w 28 wersjach językowych, dostosowuje się do jasnego lub ciemnego trybu systemu operacyjnego i wyświetla się nad znanymi paskami zgody na pliki cookie, aby nigdy się nie nakładały.

Instalacja

Dodaj tag raz, we wspólnym szablonie witryny, nagłówku motywu lub menedżerze tagów, a pojawi się na każdej stronie. Może znajdować się w <head> lub w dowolnym miejscu przed </body>; jest ładowany z atrybutem defer, więc jego umiejscowienie nie zmienia zachowania:

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

Bez żadnych atrybutów snippet odczytuje manifest pod adresem https://YOURDOMAIN/.well-known/ai-disclosure.json. Jeśli Twoja platforma nie może udostępnić pliku w katalogu głównym domeny, hostuj manifest w AIDisclose i wskaż go w tagu za pomocą klucza:

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

Jeśli manifest jest nieosiągalny, snippet zapisuje ostrzeżenie w konsoli i nie wyświetla żadnych informacji zależnych od manifestu, więc nieudane pobranie nigdy nie pokazuje zgadywanej informacji. Metadane strony, etykiety [data-ai-content] oraz baner wymuszony przez data-banner="true" nadal się wyświetlają.

Konfiguracja

Snippet można skonfigurować na trzy sposoby. Użyj tego, który pasuje do Twojej platformy.

1. Atrybuty w tagu skryptu. Najprostsza droga, bez dodatkowego kodu:

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

2. Globalny obiekt konfiguracji. Zdefiniuj window.AIDiscloseConfig przed uruchomieniem skryptu. Udostępnia on pełny zestaw opcji, w tym opcje selektorów, które nie mają postaci atrybutu:

<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. Ręczna inicjalizacja. Dodaj data-manual, aby odroczyć automatyczne uruchomienie, a następnie samodzielnie wywołaj AIDisclose.init(), gdy aplikacja będzie gotowa (przydatne w aplikacjach jednostronicowych):

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

Jeśli obecnych jest więcej źródeł, wygrywa window.AIDiscloseConfig: nadpisuje zarówno atrybuty tagu skryptu, jak i dowolny obiekt przekazany do AIDisclose.init().

Dokumentacja opcji

Zestaw opcji jest stabilny w linii 1.x.

Opcja	Atrybut	Wartości	Domyślnie	Działanie
`theme`	`data-theme`	`light`, `dark`, `auto`	`auto`	Schemat kolorów. `auto` dostosowuje się do preferencji systemu odwiedzającego.
`siteKey`	`data-aidisclose`	ciąg znaków	brak	Ładuje manifest hostowany w AIDisclose dla tego klucza zamiast pliku well-known.
`manifestUrl`	`data-manifest-url`	URL	`/.well-known/ai-disclosure.json`	Odczytuje manifest z niestandardowego adresu URL.
`lang`	`data-lang`	kod BCP-47	`<html lang>` strony, w przeciwnym razie język odwiedzającego	Wymusza język wyświetlania.
`banner`	`data-banner`	`true`, `false`	auto	Wymusza włączenie lub wyłączenie banera interakcji. Pozostawiony bez ustawienia pojawia się tylko wtedy, gdy manifest deklaruje system konwersacyjny (chatbot).
`persistentChip`	—	`true`, `false`	`true`	Pokazuje lub ukrywa zwinięty miniznacznik banera interakcji (małą pigułkę, do której się minimalizuje).
`alwaysShow`	—	`true`, `false`	`false`	Pokazuje baner ponownie przy każdej wizycie, ignorując wcześniejsze zamknięcie przez odwiedzającego (zapamiętane w `localStorage` przeglądarki).
`mountSelector`	—	selektor CSS	brak	Wyświetla baner wewnątrz tego elementu zamiast jako stałą nakładkę u dołu.
`triggerSelector`	—	selektor CSS	brak	Pokazuje baner interakcji dopiero po kliknięciu tego elementu przez odwiedzającego, na przykład przycisku uruchamiającego czat. Strony bez pasującego elementu nie pokazują banera, więc chatbot obecny tylko na niektórych stronach ujawnia się jedynie tam. Przyciski wstrzyknięte po załadowaniu również działają. Odwiedzający, który wcześniej zamknął baner, nadal widzi miniznacznik.
`adjacentSelector`	—	selektor CSS	brak	Umieszcza etykietę obok elementu, którego nie można oznaczyć bezpośrednio, na przykład zamkniętego widżetu lub elementu iframe.
`observe`	—	`true`, `false`	`true`	Obserwuje DOM pod kątem treści dodanych później i oznacza je. Ustaw `false` na całkowicie statycznych stronach.
`beaconUrl`	—	URL	brak	Wysyła anonimowy sygnał `{siteKey, flag}` przy istotnych zdarzeniach. Bez plików cookie, bez danych osobowych.

data-manual nie jest wartością opcji: jego obecność w tagu odracza automatyczne uruchomienie, dzięki czemu możesz samodzielnie wywołać AIDisclose.init().

Motyw i wygląd

Ustaw wbudowany schemat za pomocą theme (light, dark lub auto). Aby dokładnie dopasować go do marki, nadpisz niestandardowe właściwości CSS snippetu we własnym arkuszu stylów. Są zdefiniowane na .aid-banner, .aid-chip:

Zmienna	Steruje
`--aid-bg`	Tło
`--aid-fg`	Tekst
`--aid-line`	Obramowanie
`--aid-btn`	Obramowanie przycisku zamknięcia
`--aid-btnfg`	Tekst przycisku zamknięcia
`--aid-hov`	Najechanie na przycisk zamknięcia

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

Snippet nie zawiera reguł !important i używa selektorów o niskiej specyficzności, więc Twój CSS wygrywa. Punkty zaczepienia klas to .aid-banner, .aid-chip, .aid-badge, .aid-badge-inline, .aid-wrap, .aid-ai (informacja o treści) i .aid-hm („stworzone przez ludzi"). Odstępy, zaokrąglenia i cień zmienisz bezpośrednio na tych klasach.

Domyślnie baner jest stałą nakładką u dołu okna widoku. Ustaw mountSelector, aby wyświetlić go w układzie ciągłym i statycznie wewnątrz kontrolowanego przez Ciebie elementu, tak aby mieścił się we własnym układzie.

Własne teksty

Baner i znacznik zawierają dokładny, zlokalizowany tekst w 28 językach od razu po instalacji. Aby zmienić treść:

Dla każdego języka, w manifeście. Dodaj disclosure.texts do systemu, z kluczami według kodu języka. Snippet użyje Twojego tekstu dla pasującego języka odwiedzającego:

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

Dla poszczególnych elementów. Dodaj data-ai-label do oznaczonego elementu, aby ustawić etykietę tej plakietki.

Gdy system ustawia editorialResponsibility.humanReview: true, a jego treść nie jest w pełni wygenerowana przez SI ani zmanipulowana, informacja automatycznie brzmi „wspomagane przez SI, zweryfikowane przez człowieka" w języku odwiedzającego, zamiast „wygenerowane przez SI".

Oznaczanie treści SI

Snippet oznacza tylko to, co sam oznaczysz. Dodaj data-ai-content do dowolnego elementu wygenerowanego przez SI:

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

Każdy oznaczony element otrzymuje widoczną plakietkę „SI" oraz nadający się do odczytu maszynowego data-digital-source-type (domyślnie trainedAlgorithmicMedia, wartość zgodna z IPTC i schema.org). Dodaj data-ai-label dla własnego tekstu etykiety lub samodzielnie ustaw data-digital-source-type, aby był bardziej szczegółowy.

W przypadku SI, której nie można oznaczyć bezpośrednio, na przykład zewnętrznego widżetu czatu w zamkniętym elemencie iframe, użyj adjacentSelector, aby umieścić etykietę obok, lub triggerSelector, aby wyświetlić baner interakcji po otwarciu widżetu.

Informacja o generowaniu treści może obejmować całą witrynę (disclosure.scope: "site") lub konkretne strony (disclosure.scope: "page" z listą disclosure.pages zawierającą wzorce ścieżek, takie jak /blog/*). Dopasowanie na poziomie strony ma pierwszeństwo przed dopasowaniem na poziomie witryny, a system o zasięgu strony bez pasującej ścieżki nie wyświetla tam niczego.

Aplikacje jednostronicowe i frameworki

Snippet obserwuje DOM za pomocą MutationObserver i ponownie ocenia właściwą informację przy zmianie trasy, więc treści i strony dodane po załadowaniu są nadal oznaczane. W aplikacji SPA:

Pozostaw observe na wartości domyślnej (true), aby wychwycić treści renderowane po stronie klienta.
Jeśli uzależniasz inicjalizację od gotowości aplikacji, dodaj data-manual i wywołaj AIDisclose.init() po zamontowaniu frameworka.
Informacje o zasięgu strony aktualizują się automatycznie przy zmianie trasy; nie jest potrzebne wywołanie dla każdej trasy.

Ustaw observe: false tylko na całkowicie statycznych stronach, na których nic nie jest wstrzykiwane po załadowaniu.

Content Security Policy

Jeśli wymuszasz Content Security Policy, jawnie zezwól na snippet.

Ważne

Rygorystyczne script-src 'self' po cichu blokuje snippet z CDN i ujawnienia nigdy się nie wyświetlają. To najczęstszy powód, dla którego poprawnie zadeklarowana witryna nie osiąga poziomu 2.

script-src: dodaj https://cdn.aidisclose.io lub hostuj aidisclose.js we własnym źródle i zachowaj 'self'.
style-src: snippet wstrzykuje swoje style bezpośrednio, więc 'unsafe-inline' wystarczy. Jeśli nie zezwalasz na style wbudowane, snippet awaryjnie ładuje aidisclose.css z katalogu skryptu, więc zezwól również na https://cdn.aidisclose.io w style-src (lub hostuj ten plik razem ze skryptem).
connect-src: pobranie manifestu jest w tym samym źródle dla pliku well-known i nie wymaga niczego dodatkowego. Jeśli ładujesz manifest za pomocą klucza, zezwól na https://cdn.aidisclose.io.

Manifest jest pobierany bez poświadczeń, więc udostępniaj go publicznie: punkt końcowy wymagający plików cookie lub uwierzytelnienia ich nie otrzyma.

Wersjonowanie i integralność

CDN udostępnia trzy ścieżki:

/v1/aidisclose.js śledzi najnowsze wydanie z linii 1.x. Zalecane dla większości witryn.
/v1.0.0/aidisclose.js to stała, niezmienna wersja, którą można przypiąć, z Subresource Integrity:

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

/latest/aidisclose.js zawsze śledzi najnowsze wydanie we wszystkich głównych wersjach.

Aby uzyskać skrót SRI do przypięcia, zbuduj snippet: npm run build w packages/snippet go wyświetla (kod źródłowy jest otwarty na GitHub).

Budowa własnego interfejsu ujawnień

Zamiast wbudowanego interfejsu możesz wyświetlić własny interfejs ujawnień. Nie ma jednego przełącznika wyłączającego: data-banner="false" i persistentChip: false ukrywają tylko baner interakcji i jego znacznik, natomiast informacje o treści, plakietki [data-ai-content] na poszczególnych elementach oraz plakietka „stworzone przez ludzi" nadal wyświetlają się na podstawie manifestu i znaczników. W pełni własny interfejs oznacza rezygnację z nich i wyświetlanie własnego.

Uwaga

Weryfikator AIDisclose sprawdza renderowanie, wykrywając znaczniki referencyjnego snippetu. W pełni ręcznie zbudowane ujawnienie jest prawidłowe, ale nie jest wykrywane automatycznie, więc witryna pozostaje na poziomie 1 (Zadeklarowany), a nie na poziomie 2 (Wyświetlony), chyba że własne znaczniki odtworzą to, czego szuka weryfikator. Jeśli zależy Ci na poziomie 2, zachowaj wbudowane renderowanie i zmień jego wygląd za pomocą CSS.

Dostępność

Wyświetlany interfejs spełnia WCAG 2.1 AA: widoczne obrysy :focus-visible na interaktywnych elementach sterujących, poprawne role i etykiety, kontrast zachowany w trybie jasnym i ciemnym oraz animacje ograniczone przez prefers-reduced-motion. Snippet wykrywa również znane paski zgody na pliki cookie i wyświetla się nad nimi, aby ujawnienia nigdy nie były ukryte za platformą CMP. Na bardzo wąskich ekranach baner interakcji otwiera się jako kompaktowy znacznik, dzięki czemu nigdy nie zasłania treści.

#Przegląd

#Instalacja

#Konfiguracja

#Dokumentacja opcji

#Motyw i wygląd

#Własne teksty

#Oznaczanie treści SI

#Aplikacje jednostronicowe i frameworki

#Content Security Policy

#Wersjonowanie i integralność

#Budowa własnego interfejsu ujawnień

#Dostępność