Script-Attribute des Einbaucodes

Der Einbaucode des Chatfensters ist ein einzelnes <script>-Element. Seine data--Attribute steuern den Lader einbetten.js: welcher Assistent erscheint, woher Chatfenster und Anfragen kommen, in welcher Farbe und Ecke der Auslöser steht, welche Sprache gilt und ob das Chatfenster auf eine Einwilligung wartet. Hier steht zu jedem Attribut, ob es Pflicht ist, welche Werte es annimmt, was ohne Angabe gilt und was bei einem ungültigen Wert geschieht.

Die Attribute im Überblick

Der Einbaucode aus der App

Den fertigen Einbaucode finden Sie in der App unter Arbeit › Assistenten (app.xicbot.de/assistenten) beim jeweiligen Assistenten im Bereich Chatfenster auf Ihrer Website. Dort stehen zwei schreibgeschützte Felder: Einbaucode über unsere Adresse und Einbaucode über Ihre eigene Adresse. Das zweite erscheint erst, wenn Eigener Pfad auf Ihrer Domain eingetragen und gespeichert ist; bis dahin steht an seiner Stelle „Sobald oben ein eigener Pfad steht und gespeichert ist, erscheint hier der zugehörige Einbaucode.“ Nach Speichern holt die App den Einbaucode neu, mit Einbaucode kopieren übernehmen Sie ihn. Wie er in die Seite kommt, beschreibt Widget einbauen.

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

<!-- Derselbe Code mit Einwilligung vor dem ersten Gespräch -->
<script src="https://example.com/chat/einbetten.js" data-xicbot="…" data-basis="https://example.com/chat" data-einwilligung="erforderlich" defer></script>

Der Einbaucode über unsere Adresse trägt data-api, der über Ihre eigene Adresse trägt data-basis und kein data-api. data-einwilligung="erforderlich" hängt die App an beide an, sobald Einwilligung vor dem ersten Gespräch eingeschaltet und gespeichert ist. Farbe, Ecke und Sprache stehen in keinem der beiden; wer sie setzen will, ergänzt sie im kopierten Code:

<!-- Einbaucode mit Farbe, Ecke und Sprache -->
<script src="https://example.com/chat/einbetten.js" data-xicbot="…" data-basis="https://example.com/chat"
        data-farbe="#0f766e" data-platz="links" data-senkrecht="unten" data-sprache="en" defer></script>

data-xicbot

data-xicbot trägt den öffentlichen Schlüssel des Assistenten. Die App vergibt ihn beim Anlegen des Assistenten: 32 Zeichen aus Ziffern und den Buchstaben a bis f. In der App steht er unter Öffentlicher Schlüssel mit dem Hinweis „Er steht im Klartext auf jeder fremden Seite. Er erlaubt nur, dieses eine Chatfenster zu nutzen.“ Leerzeichen am Anfang und Ende entfernt der Lader; bleibt danach nichts übrig, bricht er ab, und auf der Seite erscheint nichts.

• Sein eigenes <script>-Element findet der Lader über document.currentScript. Wo das nicht greift, nimmt er das erste Element script[data-xicbot] der Seite.
• Je Seite wirkt ein Einbaucode. Der erste, der ausgeführt wird, baut das Chatfenster; jeder weitere endet ohne Wirkung. Zwei Assistenten auf derselben Seite lassen sich deshalb nicht einbinden.
• Der Schlüssel ist Teil der Namen, unter denen der Browser das laufende Gespräch und die Einwilligung ablegt: xicbot.gespraech.<Schlüssel> und xicbot.einwilligung.<Schlüssel>. Einzelheiten stehen unter JavaScript und Speicher.
• Nach Neuen Schlüssel erzeugen nimmt die Schnittstelle den bisherigen Schlüssel nicht mehr an. Auf jeder Seite, die danach mit dem bisherigen Einbaucode geladen wird, verschwinden Auslöser und Chatfenster, sobald das Chatfenster die Antwort der Schnittstelle erhält. Mit dem neuen Einbaucode beginnen Gespräch und Einwilligung für Besucher neu, weil die Namen mit dem Schlüssel wechseln. Siehe Öffentlicher Schlüssel.

data-basis

data-basis legt fest, aus welchem Verzeichnis der Lader das Chatfenster rahmen.html holt. Ohne das Attribut ist es das Verzeichnis, aus dem einbetten.js selbst geladen wurde. Der Einbaucode über Ihre eigene Adresse trägt es trotzdem ausdrücklich: wer die Datei später in ein eigenes Paket übernimmt oder aus einem anderen Verzeichnis ausliefert, verschöbe sonst unbemerkt auch das Chatfenster.

• Ein relativer Wert wie /chat wird gegen die Adresse der aktuellen Seite aufgelöst.
• Zulässig sind nur http: und https:. Bei einem anderen Schema oder einem Wert, der sich nicht als Adresse lesen lässt, baut der Lader nichts: kein Auslöser, kein Chatfenster, keine Meldung. Auf die Vorgabe fällt er in diesem Fall nicht zurück.
• Abfrage (?…) und Anker (#…) fallen weg, Schrägstriche am Ende ebenso.
• Stimmt der Ursprung der Basis mit dem der Seite überein, also Schema, Domain und Port, laufen auch die Anfragen über diese Basis, sofern kein data-api gesetzt ist. https://www.example.com und https://example.com gelten dabei als verschieden.

In der App heißt das zugehörige Feld Eigener Pfad auf Ihrer Domain. Es nimmt bis zu 200 Zeichen auf und erwartet eine absolute Adresse mit http oder https, ohne Abfrage und ohne Anker. Einen Schrägstrich am Ende entfernt die App beim Speichern; ein leeres Feld entfernt den eigenen Pfad wieder. Was Ihr Server dafür bereitstellen muss, steht unter Eigener Pfad.

data-api

data-api nennt die Adresse, an die das Chatfenster seine Anfragen richtet. Fehlt das Attribut oder ist es leer, gilt: Liegt die Basis auf demselben Ursprung wie die Seite, ist die Basis auch die Schnittstelle, andernfalls die Schnittstelle von XICBOT. Schrägstriche am Ende entfernt der Lader. Einen gesetzten Wert prüft er sonst nicht: Leerzeichen am Rand bleiben stehen, und das Schema wird nicht geprüft.

Der Einbaucode über unsere Adresse trägt data-api mit der Adresse unserer Schnittstelle. Der Einbaucode über Ihre eigene Adresse trägt es bewusst nicht: dort ergibt sich die Schnittstelle aus der Basis, und ein ausdrücklicher Wert würde wieder auf eine fremde Adresse zeigen.

data-farbe

data-farbe färbt den Auslöser, bis die Einstellungen aus der App eintreffen. Erlaubt ist # mit genau sechs Hexziffern in beliebiger Schreibung, etwa #0f766e oder #0F766E. Kurzformen wie #fff, Farbnamen, rgb() und Leerzeichen um den Wert gelten als ungültig; dann gilt #4f46e5.

Das Attribut wirkt nur auf den Auslöser. Das Chatfenster selbst nimmt die Farbe aus der App, und sobald sie eintrifft, färbt sie auch den Auslöser um. Die ersten beiden Punkte im Auslöser erscheinen in #000000 oder #ffffff, je nachdem, was auf der Farbe mehr Kontrast ergibt; der dritte Punkt ist #22d3ee. Ist in der App ein Bild in der Titelleiste hinterlegt, zeigt der Auslöser nach dem Eintreffen der Einstellungen dieses Bild statt der Punkte; lädt es nicht, erscheinen wieder die Punkte.

Das Feld Farbe in der App ist ein Farbwähler und speichert dasselbe Format; neue Assistenten beginnen mit #4f46e5. Steht in data-farbe derselbe Wert wie in der App, wechselt die Farbe beim Laden nicht sichtbar.

data-platz und data-senkrecht

Die beiden Attribute bestimmen die Ecke, in der der Auslöser steht und an der sich das Chatfenster öffnet. Sie nehmen deutsche und englische Werte an; Groß- und Kleinschreibung und Leerzeichen am Rand spielen keine Rolle. Einen anderen Wert übergeht der Lader.

In der App entspricht das dem Feld Ecke des Fensters; neue Assistenten beginnen mit unten rechts:

Abstände, Fenstergröße, Skalierung und Eckenradius lassen sich nicht über Attribute setzen. Bis die Einstellungen eintreffen, gelten 20 px Abstand zum Seitenrand und zur Ober- oder Unterkante, ein Fenster von 384 × 620 px, die Skalierung 100 und ein Eckenradius von 18 px; der Auslöser misst dabei 56 px. Danach gelten Abstand zum Seitenrand (px), Abstand zur Ober- oder Unterkante (px), Breite des Fensters (px), Höhe des Fensters (px), Skalierung (%) und Eckenradius (px) aus der App, beschrieben unter Einstellungen des Chatfensters.

data-sprache

data-sprache legt fest, in welcher Sprache das Chatfenster seine festen Texte zeigt. Erlaubt ist ein Kürzel aus zwei Buchstaben, auf Wunsch mit Region: de, en, en-gb. Leerzeichen am Rand und Großbuchstaben bereinigt der Lader, EN-GB wirkt also wie en-gb. Formen wie de_AT, deu oder zh-Hant sind ungültig und zählen wie ein fehlendes Attribut.

Wirksam sind Deutsch und Englisch. Ein gültiges anderes Kürzel wie fr geht zwar als Sprachwunsch an die Schnittstelle, das Chatfenster nimmt dann aber die Sprache der aktiven Fassung, also Deutsch oder English. Dieselbe Fassungssprache gilt ohne Attribut. Steht ein deutsches oder englisches Kürzel, geht es der Fassungssprache vor.

Das Attribut bestimmt:

• die Beschriftungen im Chatfenster und seine Sprachangabe lang,
• die Beschriftungen des Auslösers für Vorlesehilfen: „Chat öffnen“ oder „Open chat“, bis die Einstellungen eintreffen, und im geöffneten Zustand „Chat schließen“ oder „Close chat“,
• die Beschriftung des Kreuzes an der Sprechblase der Ansprache: „Hinweis schließen“ oder „Dismiss message“,
• den Hinweis auf den Assistenten: „Sie schreiben mit einem automatischen Assistenten.“ beziehungsweise „You are chatting with an automated assistant.“,
• den Hinweis zu den Grenzen des Assistenten,
• den Vorgabetext der Einwilligung, wenn Text der Einwilligung leer ist: „Ich bin damit einverstanden, dass mein Gespräch gespeichert und zur Beantwortung meiner Frage verarbeitet wird.“ beziehungsweise „I agree that my conversation is stored and processed in order to answer my question.“

Das Attribut bestimmt nicht:

• den Namen im Chatfenster (Überschrift im Fenster), die Begrüßung und die Texte der Ansprache: sie erscheinen so, wie sie in der App gepflegt sind,
• einen eigenen Text der Einwilligung,
• die Sprache der Antworten: sie richtet sich nach dem, was der Besucher schreibt; lässt sich das nicht erkennen, nach der bisherigen Sprache des Gesprächs und zuletzt nach der Fassung.

data-einwilligung

Mit data-einwilligung="erforderlich" wartet der Lader mit dem Chatfenster, bis eine Zustimmung vorliegt. Der Auslöser erscheint trotzdem sofort. Erkannt wird nur genau erforderlich in Kleinbuchstaben; Leerzeichen am Rand stören nicht, Erforderlich oder ja wirken dagegen wie ein fehlendes Attribut.

Ohne das Attribut baut der Lader das Chatfenster, sobald die Seite fertig geladen ist, und das Chatfenster ruft dabei die öffentliche Konfiguration des Assistenten ab.

Die App hängt das Attribut an beide Einbaucodes, wenn Einwilligung vor dem ersten Gespräch eingeschaltet und gespeichert ist. Ein bereits eingesetzter Einbaucode ändert sich dadurch nicht: Kopieren Sie ihn nach dem Umschalten neu.

Das Tor öffnet sich auf einem dieser Wege:

• Ihre Seite ruft window.xicbot.einwilligen() auf, etwa aus Ihrem Einwilligungsbanner. Der Aufruf legt die Zustimmung für 180 Tage im Speicher des Browsers ab, baut dann das Chatfenster und gibt true zurück. Lässt der Browser dieses Ablegen nicht zu, öffnet sich das Tor nur für den laufenden Seitenaufruf; auf der nächsten Seite wartet der Lader wieder auf einwilligen() oder einen Klick auf den Auslöser. window.xicbot steht bereit, sobald der Lader gelaufen ist; ein Objekt, das Ihre Seite vorher unter diesem Namen angelegt hat, ersetzt er.
• Der Besucher hat bei einem früheren Besuch zugestimmt, und die 180 Tage sind noch nicht abgelaufen.
• Der Besucher hat auf der vorigen Seite im Chatfenster einen Vorschlag zum Ausfüllen eines Formulars bestätigt, siehe Formulare vorausfüllen.
• Der Besucher klickt auf den Auslöser. Wer ihn drückt, hat nach dem Chat gefragt; das Chatfenster wird dann auch ohne Zustimmung gebaut. Dabei ruft das Chatfenster die öffentliche Konfiguration des Assistenten ab. Ist Einwilligung vor dem ersten Gespräch eingeschaltet, beginnt ein Gespräch erst nach der Einwilligung im Fenster.

window.xicbot.stand() liefert den Zustand als Objekt: tor (Attribut gesetzt), einwilligung (Zustimmung liegt vor), gespraech (ein laufendes Gespräch ist bekannt) und offen (Chatfenster geöffnet).

Rangfolge zwischen Attribut und App

Der Lader richtet den Auslöser sofort nach den Attributen ein. Sobald das Chatfenster seine Konfiguration geladen hat, meldet es die Einstellungen aus der App, und der Lader übernimmt sie.

• Bleibt das Tor geschlossen oder scheitert das Laden der Konfiguration, gelten die Attribute weiter.
• Das Chatfenster fragt die Einstellungen erneut ab, wenn der Besucher es öffnet oder in den Browser-Tab zurückkehrt, höchstens einmal pro Minute. Eine Änderung in der App erreicht geöffnete Seiten so ohne Neuladen.

So wertet der Lader die Attribute aus

1. 1

   Schritt 1

   Eigenes Element finden

   Der Lader nimmt document.currentScript, sonst das erste script[data-xicbot] der Seite. Findet er keines, endet er.

2. 2

   Schritt 2

   Schlüssel lesen

   Ist data-xicbot leer, endet der Lader, ohne etwas anzuzeigen.

3. 3

   Schritt 3

   Nur einmal je Seite

   Ist auf der Seite schon ein Einbaucode gelaufen, endet dieser. Ab hier gilt die Seite als belegt, auch wenn ein späterer Schritt scheitert.

4. 4

   Schritt 4

   Basis bestimmen

   Aus data-basis oder dem Verzeichnis von src. Ohne gültige Basis mit http: oder https: endet der Lader.

5. 5

   Schritt 5

   Übrige Attribute lesen

   Schnittstelle, Farbe, Ecke, Sprache und Tor. Ungültige Werte bei Farbe, Ecke, Sprache und Tor zählen als nicht gesetzt; data-api übernimmt der Lader ungeprüft.

6. 6

   Schritt 6

   Auslöser einsetzen

   Der Auslöser erscheint sofort als Schaltfläche in Farbe und Ecke aus den Attributen, für Vorlesehilfen bezeichnet mit „Chat öffnen“, bei englischem Kürzel in data-sprache mit „Open chat“.

7. 7

   Schritt 7

   Chatfenster bauen

   Nach dem Ereignis load der Seite; mit Tor erst nach Zustimmung oder Übergabe. Ein Klick auf den Auslöser baut es sofort. Das Chatfenster kommt als rahmen.html von der Basis und läuft in einem eigenen, abgeschotteten Rahmen.

8. 8

   Schritt 8

   Einstellungen übernehmen

   Das Chatfenster lädt die Konfiguration des Assistenten, mit data-sprache als Sprachwunsch, und meldet Überschrift, Farbe, Ecke und Maße an den Lader. Ab dann gelten die Werte aus der App.

Fehlerbilder

Wie Sie prüfen, ob der Einbaucode auf Ihrer Seite angekommen ist, steht unter Einbindung prüfen; alle Meldungen des Chatfensters sammelt Meldungen.

Weiterlesen

• Widget einbauen: Einbauwege, eigener Pfad und Sicherheitsrichtlinie
• Einstellungen des Chatfensters: Farbe, Ecke, Abstände und Maße in der App
• Einwilligung und Besucherrechte: Tor im Chatfenster und Vorgabetext
• Formulare vorausfüllen: die Übergabe zwischen zwei Seiten
• JavaScript und Speicher: window.xicbot und was der Browser ablegt
• Darstellung und Bedienung: Auslöser, Tastatur und Bildschirmleser
• Gespräch im Widget: was Besucher im Chatfenster erleben

Häufige Fragen