Widget einbauen

Das Chatfenster kommt mit einer einzigen Zeile auf Ihre Website. Diese Seite zeigt, wo der Einbaucode in der App steht, welche Einstellungen vorher gesetzt sein müssen, wie sich die beiden Einbauwege unterscheiden und woran Sie erkennen, dass das Fenster auf Ihrer Seite angekommen ist.

Wo der Einbaucode steht

Öffnen Sie in der App Arbeit › Assistenten (app.xicbot.de/assistenten) und klicken Sie beim gewünschten Assistenten auf Bearbeiten. Mit der Rolle Lesen heißt der Knopf Ansehen. Im geöffneten Bereich folgt der Abschnitt Chatfenster auf Ihrer Website mit dem Hinweis *Das Chatfenster läuft in einem eigenen Rahmen. Es kann die Seite, auf der es liegt, weder lesen noch verändern.* Dort stehen Freigabe, Domainliste, eigener Pfad, beide Einbaucodes, der Einbindungsstand, die Vorschau und der öffentliche Schlüssel. Der Bereich Assistenten öffnet sich erst, wenn Ihre E-Mail-Adresse bestätigt ist; bis dahin meldet die App Dieser Bereich bleibt gesperrt, bis die E-Mail-Adresse bestätigt ist.

Diese Vorgänge teilen sich eine Grenze von 30 je Minute und angemeldeter Person: Speichern in diesem Abschnitt und unter Grunddaten, Neuen Schlüssel erzeugen, das Anlegen von Assistenten, das Veröffentlichen und Zurückholen von Fassungen, das Anlegen und Ändern von Werkzeugen sowie das Anlegen und Ändern von Prüffragen und das Starten von Läufen in der Abnahme. Darüber meldet die App Zu viele Versuche. Bitte warten Sie einen Moment. Ein ganzer Lauf der Abnahme zählt als ein Vorgang, jedes Ein- oder Ausschalten einer Prüffrage ebenfalls. Wer in einer Minute viele Prüffragen umschaltet, muss danach bis zu einer Minute warten, bis Speichern wieder gelingt. Rollen vergeben Sie unter Team und Rollen.

In sechs Schritten auf die Website

1. 1

   Schritt 1

   Assistent auf aktiv stellen

   Unter Grunddaten im Feld Status den Wert aktiv wählen und dort mit Speichern übernehmen. Ein neuer Assistent beginnt als Entwurf, mit ausgeschaltetem Chatfenster und bereits einer ersten Fassung. Mit Entwurf oder pausiert antwortet der Einbaucode wie ein unbekannter Schlüssel.

2. 2

   Schritt 2

   Chatfenster freigeben

   Das Kästchen Chatfenster freigeben setzen und Speichern drücken. Die App erklärt dazu: *Erst mit dieser Freigabe antwortet der Schnipsel auf fremden Seiten. Ohne sie bleibt er wirkungslos.* Nach dem Speichern erscheint Gespeichert.

3. 3

   Schritt 3

   Domains eintragen, wenn gewünscht

   Unter Erlaubte Domains die Websites eintragen, auf denen Gespräche beginnen dürfen. Ein leeres Feld lässt jede Website zu.

4. 4

   Schritt 4

   Einbaucode kopieren

   Unter Einbaucode über unsere Adresse oder Einbaucode über Ihre eigene Adresse auf Einbaucode kopieren drücken. Die App bestätigt mit Einbaucode kopiert.

5. 5

   Schritt 5

   Code in die Seiten setzen

   Die Zeile in den Kopf (<head>) jeder Seite setzen, auf der das Fenster erscheinen soll, in der Regel über die Seitenvorlage Ihres Systems.

6. 6

   Schritt 6

   Einbindung prüfen

   Eine Seite mit dem Code im Browser aufrufen, danach den Assistenten in der App neu öffnen. Steht im Kasten Einbindung auf Ihrer Website der Eintrag Zuletzt geladen: mit Zeitpunkt, ist das Fenster angekommen.

Die beiden Einbauwege

Die App zeigt zwei Einbaucodes nebeneinander. Beide laden dasselbe Chatfenster, sie unterscheiden sich darin, über welche Adresse der Besucher es bezieht.

<!-- Einbaucode über unsere Adresse -->
<script src="https://cdn.xicbot.de/einbetten.js" data-xicbot="…" data-api="…" defer></script>

<!-- Einbaucode über Ihre eigene Adresse, Pfad https://example.com/chat -->
<script src="https://example.com/chat/einbetten.js" data-xicbot="…" data-basis="https://example.com/chat" defer></script>

Die Auslassungszeichen stehen hier für Ihren Schlüssel und die Adresse der Schnittstelle. Kopieren Sie den Code aus der App, statt ihn abzutippen: dort stehen alle Werte ausgeschrieben.

Weitere Angaben am Code, etwa Farbe, Platz oder Sprache, beschreibt Script-Attribute. Aussehen, Texte und Position holt das Fenster beim Laden vom Server; was Sie dort unter Widget-Einstellungen ändern, gilt ohne neuen Code. Den Code tauschen Sie nur aus, wenn Sie einen neuen Schlüssel erzeugen, Einwilligung vor dem ersten Gespräch ein- oder ausschalten oder den eigenen Pfad ändern.

Für die Auslieferung über cdn.xicbot.de gilt:

• Nach dem ersten Aufruf spricht der Browser cdn.xicbot.de ein Jahr lang nur verschlüsselt an.
• Suchmaschinen sollen die Dateien nicht aufnehmen und ihren Verweisen nicht folgen.
• Kein Kopf verbietet das Einbetten in fremde Seiten. Die Trennung von Ihrer Seite leistet der abgeschottete Rahmen.
• Antwortet die Auslieferung nicht, bricht cdn.xicbot.de nach 3 Sekunden Verbindungsaufbau oder 10 Sekunden Warten mit einem Fehler ab, statt die Anfrage offen zu halten. Dank defer wartet Ihre Seite nicht auf den Lader.

Freigabe und Status

Das Chatfenster arbeitet nur, wenn alle vier Bedingungen erfüllt sind:

• Chatfenster freigeben ist gesetzt und gespeichert.
• Der Status des Assistenten ist aktiv, nicht Entwurf und nicht pausiert.
• Ihr Konto ist aktiv.
• Bei einem Demozugang ist die Frist nicht abgelaufen.

Fehlt eine davon, behandelt das Chatfenster das wie einen unbekannten Schlüssel. Auf Ihrer Website nimmt der Lader dann den Auslöser vom Bildschirm und entfernt das Chatfenster, sobald dieses nach dem Laden Ihrer Seite seine Einstellungen abgerufen hat. Trägt der Code data-einwilligung="erforderlich", geschieht das erst nach einer Zustimmung oder einem Klick auf den Auslöser; in der Vorschau der App steht Dieser Chat ist nicht verfügbar. Ist der Assistent aktiv, hat aber noch keine aktive Fassung, erscheint das Fenster mit dem Satz Dieser Assistent ist noch nicht bereit. Fassungen verwalten Sie unter Assistenten.

Erlaubte Domains

Das Feld Erlaubte Domains nimmt bis zu 500 Zeichen auf. Die App sagt dazu: *Eine pro Zeile. Unterdomains sind eingeschlossen. Leer heißt: jede Website darf das Fenster einbinden.*

• Ein Eintrag je Zeile, ein Komma trennt ebenfalls. Groß- und Kleinschreibung spielt keine Rolle, Leerzeichen am Rand fallen weg.
• Tragen Sie nur den Rechnernamen ein, etwa example.com. Verglichen wird der reine Name der Seite ohne https://, Pfad und Port; ein Eintrag mit diesen Bestandteilen passt auf keine Seite.
• example.com deckt shop.example.com und www.example.com mit ab. Umgekehrt deckt www.example.com die Adresse example.com nicht ab.
• Meldet das Fenster keinen Rechnernamen, gilt die Seite bei gefüllter Liste als nicht freigegeben.
• Ein leeres Feld bedeutet keine Einschränkung.

Geprüft wird die Liste, wenn ein Besucher das Fenster öffnet und damit das Gespräch beginnt. Verlangt der Code eine Einwilligung, beginnt das Gespräch und damit die Prüfung erst nach der Zustimmung. Die Adresse der Seite meldet das Fenster dabei selbst mit. Steht sie nicht in der Liste, liest der Besucher Dieser Chat ist für diese Website nicht freigegeben. Der Auslöser erscheint auf einer solchen Seite trotzdem, und Einbindung auf Ihrer Website hält auch sie fest. Der Schlüssel bleibt dabei im Seitenquelltext lesbar; die Liste regelt, wo Gespräche beginnen. Ist die Seite erlaubt, die Adresse des Besuchers aber gesperrt, liest er Dieser Chat steht Ihnen derzeit nicht zur Verfügung., und Eingabefeld und Senden bleiben gesperrt, siehe Gespräche.

Eigener Pfad auf Ihrer Domain

Mit Eigener Pfad auf Ihrer Domain laufen Fenster und Anfragen über Ihre Domain. Die App nennt das *Der empfohlene Weg: Fenster und Anfragen laufen über Ihre Domain, der Besucher spricht mit keiner fremden Adresse.* Dafür reicht Ihr Webserver einen Pfad an XICBOT weiter. Für das Feld gilt:

• Eine absolute Adresse mit https:// oder http:// und Rechnername, etwa https://example.com/chat.
• Das Feld ist ein Adressfeld: Eine Eingabe ohne Schema, etwa example.com/chat, lässt der Browser nicht absenden. Andere Schemata als https:// oder http:// weist erst der Dienst beim Speichern ab.
• Höchstens 200 Zeichen.
• Keine Abfrage (?…) und kein Fragment (#…).
• Ein Schrägstrich am Ende und Leerzeichen am Rand fallen beim Speichern weg.
• Ein leeres Feld heißt: kein eigener Pfad eingerichtet. Der zugehörige Einbaucode verschwindet dann.
• Lehnt der Dienst den Wert beim Speichern ab, nennt die App den Grund direkt unter dem Feld, etwa Die Adresse Ihres eigenen Pfads darf weder „?“ noch „#“ enthalten. Hat der Dienst nur markierte Felder abgelehnt, meldet die App dazu Bitte prüfen Sie die markierten Felder.

Einbaucode über Ihre eigene Adresse erscheint erst nach dem Speichern. Bis dahin steht dort *Sobald oben ein eigener Pfad steht und gespeichert ist, erscheint hier der zugehörige Einbaucode.* Dieser Code trägt kein data-api: Der Lader nimmt den Pfad nur dann auch für die Schnittstelle, wenn Protokoll, Rechnername und Port des Pfads genau mit der Seite übereinstimmen, auf der er steht. Tragen Sie den Pfad deshalb mit dem Rechnernamen ein, unter dem Ihre Seiten laufen, bei https://www.example.com also https://www.example.com/chat.

Was Ihr Server weiterreicht

• X-Xicbot-Base setzt Ihr Server selbst und reicht keinen gleichnamigen Kopf des Besuchers durch. Aus diesem Kopf entsteht die Sicherheitsrichtlinie des Chatfensters.
• X-Xicbot-Api brauchen Sie nur, wenn die Schnittstelle nicht unter demselben Pfad liegt. Ohne ihn gilt X-Xicbot-Base auch für die Schnittstelle. Auch diesen Kopf setzt oder leert Ihr Server selbst.
• Beide Köpfe enthalten eine Adresse aus http:// oder https://, Rechnername in Kleinbuchstaben, optional Port und Pfad, höchstens 200 Zeichen. Ein gesetzter, aber unbrauchbarer Kopf wird mit Status 400 abgewiesen, statt still auf die Standardadresse zurückzufallen.
• Unbekannte Fassungsnamen beantwortet die Auslieferung mit 404.
• Setzen Sie die Köpfe der Auslieferung (Zwischenspeicher, Herkunft, Inhaltstyp, Sicherheitsrichtlinie) nicht noch einmal. Sie kommen von XICBOT und stünden sonst doppelt in der Antwort.

Wie der Lader startet

• einbetten.js baut das Chatfenster erst, wenn Ihre Seite fertig geladen ist.
• Steht der Einbaucode zweimal auf einer Seite, bleibt der zweite ohne Wirkung. Je Seite gibt es ein Chatfenster.
• Der Lader selbst stellt keine Anfragen ins Netz. Alles, was Daten holt, läuft im Chatfenster.
• Das Chatfenster ist ein Rahmen fremden Ursprungs mit sandbox="allow-scripts allow-popups allow-popups-to-escape-sandbox" und ohne allow-same-origin. Ihre Seite kann seinen Inhalt nicht lesen und das Fenster nicht den Ihrer Seite. Die Gesprächskennung legt der Lader allerdings im Speicher Ihrer Seite ab; wer sie kennt, kann den Verlauf abrufen, Skripte auf Ihrer Seite eingeschlossen.
• Der Rahmen lädt ohne Verweisadresse (referrerpolicy="no-referrer"). Seine Angaben, darunter der Ursprung Ihrer Seite, stehen im Fragment der Adresse; ein Fragment geht beim Laden des Rahmens nicht an den Server. Den Rechnernamen Ihrer Seite meldet das Fenster danach selbst an den Dienst, für den Einbindungsstand und für Erlaubte Domains.
• Das Fenster liegt in der obersten Ebene des Browsers. Kennt ein Browser diese Ebene nicht, hält es sich mit der Stapelzahl 2147483647 über Ihrer Seite.
• Ist Einwilligung vor dem ersten Gespräch eingeschaltet, lädt vor der Zustimmung nichts von selbst. Ein Klick auf den Auslöser baut das Fenster.
• Wie Ihre Seite das Fenster per Skript steuert, beschreibt JavaScript und Speicher.

Sicherheitsrichtlinie Ihrer Seite

Hat Ihre Seite eine Content-Security-Policy, gilt für das Widget:

• Ihre Richtlinie muss den Lader von der Adresse im Einbaucode laden und das Chatfenster als Rahmen von derselben Basis einbetten lassen. Beim eigenen Pfad ist das Ihre eigene Domain.
• Für die Schnittstelle braucht Ihre Richtlinie keinen Eintrag: Die Anfragen stellt das Chatfenster, nicht Ihre Seite.
• Der Lader hängt kein <style> ein, sondern setzt jede Eigenschaft einzeln am Element. Eine strenge Regel für Stile hält ihn deshalb nicht auf.
• Das Bild im Auslöser kommt als data:-Adresse. Lässt Ihre Richtlinie das für Bilder nicht zu, zeigt der Auslöser stattdessen die Punkte der Marke.
• Das Chatfenster bringt seine eigene Richtlinie mit. Sie erlaubt die Einbettung auf jeder Seite; wo Gespräche beginnen, regelt Erlaubte Domains.

Einbindung prüfen

Der Kasten Einbindung auf Ihrer Website zeigt entweder Zuletzt geladen: mit Datum und Uhrzeit und darunter Seite: mit dem Rechnernamen, auf dem das Fenster zuletzt geladen hat, oder Das Fenster hat auf Ihrer Website noch nie geladen. Darunter erklärt die App: *Festgehalten wird, wann das Fenster zuletzt auf einer fremden Seite geladen hat - nicht das erste Gespräch. Die Vorschau auf dieser Seite zählt nicht mit.*

• Der Eintrag entsteht, sobald das Chatfenster seine Einstellungen abruft, auch bei einem Assistenten ohne aktive Fassung. Hat der Besucher die Anfragegrenze erreicht, entsteht bei diesem Abruf kein Eintrag.
• Festgehalten wird der Rechnername der Seite in Kleinbuchstaben, höchstens 120 Zeichen.
• Lädt das Fenster erneut auf demselben Rechnernamen, schreibt der Dienst den Zeitpunkt höchstens alle fünf Minuten neu. Ein anderer Rechnername wird sofort übernommen.
• Trägt der Einbaucode data-einwilligung="erforderlich", entsteht der Eintrag erst, wenn ein Besucher zustimmt oder den Auslöser anklickt.
• Ohne Freigabe, ohne Status aktiv oder bei ruhendem Konto entsteht kein Eintrag.
• Seiten außerhalb von Erlaubte Domains zählen mit, weil die Liste erst beim Gesprächsbeginn geprüft wird.
• Kann die App den Stand nicht laden, steht dort Der Stand konnte nicht geladen werden.
• Die App liest die Anzeige beim Öffnen des Assistenten, nach dem Speichern und nach einem neuen Schlüssel. Einen neueren Stand sehen Sie, wenn Sie den Assistenten schließen und erneut öffnen.

Vorschau anzeigen öffnet das Fenster in der App; die Vorschau antwortet nicht und gilt nicht als Einbindung, Einzelheiten unter Vorschau in der App. Sie lädt über unsere Adresse, auch wenn ein eigener Pfad eingetragen ist. Ob Ihr Pfad funktioniert, zeigt erst der Aufruf Ihrer eigenen Seite. Wie Sie Antworten vor dem Einbau testen, steht unter Probieren und abnehmen.

Öffentlicher Schlüssel

Unter Öffentlicher Schlüssel steht die Kennung aus 32 Zeichen (Ziffern und a bis f), die im Einbaucode als data-xicbot erscheint. Die App sagt dazu: *Er steht im Klartext auf jeder fremden Seite. Er erlaubt nur, dieses eine Chatfenster zu nutzen.* Der Schlüssel entsteht beim Anlegen des Assistenten und lässt sich nicht von Hand eintragen.

Neuen Schlüssel erzeugen steht den Rollen Verwaltung und Inhaber offen; bei anderen Rollen steht dort *Einen neuen Schlüssel erzeugt, wer die Rolle Verwaltung oder Inhaber hat.* Nach dem Klick fragt die App: *Neuen Schlüssel erzeugen? Der bisherige Einbaucode hört sofort auf zu arbeiten.* Bestätigen Sie mit Neuen Schlüssel erzeugen oder brechen Sie mit Abbrechen ab.

• Der alte Schlüssel gilt ab diesem Moment nicht mehr. Jede Seite mit dem alten Code verliert ihren Auslöser, sobald das Chatfenster dort lädt.
• Die App holt den Einbaucode neu, zeigt bis dahin Wird geladen … und meldet danach Neuer Schlüssel ist aktiv. Bitte den Einbaucode überall austauschen. Klappen Sie den Assistenten während des Tauschs zu und wieder auf, kommt der neue Einbaucode je nach Zeitpunkt erst mit dem Aufklappen; die Meldung kann dann schon stehen, während noch Wird geladen … zu sehen ist.
• Kommt der neue Einbaucode danach nicht an, ist der Tausch trotzdem vollzogen. Statt einer Fehlermeldung steht dann Neuer Schlüssel ist aktiv, der bisherige Einbaucode lädt nicht mehr. Der neue Einbaucode konnte nicht geladen werden. Öffnen Sie den Assistenten erneut, um ihn zu sehen, und tauschen Sie ihn überall aus. An der Stelle der Codes steht Der Stand konnte nicht geladen werden.
• Ist der Assistent beim Abschluss des Tauschs nicht mehr geöffnet, etwa weil Sie inzwischen einen anderen geöffnet haben, nennt die App ihn beim Namen: Der neue Schlüssel für „…“ ist aktiv, der bisherige Einbaucode lädt nicht mehr. Öffnen Sie diesen Assistenten, um den neuen Einbaucode zu sehen, und tauschen Sie ihn überall aus.
• Das Protokoll hält fest, wer den Schlüssel getauscht hat und wann. Der Schlüssel selbst steht nicht darin, weder alt noch neu.
• Kommt der Eintrag ins Protokoll nicht zustande, bleibt der alte Schlüssel, und die App meldet Nicht gespeichert: Der Eintrag ins Protokoll kam nicht zustande. Bitte versuchen Sie es erneut.

Meldungen

Weiterlesen

• Widget-Einstellungen: Titel, Farbe, Position, Größe und Ansprache.
• Script-Attribute: alle Angaben am Einbaucode.
• Einwilligung und Besucherrechte: Einwilligungstor und Widerruf.
• Widget-Auslieferung: Dateien, Fassungen und Zwischenspeicher.
• Gespräch im Widget: was der Besucher im Fenster erlebt.
• API: Widget: die öffentlichen Endpunkte des Chatfensters.
• Gespräche: Gespräche lesen und Besucher sperren.

Häufige Fragen