DocsSchnellstart

Den Nodale-Agenten auf Ihrer Website installieren

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.

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.

Das Tag einfügen

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

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

Content Security Policy

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

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:

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

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'). 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.

Für KI-Agenten: diese Seite in Markdown

Jeder Besuch zählt.