JavaScript interface and browser storage

The embed code creates a window.xicbot object on your page. Its three methods let your own consent banner work with the chat window. Below you will find what each method does, which messages pass between the loader and the chat window, and every entry the loader keeps in the storage of your page.

The window.xicbot interface

The loader sets up window.xicbot as soon as it runs; with the defer attribute from the embed code, that happens once the browser has parsed the page. If data-xicbot is missing or the base address does not resolve to an http or https URL, no object is created. A second copy of the embed code on the same page has no effect. The loader recognises its handle by a marker of its own, not by its methods: any object your page created under that name beforehand is replaced, including a stub with an einwilligen method. If your page defined the name as read-only, its object stays and the chat window runs without the loader's methods.

einwilligen()

• Writes xicbot.einwilligung.<key> with the value ja. Each call restarts the 180-day period.
• Loads the chat window in the background straight away, even while the page itself is still loading. If a widerrufen() is still waiting for its reply, the loader loads the new chat window right after the old one has been removed. Visitors open it through the launcher.
• Returns true; consent applies from the moment of the call. If the browser refuses to store it, it applies to the current page view only: stand().einwilligung is true for now, but false on the next page until your banner calls einwilligen() again.
• If the embed code carries data-einwilligung="erforderlich", which Consent before the first conversation adds, the loader waits for this call before loading the window on its own. A click on the launcher loads it earlier.
• Consent given on your page does not replace the consent step in the chat window. If the assistant requires it, the window still asks before the first conversation.

widerrufen()

Call widerrufen() when a visitor takes back their consent in your banner.

• Removes consent at once, that is xicbot.einwilligung.<key> and any consent that applied to the current page view only.
• Takes a speech bubble from proactive outreach off the page at once. No new one appears until the next page view.
• Discards a form handover from the previous page that has not been filled in yet and removes xicbot.formular.<key>.
• Closes the chat window if it is open.
• If the chat window is loaded, the loader asks it to withdraw the conversation's consent with the service. The window takes the same route as its Withdraw consent button. If the window is still loading, the loader only asks it when a conversation ID is stored, as soon as the window is ready. Without a chat window, no request goes to the service.
• Waits no more than five seconds for the window's reply. During that time a click on the launcher opens nothing.
• Then removes xicbot.gespraech.<key> and xicbot.besuch.<key> and takes the chat window out of the page, even if no reply arrived.
• Returns a promise. It resolves to true if the service confirmed the withdrawal. false means there is no confirmation, for example because there is no conversation, no consent was given in the chat window, or no reply came within the time limit. A second call while the first is still waiting returns the same promise.

After the withdrawal the launcher stays on the page. Clicking it builds a fresh chat window that does not resume the earlier conversation; if the assistant requires consent, the window asks for it again. How visitors give consent inside the chat window is covered in Consent and visitor rights.

stand()

The loader does not announce changes to this state. If your banner needs it, for example to show the right button, call stand() at the moment you need the answer.

Example: your own consent banner

The example connects two functions of your own banner to the chat window. The values in the embed code are shortened; copy your own embed code from the app. A script that runs before the loader will not find window.xicbot yet, so call the methods from your banner's events or after DOMContentLoaded at the earliest.

<script src="https://cdn.xicbot.de/einbetten.js" data-xicbot="…" data-api="…" data-einwilligung="erforderlich" defer></script>
<script>
  // Visitor agrees in the banner
  function allowChat() {
    if (window.xicbot) window.xicbot.einwilligen();
  }

  // Visitor takes consent back
  function withdrawChat() {
    if (window.xicbot) window.xicbot.widerrufen();
  }
</script>

Messages between page and chat window

The chat window runs in an iframe with sandbox="allow-scripts allow-popups allow-popups-to-escape-sandbox", without allow-same-origin and with referrerpolicy="no-referrer". That gives it an opaque origin: it cannot reach into your page, your page cannot reach into it, and it cannot use storage of its own. When building it, the loader passes everything the window needs to start in the URL fragment rahmen.html#…: key, API address, the origin of your page, position, language, shape and width class of the shell, the stored conversation ID and the styling defaults read from the page. Browsers do not send the fragment to any server. Everything after that goes through postMessage; each message is an object with xb: 1 and an art field.

From the chat window to the loader

The loader checks the dimensions from bereit and aendern again before applying them. A value outside its range is ignored while the remaining values still apply: abstand_x and abstand_y 0 to 400 pixels, breite 280 to 720 pixels, hoehe 320 to 1200 pixels, skalierung 80 to 150 percent, rundung 0 to 40 pixels. Until a valid message arrives, the loader uses a 20-pixel offset, a width of 384 and a height of 620 pixels, 100 percent scale and an 18-pixel radius. How these dimensions play out on the page is covered in Appearance and accessibility.

From the loader to the chat window

Checks on both sides

• The loader only accepts messages sent by its own chat window (checked via event.source), whose origin is null or the origin of the base address, and which carry xb: 1.
• The loader posts with the target * because the chat window has no origin that could be named. As long as there is no chat window, it sends nothing.
• The chat window only accepts messages from its parent window whose origin equals the page origin it was given at start.
• The chat window posts to the origin of your page, since its messages carry the conversation ID.
• A message with an unknown art has no effect on either side.

Entries in browser storage

Because of the sandbox, the chat window cannot use storage of its own. Anything that has to survive a page change is therefore kept by the loader in the storage of your page, under the origin of your website. <key> stands for the value of data-xicbot in the embed code.

The expiry of the conversation ID runs from the start of the conversation and is not extended by later visits; after 30 days the visitor starts a new conversation. The visit marker holds only ja and no identifier. Entry names contain the key from the embed code, so after Generate a new key and replacing the embed code, the loader no longer reads the entries stored under the old name.

Storage format with expiry

Each entry the loader writes to localStorage is a JSON object holding the value and the expiry time in milliseconds since 1 January 1970:

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

• bis is the time of writing plus the expiry period.
• On reading, an entry whose bis has passed counts as absent and the loader deletes it. Until it is read again, an expired entry stays in storage.
• An entry in another format, such as plain text from an older loader version, is used as the value as it stands and gets an expiry on the next write. If only bis is missing, the entry does not expire.
• Writing an empty value deletes the entry.
• Storage errors, for instance blocked or full storage, are caught by the loader; the entry is then simply missing.

Form handover across a page change

If an approved form is set to live on another page of your website, the loader carries the confirmed instruction across the page change. The values do not travel in the URL but in the sessionStorage of the tab.

• Content: aufruf, werkzeug, selektor, seite, up to 20 felder with their values, absenden, bestaetigt and bis.
• It is only written for another page of the same origin, and the loader navigates to that page right afterwards. If the page is on a different domain or subdomain, no handover is created.
• On its next start in this tab, the loader reads the entry once and deletes it straight away, even if it then discards it.
• It is discarded if it cannot be read, if bis has passed or if it lies more than two minutes in the future.
• It is only carried out once the chat window has reported the settings, and only on the page it was written for, which must also be the page set for the form.
• Without usable sessionStorage the page change does not happen; the chat window receives a formular-bericht with no fields filled.

Approval, field types and the filling itself are covered in Form prefill.

When the browser blocks storage

If the browser blocks storage for your page, every page view starts from scratch. Within a single page view the chat window works as usual, but it does not resume the conversation after a page change. The On a second visit rule does not fire. einwilligen() then applies to the current page view: stand().einwilligung is true, and with data-einwilligung="erforderlich" the window loads straight away. On the next page the loader waits again for einwilligen() or a click on the launcher.

Further reading

• Embed the widget: the embed code and both ways of embedding it.
• Script attributes: data-einwilligung and the other attributes of the embed code.
• Consent and visitor rights: consent in the window, access, withdrawal and deletion.
• Proactive outreach: rules such as On a second visit.
• Appearance and accessibility: shell, focus and keyboard.
• Widget API endpoints: the endpoints the chat window calls on the service.

Frequent questions