Snippet-Referenz: konfigurieren & anpassen

aidisclose.js ist das Skript auf Ihrer Website, das Ihr ai-disclosure.json-Manifest liest und die gesetzlich vorgeschriebenen Offenlegungen darstellt: ein Interaktionsbanner für Chatbots, einen dauerhaften Inhaltshinweis, sichtbare Kennzeichnungen auf markierten Medien und maschinenlesbare Seiten-Metadaten. Es ist abhängigkeitsfrei, rund 8.2 KB gzip-komprimiert und erfüllt WCAG 2.1 AA.

Diese Seite ist die vollständige Referenz zur Konfiguration und Anpassung. Die plattformspezifischen Installationsschritte (WordPress, Shopify, Webflow, Tag-Manager) finden Sie in der Installationsanleitung. Sie können dieses Dokument auch als reines Markdown lesen.

Überblick

Ein einziges Script-Tag steuert alles. Beim Laden ruft das Snippet Ihr Manifest ab und stellt dann nur das dar, was das Manifest deklariert:

Interaktionsbanner für ein conversational-System: ein Hinweis, dass die besuchende Person mit einer KI spricht.
Inhaltshinweis für ein content-generation-System mit scope: site oder scope: page: ein kleiner dauerhafter Chip. Ein Klick darauf öffnet eine kurze Erläuterung mit dem Hinweistext, Ihrem Herausgebernamen und dem Systemzweck aus dem Manifest sowie einem Link zur Manifest-Datei; der Hinweistext verlinkt auf eine allgemein verständliche Erklärung auf aidisclose.io. Das Abzeichen „made by humans“ öffnet dieselbe Karte mit dem Herausgebernamen.
Kennzeichnungen pro Element auf jedem Element, das Sie mit data-ai-content markieren: ein sichtbares „KI“-Abzeichen sowie ein maschinenlesbares data-digital-source-type.
Seiten-Metadaten: ein <link rel="ai-disclosure"> und ein <meta name="ai-disclosure">, die auf Ihr Manifest verweisen.
Abzeichen „made by humans“, wenn das Manifest noAiDeclared setzt.

Alles Folgende ist optional. Ohne Konfiguration liest das Snippet Ihr /.well-known/ai-disclosure.json, stellt in der Sprache der besuchenden Person über 28 Sprachen hinweg dar, folgt der Hell- oder Dunkel-Einstellung des Betriebssystems und positioniert sich oberhalb bekannter Cookie-Consent-Leisten, sodass sich die beiden nie überlagern.

Installation

Fügen Sie das Tag einmal in die gemeinsame Vorlage Ihrer Website, den Theme-Header oder den Tag-Manager ein, und es wird mit jeder Seite ausgeliefert. Es kann im <head> oder an beliebiger Stelle vor </body> stehen; es wird verzögert (deferred) geladen, daher ändert die Platzierung das Verhalten nicht:

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

Ohne Attribute liest das Snippet das Manifest unter https://YOURDOMAIN/.well-known/ai-disclosure.json. Wenn Ihre Plattform keine Datei im Wurzelverzeichnis der Domain bereitstellen kann, hosten Sie das Manifest bei AIDisclose und verweisen Sie das Tag über einen Schlüssel darauf:

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

Ist das Manifest nicht erreichbar, gibt das Snippet eine Konsolenwarnung aus und stellt keine manifestgesteuerten Hinweise dar, sodass ein fehlgeschlagener Abruf niemals einen geratenen Hinweis anzeigt. Seiten-Metadaten, Ihre [data-ai-content]-Kennzeichnungen und ein mit data-banner="true" erzwungenes Banner werden weiterhin dargestellt.

Konfiguration

Es gibt drei Wege, das Snippet zu konfigurieren. Verwenden Sie den, der zu Ihrer Plattform passt.

1. Attribute am Script-Tag. Der einfachste Weg, ohne zusätzlichen Code:

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

2. Ein globales Konfigurationsobjekt. Definieren Sie window.AIDiscloseConfig, bevor das Skript ausgeführt wird. Es stellt den vollständigen Optionsumfang bereit, einschließlich der Selektor-Optionen, die keine Attributform haben:

<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. Manuelle Initialisierung. Fügen Sie data-manual hinzu, um den automatischen Start zu verzögern, und rufen Sie dann AIDisclose.init() selbst auf, sobald Ihre Anwendung bereit ist (nützlich in Single-Page-Apps):

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

Sind mehrere Quellen vorhanden, hat window.AIDiscloseConfig Vorrang: es überschreibt sowohl die Attribute am Script-Tag als auch jedes an AIDisclose.init() übergebene Objekt.

Optionsreferenz

Der Optionsumfang ist für die 1.x-Reihe stabil.

Option	Attribut	Werte	Standard	Wirkung
`theme`	`data-theme`	`light`, `dark`, `auto`	`auto`	Farbschema. `auto` folgt der Betriebssystem-Einstellung der besuchenden Person.
`siteKey`	`data-aidisclose`	Zeichenkette	keiner	Lädt das bei AIDisclose gehostete Manifest für diesen Schlüssel anstelle der Well-known-Datei.
`manifestUrl`	`data-manifest-url`	URL	`/.well-known/ai-disclosure.json`	Liest das Manifest von einer benutzerdefinierten URL.
`lang`	`data-lang`	BCP-47-Code	Seiten-`<html lang>`, sonst die Sprache der besuchenden Person	Erzwingt eine Anzeigesprache.
`banner`	`data-banner`	`true`, `false`	auto	Erzwingt das Interaktionsbanner an oder aus. Bleibt es ungesetzt, erscheint es nur, wenn Ihr Manifest ein konversationelles (Chatbot-)System deklariert.
`persistentChip`	—	`true`, `false`	`true`	Zeigt oder unterdrückt den eingeklappten Mini-Chip des Interaktionsbanners (die kleine Pille, zu der es sich minimiert).
`alwaysShow`	—	`true`, `false`	`false`	Zeigt das Banner bei jedem Besuch erneut und ignoriert das frühere Schließen durch die besuchende Person (im `localStorage` des Browsers gespeichert).
`mountSelector`	—	CSS-Selektor	keiner	Stellt das Banner inline innerhalb dieses Elements dar, statt als festes Overlay am unteren Rand.
`triggerSelector`	—	CSS-Selektor	keiner	Zeigt das Interaktionsbanner erst, nachdem die besuchende Person auf dieses Element geklickt hat, etwa einen Chat-Starter. Seiten ohne passendes Element zeigen kein Banner, sodass ein Chatbot, der nur auf manchen Seiten existiert, auch nur dort offengelegt wird. Auch nach dem Laden eingefügte Starter funktionieren. Eine Person, die das Banner zuvor geschlossen hat, sieht weiterhin den Mini-Chip.
`adjacentSelector`	—	CSS-Selektor	keiner	Platziert eine Kennzeichnung neben einem Element, das Sie nicht direkt markieren können, etwa ein geschlossenes Widget oder ein iframe.
`observe`	—	`true`, `false`	`true`	Beobachtet das DOM auf später hinzugefügte Inhalte und kennzeichnet sie. Setzen Sie `false` auf vollständig statischen Seiten.
`beaconUrl`	—	URL	keiner	Sendet bei nennenswerten Ereignissen ein anonymes `{siteKey, flag}`-Beacon. Keine Cookies, keine personenbezogenen Daten.

data-manual ist kein Optionswert: seine Anwesenheit am Tag verzögert den automatischen Start, damit Sie AIDisclose.init() selbst aufrufen können.

Theme und Erscheinungsbild

Legen Sie das eingebaute Schema mit theme fest (light, dark oder auto). Um exakt zu Ihrer Marke zu passen, überschreiben Sie die benutzerdefinierten CSS-Eigenschaften des Snippets in Ihrem eigenen Stylesheet. Sie sind auf .aid-banner, .aid-chip definiert:

Variable	Steuert
`--aid-bg`	Hintergrund
`--aid-fg`	Text
`--aid-line`	Rahmen
`--aid-btn`	Rahmen der Schließen-Schaltfläche
`--aid-btnfg`	Text der Schließen-Schaltfläche
`--aid-hov`	Hover der Schließen-Schaltfläche

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

Das Snippet liefert keine !important-Regeln aus und verwendet Selektoren mit niedriger Spezifität, sodass Ihr CSS gewinnt. Die Klassen-Ankerpunkte sind .aid-banner, .aid-chip, .aid-badge, .aid-badge-inline, .aid-wrap, .aid-ai (Inhaltshinweis) und .aid-hm („made by humans“). Passen Sie Abstände, Radius und Schatten direkt an diesen an.

Standardmäßig ist das Banner ein festes Overlay am unteren Rand des Ansichtsbereichs. Setzen Sie mountSelector, um es inline und statisch innerhalb eines von Ihnen kontrollierten Elements darzustellen, sodass es sich in Ihr eigenes Layout einfügt.

Eigene Texte

Banner und Chip enthalten von Haus aus korrekten, lokalisierten Text in 28 Sprachen. So überschreiben Sie die Formulierungen:

Pro Sprache, im Manifest. Fügen Sie einem System disclosure.texts hinzu, indexiert nach Sprachcode. Das Snippet verwendet Ihren Text für die passende Sprache der besuchenden Person:

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

Pro Element. Fügen Sie einem markierten Element data-ai-label hinzu, um die Beschriftung dieses Abzeichens festzulegen.

Wenn ein System editorialResponsibility.humanReview: true setzt und sein Inhalt nicht vollständig KI-generiert oder manipuliert ist, lautet der Hinweis automatisch „KI-unterstützt, von Menschen geprüft“ in der Sprache der besuchenden Person, statt „KI-generiert“.

Ihre KI-Inhalte kennzeichnen

Das Snippet kennzeichnet nur, was Sie markieren. Fügen Sie jedem KI-generierten Element data-ai-content hinzu:

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

Jedes markierte Element erhält ein sichtbares „KI“-Abzeichen und ein maschinenlesbares data-digital-source-type (standardmäßig trainedAlgorithmicMedia, ein mit IPTC und schema.org kompatibler Wert). Fügen Sie data-ai-label für einen eigenen Beschriftungstext hinzu oder setzen Sie data-digital-source-type selbst, um genauer zu sein.

Für KI, die Sie nicht direkt annotieren können, etwa ein Chat-Widget eines Drittanbieters in einem geschlossenen iframe, verwenden Sie adjacentSelector, um eine Kennzeichnung daneben zu platzieren, oder triggerSelector, um das Interaktionsbanner einzublenden, wenn das Widget geöffnet wird.

Ein Content-Generation-Hinweis kann die gesamte Website abdecken (disclosure.scope: "site") oder bestimmte Seiten (disclosure.scope: "page" mit einer disclosure.pages-Liste aus Pfad-Globs, etwa /blog/*). Eine Übereinstimmung auf Seitenebene hat Vorrang vor einer auf Website-Ebene, und ein System mit Seitenbereich ohne passenden Pfad stellt dort nichts dar.

Single-Page-Apps und Frameworks

Das Snippet beobachtet das DOM mit einem MutationObserver und bewertet den anwendbaren Hinweis bei Routenwechseln neu, sodass nach dem Laden hinzugefügte Inhalte und Seiten weiterhin gekennzeichnet werden. In einer SPA:

Belassen Sie observe beim Standardwert (true), damit clientseitig gerenderter Inhalt erfasst wird.
Wenn Sie die Initialisierung von der Bereitschaft der Anwendung abhängig machen, fügen Sie data-manual hinzu und rufen Sie AIDisclose.init() auf, nachdem Ihr Framework gemountet ist.
Hinweise mit Seitenbereich aktualisieren sich automatisch bei Routenwechseln; ein Aufruf pro Route ist nicht nötig.

Setzen Sie observe: false nur auf vollständig statischen Seiten, auf denen nach dem Laden nichts eingefügt wird.

Content Security Policy

Wenn Sie eine Content Security Policy durchsetzen, erlauben Sie das Snippet ausdrücklich.

Wichtig

Ein striktes script-src 'self' blockiert das CDN-Snippet stillschweigend, und die Offenlegungen werden nie dargestellt. Dies ist der häufigste Grund, warum eine korrekt deklarierte Website Level 2 nicht erreicht.

script-src: Fügen Sie https://cdn.aidisclose.io hinzu oder hosten Sie aidisclose.js von Ihrem eigenen Ursprung und behalten Sie 'self' bei.
style-src: Das Snippet fügt seine Stile inline ein, daher genügt 'unsafe-inline'. Wenn Sie keine Inline-Stile erlauben, greift es auf das Laden von aidisclose.css aus dem Verzeichnis des Skripts zurück; erlauben Sie in diesem Fall auch https://cdn.aidisclose.io in style-src (oder hosten Sie diese Datei zusammen mit dem Skript selbst).
connect-src: Der Manifest-Abruf ist für die Well-known-Datei gleichen Ursprungs und benötigt nichts Zusätzliches. Wenn Sie das Manifest über einen Schlüssel laden, erlauben Sie https://cdn.aidisclose.io.

Das Manifest wird ohne Anmeldeinformationen abgerufen, stellen Sie es daher öffentlich bereit: ein Endpunkt, der Cookies oder Authentifizierung verlangt, erhält diese nicht.

Versionierung und Integrität

Das CDN liefert drei Tracks:

/v1/aidisclose.js folgt der neuesten 1.x-Version. Für die meisten Websites empfohlen.
/v1.0.0/aidisclose.js ist eine feste, unveränderliche Version, die Sie mit Subresource Integrity anheften können:

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

/latest/aidisclose.js folgt stets der neuesten Version über Hauptversionen hinweg.

Um den SRI-Hash zum Anheften zu erhalten, bauen Sie das Snippet: npm run build in packages/snippet gibt ihn aus (der Quelltext ist offen auf GitHub).

Eigene Offenlegungs-UI erstellen

Sie können anstelle der eingebauten Ihre eigene Offenlegungs-UI darstellen. Es gibt keinen einzelnen Ausschalter: data-banner="false" und persistentChip: false unterdrücken nur das Interaktionsbanner und seinen Chip, während Inhaltshinweise, [data-ai-content]-Abzeichen pro Element und das Abzeichen „made by humans“ weiterhin aus Ihrem Manifest und Markup dargestellt werden. Eine vollständig eigene UI bedeutet, sich nicht auf diese zu verlassen und stattdessen Ihre eigene darzustellen.

Hinweis

Der AIDisclose-Prüfer überprüft die Darstellung, indem er das Markup des Referenz-Snippets erkennt. Eine vollständig handgebaute Offenlegung ist gültig, wird aber nicht automatisch erkannt, sodass die Website bei Level 1 (Deklariert) statt Level 2 (Dargestellt) bleibt, es sei denn, Ihr eigenes Markup reproduziert, wonach der Prüfer sucht. Wenn Ihnen Level 2 wichtig ist, behalten Sie die eingebaute Darstellung bei und gestalten Sie sie mit CSS um.

Barrierefreiheit

Die dargestellte UI erfüllt WCAG 2.1 AA: sichtbare :focus-visible-Umrisse auf interaktiven Bedienelementen, korrekte Rollen und Beschriftungen, Kontrast, der in Hell und Dunkel bestehen bleibt, und Animation, die hinter prefers-reduced-motion gesteuert wird. Das Snippet erkennt zudem bekannte Cookie-Consent-Leisten und positioniert sich oberhalb von ihnen, sodass Offenlegungen nie hinter einer CMP verborgen sind. Auf sehr schmalen Bildschirmen öffnet sich das Interaktionsbanner als kompakter Chip, sodass es niemals Inhalte verdeckt.

#Überblick

#Installation

#Konfiguration

#Optionsreferenz

#Theme und Erscheinungsbild

#Eigene Texte

#Ihre KI-Inhalte kennzeichnen

#Single-Page-Apps und Frameworks

#Content Security Policy

#Versionierung und Integrität

#Eigene Offenlegungs-UI erstellen

#Barrierefreiheit