DocsWidget-Code

Widget einbauen (Code-Snippet)

Eine einzige Skript-Zeile bindet den Alpheris-Chatbot in jede Website ein — egal auf welcher Plattform. Hier erfährst du, wo du das Snippet im Dashboard findest, wo es im Quelltext platziert wird und was bei Cache und Reload zu beachten ist.

Das Code-Snippet

Alpheris wird über einen einzigen <script>-Tag eingebunden. Er lädt den Widget-Loader von alpheris.com und identifiziert deinen Shop über das Attribut data-alpheris-key. So sieht der Code aus:

HTML

<!-- Alpheris Chat Widget -->
<script src="https://alpheris.com/widget.js" data-alpheris-key="INSTALL_ID" crossorigin="anonymous" async></script>
<!-- End Alpheris Chat Widget -->

Ersetze INSTALL_ID durch deine eigene Install-ID. Im fertigen Snippet aus dem Dashboard ist dieser Wert bereits eingetragen — du kopierst dort also den vollständigen Code und brauchst nichts mehr von Hand anzupassen.

Die Install-ID ist der Schlüssel, der das Widget mit deinem Konto und deiner Wissensbasis verbindet. Sie ist nicht geheim (sie steht im öffentlichen Quelltext deiner Seite), aber sie wird serverseitig an deine verifizierte Domain gebunden — siehe Abschnitt Domain-Bindung weiter unten.

Attribute im Snippet

Attribut	Bedeutung
`src`	Loader-Skript `https://alpheris.com/widget.js`. Lädt das eigentliche Widget nach.
`data-alpheris-key`	Deine Install-ID. Pflicht. Ohne diesen Wert erscheint kein Widget.
`crossorigin`	`anonymous` — lädt das Skript ohne Cookies/Credentials, sauber für CORS.
`async`	Lädt das Skript asynchron, damit deine Seite nicht blockiert wird.

Das Attribut data-key wird vom Loader als Alias ebenfalls akzeptiert, falls dein Theme oder Tag-Manager das längere Attribut verändert. Bevorzuge im Normalfall jedoch data-alpheris-key.

Wo platziere ich den Code?

Füge das Snippet direkt vor dem schließenden </body>-Tag ein — auf jeder Seite, auf der der Chatbot erscheinen soll. In den meisten Fällen ist das ein gemeinsames Template (Footer / Layout), sodass eine einzige Stelle reicht.

HTML

    <!-- … dein Seiteninhalt … -->

    <!-- Alpheris Chat Widget -->
    <script src="https://alpheris.com/widget.js" data-alpheris-key="INSTALL_ID" crossorigin="anonymous" async></script>
  </body>
</html>

Warum vor </body> und nicht im <head>? Durch async blockiert das Skript zwar ohnehin nicht den Seitenaufbau, aber die Platzierung am Ende des <body> stellt sicher, dass das restliche Markup zuerst geladen wird und das Widget zuverlässig an den fertigen DOM andocken kann.

Binde das Snippet nur einmal pro Seite ein. Wird es doppelt geladen (z. B. einmal über das Theme und einmal über einen Tag-Manager), kann das Widget mehrfach erscheinen. Bei Shopify und WordPress übernimmt Alpheris die Einbindung automatisch — füge dort den Code nicht zusätzlich von Hand ein.

Wo finde ich den Code im Dashboard?

Den fertigen, auf deinen Shop zugeschnittenen Snippet findest du in der Konsole unter Einbindung. Dort ist die Install-ID bereits eingesetzt.

Konsole öffnen

Melde dich unter console.alpheris.com an.

Zu „Einbindung" wechseln

Im Menü den Bereich Einbindung öffnen. Die Standard-Methode ist Code — das manuelle Einfügen des Snippets, das auf jeder Plattform funktioniert.

Snippet kopieren

Den angezeigten <script>-Block mit dem Kopieren-Button übernehmen. Die data-alpheris-key-Install-ID ist bereits enthalten.

In die Website einfügen

Das Snippet vor </body> deines Seiten-Templates platzieren und veröffentlichen.

Neben der Methode Code bietet der Bereich „Einbindung" auch geführte 1-Klick-Wege für Shopify (per App-Installation) und WordPress an. Bei diesen Wegen wird das Widget automatisch eingebunden — den manuellen Snippet brauchst du dann nicht.

Domain-Bindung

Aus Sicherheitsgründen ist die Install-ID an deine verifizierte Domain gebunden. Anfragen des Widgets werden serverseitig gegen den Host der einbettenden Seite geprüft (Strict-Domain-Modus, standardmäßig aktiv). Praktisch heißt das:

Das Widget funktioniert auf der Domain, die du im Dashboard hinterlegt und verifiziert hast.
Bei Shopify- und WordPress-Installationen wird die Domain automatisch mit verifiziert.
Setzt du das Snippet auf eine andere, nicht freigegebene Domain, lädt das Widget bewusst nicht.

Welche Domains erlaubt sind und wie du weitere hinzufügst, ist im Abschnitt Domains beschrieben.

Zum lokalen Testen oder auf einer Staging-Domain musst du diese Domain ebenfalls im Dashboard freigeben — sonst greift die Domain-Prüfung und das Widget bleibt aus.

Cache & Reload

Nach dem Einfügen erscheint das Widget beim nächsten Laden der Seite — typischerweise unten rechts. Wenn du nichts siehst oder eine Änderung nicht erscheint, liegt es fast immer am Caching:

Hard-Reload im Browser

Lade die Seite mit geleertem Cache neu: Strg+Shift+R (Windows/Linux) bzw. Cmd+Shift+R (macOS). Alternativ ein privates/Inkognito-Fenster nutzen.

Seiten-/CDN-Cache leeren

Nutzt deine Plattform einen Page-Cache oder ein CDN (z. B. ein Caching-Plugin oder Cloudflare), leere dessen Cache, damit das neue Markup mit dem Snippet ausgeliefert wird.

Konfigurationsänderungen

Design, Begrüßung und andere Einstellungen werden im Dashboard verwaltet, nicht im Snippet. Solche Änderungen greifen nach kurzer Zeit automatisch — ein erneutes Bearbeiten des Codes ist nicht nötig, ein Reload der Seite genügt.

Gut zu wissen: Da das gesamte Verhalten des Widgets über das Dashboard gesteuert wird, musst du das Snippet nur ein einziges Mal einbauen. Spätere Anpassungen an Aussehen, Texten oder Wissensbasis erfordern keinen Code-Eingriff.

Es erscheint kein Widget?

Wenn nach Hard-Reload und geleertem Cache weiterhin nichts auftaucht, prüfe der Reihe nach:

Snippet vorhanden: Liegt der <script>-Tag wirklich im ausgelieferten HTML, vor </body>? (Quelltext der Seite ansehen.)
Install-ID korrekt: Stimmt der Wert in data-alpheris-key mit dem aus dem Dashboard überein?
Domain freigegeben: Läuft die Seite auf einer im Dashboard verifizierten Domain?
Kein doppeltes Skript: Bei Shopify/WordPress nicht zusätzlich von Hand einfügen.

Mehr Diagnose-Schritte findest du unter Fehlerbehebung.