# Den Nodale-Agenten auf Ihrer Website installieren

<https://nodale.ai/de/docs>

Ein Script-Tag bringt den Nodale-Agenten auf Ihre Website. Wo Sie es einfügen, was Ihre Website erlauben muss und wie Sie prüfen, ob es läuft.

Der Nodale-Agent läuft über ein einziges Script-Tag auf Ihrer Website. Diese Seite richtet sich an den Entwickler, der es installiert. Um den Agenten aus Ihrem eigenen Code zu steuern, lesen Sie die [JavaScript API](https://nodale.ai/de/docs/api).

## Bevor Sie beginnen

Zwei Dinge müssen in Ihrem Nodale-Workspace erfüllt sein, sonst tut das Tag nichts:

1. **Der Agent ist veröffentlicht und online.** Der Tab Install Ihres Agenten zeigt die einzufügende Zeile erst, wenn der Agent veröffentlicht und sein Deployment live ist.
2. **Ihre Website ist deklariert.** Tragen Sie ihre Adresse unter **Allowed websites** ein, im selben Tab. Die Regeln stehen [weiter unten](#zugelassene-websites).

## Das Tag einfügen

```html
<script src="https://tag.nodale.app/v1/tag.js" data-workspace="YOUR_WORKSPACE_ID" async></script>
```

Kopieren Sie die Zeile aus dem Tab Install: Sie enthält bereits Ihre Workspace-ID. Fügen Sie sie auf jeder Seite ein, auf der der Agent laufen soll, im `<head>` oder direkt vor `</body>`.

- **Eine Zeile pro Workspace, einmal eingefügt.** Das Tag liest bei jedem Seitenaufruf die aktuelle Konfiguration Ihres Workspace. Eine neue veröffentlichte Version des Agenten oder eine geänderte Anzeige erreicht jede Seite, ohne dass jemand die Website anfasst.
- **Es läuft einmal pro Seite.** Es doppelt einzufügen oder es zusätzlich zur Seite über einen Tag-Manager zu laden, ist harmlos: Die zweite Kopie sieht die erste und stoppt.
- **Single-Page-Apps werden mitverfolgt.** Der Agent bleibt eingebunden, wenn Ihre App mit `pushState`, `replaceState` oder `popstate` navigiert.
- **Sprache.** Das Widget übernimmt die Sprache der Seite aus `<html lang>`. Um sie selbst festzulegen, ergänzen Sie das Tag um `data-lang`, zum Beispiel `data-lang="fr"`.
- **Ein Workspace pro Seite.** Auf einer Seite läuft genau ein Tag.

## Zugelassene Websites

Das Tag antwortet nur auf den Websites, die Ihr Workspace deklariert. Auf jeder anderen Website wird der Seite nichts hinzugefügt.

- Ein Eintrag ist ein Origin, mit Schema und Port: `https://www.example.com`. Er hat keinen Pfad.
- Nur `https`, außer `localhost` und `127.0.0.1` für die lokale Arbeit.
- `https://*.example.com` deckt jede Subdomain ab, in beliebiger Tiefe, aber nicht `example.com` selbst. Deklarieren Sie die Apex-Domain als eigenen Eintrag.
- Höchstens 20 Websites pro Workspace.
- Eine Änderung braucht keine Veröffentlichung. Eine entfernte Website zeigt den Agenten ab dem nächsten Seitenaufruf des Besuchers nicht mehr.

## Wo der Agent angezeigt wird

Die Anzeige ist eine Einstellung des Tabs Install, nicht des Tags:

- **Floating bar**: eine schwebende Leiste am unteren Rand der Seite.
- **Button**: ein Launcher in der Ecke unten rechts, der das Widget per Klick öffnet.

Um den Agenten stattdessen in Ihr eigenes Layout zu setzen, fügen Sie dieses Element an der gewünschten Stelle ein. Das Widget wird im ersten Element eingebunden, das es findet, im Fluss der Seite, unabhängig von der Anzeige-Einstellung:

```html
<div data-nodale-agent></div>
```

Eine dritte Anzeige, `hidden`, hält den Agenten unsichtbar, bis Ihr Code ihn öffnet. Sie ist bei der [JavaScript API](https://nodale.ai/de/docs/api#die-versteckte-anzeige) beschrieben.

## Content Security Policy

Eine Website, die eine Content Security Policy sendet, ergänzt die vorhandenen Direktiven um genau drei Quellen:

```text
script-src  https://tag.nodale.app;
frame-src   https://nodale.app;
connect-src https://nodale.app
```

- Kein `'unsafe-inline'`, kein `'unsafe-eval'`, kein Wildcard und keine Nonce: Das Tag ist ein externes Script ohne Inline-Code.
- Kein Eintrag für `style-src`, `img-src`, `font-src` oder `media-src`: Alles, was das Widget rendert, lädt in seinem eigenen Frame.
- `require-trusted-types-for 'script'` ist kompatibel.
- `frame-src` fällt auf `child-src` zurück, dann auf `default-src`.

## Mikrofon

Der Sprachmodus braucht das Mikrofon, und der Browser fragt erst danach, wenn der Besucher den Mikrofon-Button drückt, nie beim Laden der Seite.

Wenn Ihre Website einen `Permissions-Policy`-Header sendet, darf er dem Widget das Mikrofon nicht verweigern. Lassen Sie `microphone` entweder weg oder erlauben Sie den Nodale-Origin:

```text
Permissions-Policy: microphone=(self "https://nodale.app")
```

## Cookie-Banner

Ein Consent-Tool, das Scripts automatisch blockiert, muss das Nodale-Tag ausnehmen oder es in die Kategorie einordnen, die Ihr Workspace für das Besuchs-Tracking gewählt hat. Ein blockiertes Tag kann den Agenten nicht anzeigen.

Das Besuchs-Tracking ist standardmäßig aus. Wenn Sie es einschalten, werden Seitenaufrufe erst gezählt, nachdem der Besucher zugestimmt hat. Das Tag liest die Antwort aus Ihrem Cookie-Banner. Eine Website ohne Banner meldet sie mit [`nodale('consent')`](https://nodale.ai/de/docs/api#nodaleconsent). Der Agent selbst wird in beiden Fällen eingebunden.

## Die Installation prüfen

Öffnen Sie den Tab Install. Die Karte **Tag on your sites** führt jede deklarierte Website als **Detected** oder **Not detected** auf, mit dem Zeitpunkt, zu dem das Tag zuletzt gesehen wurde. **Check again** liest die Startseite jeder Website.

Wenn der Agent auf einer Seite nicht angezeigt wird, prüfen Sie in dieser Reihenfolge:

1. Die Website steht unter **Allowed websites**, mit exaktem Schema und exakter Subdomain.
2. Der Agent ist veröffentlicht und sein Deployment ist online.
3. Die Content Security Policy der Seite enthält die drei Quellen von oben.
4. Kein Consent-Tool blockiert das Script.

Das Tag schreibt nie einen Fehler auf Ihre Seite. Wenn es stoppt, hinterlässt es eine `console.debug`-Zeile, die mit `nodale tag:` beginnt.

## Docs

- [JavaScript API: den Nodale-Agenten aus Ihrem Code öffnen](https://nodale.ai/de/docs/api): Die nodale()-Befehle für Ihre Seite: den Agenten per eigenem Button oder Formular öffnen, E-Mail und Kontext übergeben, die Einwilligung des Besuchers melden. (Markdown: https://nodale.ai/de/docs/api.md)
- [MCP-Server: Ihren Nodale-Workspace aus Claude Code verwalten](https://nodale.ai/de/docs/mcp): Claude Code mit dem MCP-Server von Nodale verbinden, dann den Workspace lesen und ändern: Wissen, Demo-Assets, Agent-Einstellungen, Websites, Deployment. (Markdown: https://nodale.ai/de/docs/mcp.md)
