JavaScript-Schnittstelle und Browserspeicher

Der Einbaucode legt auf Ihrer Seite das Objekt window.xicbot an. Mit seinen drei Methoden verbinden Sie ein eigenes Einwilligungsbanner mit dem Chatfenster. Diese Seite beschreibt die Methoden, die Nachrichten, die Lader und Chatfenster untereinander austauschen, und jeden Eintrag, den der Lader im Speicher Ihrer Seite ablegt.

Die Schnittstelle window.xicbot

Der Lader richtet window.xicbot ein, sobald er läuft. Mit dem Attribut defer aus dem Einbaucode ist das der Fall, wenn der Browser die Seite eingelesen hat. Fehlt data-xicbot oder ergibt die Basisadresse keine http- oder https-Adresse, entsteht kein Objekt. Steht der Einbaucode zweimal auf der Seite, bleibt der zweite ohne Wirkung. Seinen Griff erkennt der Lader an einer eigenen Kennzeichnung, nicht an den Methoden: Jedes Objekt, das Ihre Seite vorher unter diesem Namen angelegt hat, ersetzt er, auch einen Platzhalter mit einer Methode einwilligen. Hat Ihre Seite den Namen schreibgeschützt angelegt, bleibt ihr Objekt stehen, und das Chatfenster läuft ohne die Methoden des Laders.

einwilligen()

• Schreibt xicbot.einwilligung.<Schlüssel> mit dem Wert ja. Jeder Aufruf beginnt die Frist von 180 Tagen neu.
• Lädt das Chatfenster sofort im Hintergrund, auch wenn die Seite selbst noch lädt. Wartet gerade ein widerrufen() auf seine Antwort, lädt der Lader das neue Chatfenster direkt nach dem Abbau des alten. Geöffnet wird es über den Auslöser.
• Liefert true; die Zustimmung gilt ab dem Aufruf. Lässt der Browser das Ablegen nicht zu, gilt sie nur für diesen Seitenaufruf: stand().einwilligung ist dann true, auf der nächsten Seite aber false, bis Ihr Banner erneut einwilligen() aufruft.
• Trägt der Einbaucode data-einwilligung="erforderlich" (gesetzt durch Einwilligung vor dem ersten Gespräch), lädt der Lader das Fenster erst nach diesem Aufruf von sich aus. Ein Klick auf den Auslöser lädt es auch vorher.
• Die Zustimmung auf Ihrer Seite ersetzt die Einwilligung im Chatfenster nicht. Verlangt der Assistent sie, fragt das Fenster vor dem ersten Gespräch selbst danach.

widerrufen()

widerrufen() ist für den Moment gedacht, in dem ein Besucher seine Zustimmung in Ihrem Banner zurücknimmt.

• Entfernt sofort die Zustimmung, also xicbot.einwilligung.<Schlüssel> und eine Zustimmung, die nur für diesen Seitenaufruf galt.
• Nimmt eine Sprechblase der proaktiven Ansprache sofort von der Seite. Bis zum nächsten Seitenaufruf erscheint keine neue.
• Verwirft eine Formularübergabe von der vorigen Seite, die noch nicht eingetragen ist, und entfernt xicbot.formular.<Schlüssel>.
• Schließt das Chatfenster, falls es geöffnet ist.
• Ist das Chatfenster geladen, bittet der Lader es, die Einwilligung des Gesprächs beim Dienst zu widerrufen. Das Fenster nimmt denselben Weg wie sein Knopf Einwilligung widerrufen. Lädt das Fenster noch, fragt der Lader es nur, wenn eine Gesprächskennung gespeichert ist, und zwar sobald es bereit ist. Ohne Chatfenster geht keine Anfrage an den Dienst.
• Wartet höchstens fünf Sekunden auf die Antwort des Fensters. In dieser Zeit öffnet ein Klick auf den Auslöser nichts.
• Entfernt danach xicbot.gespraech.<Schlüssel> und xicbot.besuch.<Schlüssel> und nimmt das Chatfenster aus der Seite, auch wenn keine Antwort kam.
• Liefert ein Promise. Es löst mit true auf, wenn der Dienst den Widerruf bestätigt hat. false heißt, dass keine Bestätigung vorliegt, etwa weil kein Gespräch besteht, im Chatfenster keine Einwilligung erteilt wurde oder innerhalb der Frist keine Antwort kam. Ein zweiter Aufruf, während der erste noch wartet, liefert dasselbe Promise.

Nach dem Widerruf bleibt der Auslöser auf der Seite. Ein Klick darauf baut ein neues Chatfenster, das kein früheres Gespräch fortsetzt; verlangt der Assistent eine Einwilligung, fragt es erneut danach. Wie Besucher im Chatfenster selbst einwilligen, beschreibt Einwilligung und Besucherrechte.

stand()

Der Lader meldet Änderungen dieses Zustands nicht von sich aus. Braucht Ihr Banner ihn, etwa um den richtigen Knopf zu zeigen, rufen Sie stand() in dem Moment auf, in dem Sie ihn brauchen.

Beispiel: eigenes Einwilligungsbanner

Das Beispiel verbindet zwei Funktionen eines eigenen Banners mit dem Chatfenster. Die Werte im Einbaucode sind gekürzt; übernehmen Sie Ihren Einbaucode aus der App. Ein Skript, das vor dem Lader läuft, findet window.xicbot noch nicht. Rufen Sie die Methoden deshalb aus den Ereignissen Ihres Banners auf oder frühestens nach DOMContentLoaded.

<script src="https://cdn.xicbot.de/einbetten.js" data-xicbot="…" data-api="…" data-einwilligung="erforderlich" defer></script>
<script>
  // Besucher stimmt im Banner zu
  function allowChat() {
    if (window.xicbot) window.xicbot.einwilligen();
  }

  // Besucher nimmt die Zustimmung zurück
  function withdrawChat() {
    if (window.xicbot) window.xicbot.widerrufen();
  }
</script>

Nachrichten zwischen Seite und Chatfenster

Das Chatfenster läuft in einem iframe mit sandbox="allow-scripts allow-popups allow-popups-to-escape-sandbox" ohne allow-same-origin und mit referrerpolicy="no-referrer". Es hat damit einen undurchsichtigen Ursprung: es greift nicht auf Ihre Seite zu, Ihre Seite nicht auf das Fenster, und einen eigenen Speicher kann es nicht nutzen. Beim Aufbau gibt der Lader ihm im Fragment der Adresse rahmen.html#… mit, was es zum Start braucht: Schlüssel, Adresse der Schnittstelle, Ursprung Ihrer Seite, Platz, Sprache, Form und Breitenklasse der Schale, die gespeicherte Gesprächskennung und die Gestaltungsvorgaben der Seite. Das Fragment schickt der Browser an keinen Server. Alles Weitere läuft über postMessage; jede Nachricht ist ein Objekt mit xb: 1 und dem Feld art.

Vom Chatfenster an den Lader

Die Maße aus bereit und aendern prüft der Lader selbst noch einmal, bevor er sie übernimmt. Ein Wert außerhalb seiner Grenze bleibt unbeachtet, die übrigen Werte gelten trotzdem: abstand_x und abstand_y 0 bis 400 Pixel, breite 280 bis 720 Pixel, hoehe 320 bis 1200 Pixel, skalierung 80 bis 150 Prozent, rundung 0 bis 40 Pixel. Bis eine gültige Meldung eintrifft, gelten 20 Pixel Abstand, 384 Pixel Breite, 620 Pixel Höhe, 100 Prozent und 18 Pixel Rundung. Was die Maße auf der Seite bewirken, beschreibt Darstellung und Bedienung.

Vom Lader an das Chatfenster

Prüfungen auf beiden Seiten

• Der Lader nimmt nur Nachrichten an, die sein eigenes Chatfenster gesendet hat (geprüft über event.source), deren Ursprung null oder der Ursprung der Basisadresse ist und die xb: 1 tragen.
• Der Lader sendet mit dem Ziel *, weil das Chatfenster keinen benennbaren Ursprung hat. Solange kein Chatfenster besteht, sendet er nichts.
• Das Chatfenster nimmt nur Nachrichten seines Elternfensters an, deren Ursprung dem mitgegebenen Ursprung Ihrer Seite entspricht.
• Das Chatfenster sendet an den Ursprung Ihrer Seite, weil seine Nachrichten die Gesprächskennung tragen.
• Eine Nachricht mit unbekannter art bleibt auf beiden Seiten ohne Wirkung.

Einträge im Browserspeicher

Das Chatfenster kann wegen der Sandbox keinen eigenen Speicher nutzen. Was einen Seitenwechsel überdauern soll, legt deshalb der Lader im Speicher Ihrer Seite ab, also unter dem Ursprung Ihrer Website. <Schlüssel> steht für den Wert von data-xicbot im Einbaucode.

Die Frist der Gesprächskennung beginnt mit dem Gespräch und verlängert sich bei späteren Besuchen nicht; nach 30 Tagen beginnt der Besucher ein neues Gespräch. Der Besuchsmerker enthält nur ja und keine Kennung. Die Namen der Einträge enthalten den Schlüssel aus dem Einbaucode: Nach Neuen Schlüssel erzeugen und dem Austausch des Einbaucodes liest der Lader die Einträge unter dem alten Namen nicht mehr.

Speicherformat mit Frist

Jeder Eintrag des Laders im localStorage ist ein JSON-Objekt mit dem Wert und dem Ablaufzeitpunkt in Millisekunden seit dem 1. Januar 1970:

{"wert":"ja","bis":1805000000000}

• bis ist der Zeitpunkt des Schreibens plus Frist.
• Beim Lesen gilt ein Eintrag mit verstrichenem bis als nicht vorhanden, und der Lader entfernt ihn. Bis zum nächsten Lesen bleibt ein abgelaufener Eintrag im Speicher stehen.
• Ein Eintrag ohne dieses Format, etwa ein reiner Text aus einer älteren Fassung des Laders, gilt unverändert als Wert und erhält beim nächsten Schreiben eine Frist. Fehlt nur bis, läuft der Eintrag nicht ab.
• Schreibt der Lader einen leeren Wert, entfernt er den Eintrag.
• Fehler des Speichers, etwa ein gesperrter oder voller Speicher, fängt der Lader ab; der Eintrag fehlt dann.

Formularübergabe über einen Seitenwechsel

Liegt ein freigegebenes Formular auf einer festgelegten anderen Seite Ihrer Website, bringt der Lader die bestätigte Anweisung über einen Seitenwechsel dorthin. Die Werte stehen dabei nicht in der Adresse, sondern im sessionStorage des Tabs.

• Inhalt: aufruf, werkzeug, selektor, seite, bis zu 20 felder mit ihren Werten, absenden, bestaetigt und bis.
• Geschrieben wird nur für eine andere Seite desselben Ursprungs; direkt danach ruft der Lader die Zielseite auf. Liegt die Seite auf einer anderen Domain oder Subdomain, entsteht keine Übergabe.
• Der Lader liest den Eintrag beim nächsten Start in diesem Tab einmal und entfernt ihn sofort, auch wenn er ihn danach verwirft.
• Verworfen wird er, wenn er nicht lesbar ist, wenn bis verstrichen ist oder mehr als zwei Minuten in der Zukunft liegt.
• Ausgeführt wird er erst, wenn das Chatfenster die Einstellungen gemeldet hat, und nur auf der Seite, für die er geschrieben wurde und die für das Formular festgelegt ist.
• Ohne nutzbaren sessionStorage bleibt der Seitenwechsel aus; das Chatfenster erhält einen formular-bericht ohne eingetragene Felder.

Freigabe, Feldarten und das Eintragen selbst beschreibt Formulare vorausfüllen.

Wenn der Browser den Speicher sperrt

Sperrt der Browser den Speicher Ihrer Seite, beginnt jeder Seitenaufruf von vorn. Innerhalb eines Seitenaufrufs arbeitet das Chatfenster wie gewohnt, nach einem Seitenwechsel setzt es das Gespräch aber nicht fort. Die Regel Beim zweiten Besuch löst nicht aus. einwilligen() gilt dann für den laufenden Seitenaufruf: stand().einwilligung ist true, und mit data-einwilligung="erforderlich" lädt das Fenster sofort. Auf der nächsten Seite wartet der Lader wieder auf einwilligen() oder einen Klick auf den Auslöser.

Weiterlesen

• Widget einbauen: Einbaucode und die beiden Einbauwege.
• Script-Attribute: data-einwilligung und die übrigen Attribute des Einbaucodes.
• Einwilligung und Besucherrechte: Einwilligung im Fenster, Auskunft, Widerruf und Löschen.
• Proaktive Ansprache: Regeln wie Beim zweiten Besuch.
• Darstellung und Bedienung: Schale, Fokus und Tastatur.
• Schnittstelle des Widgets: die Wege, die das Chatfenster beim Dienst aufruft.

Häufige Fragen