Widget-Code-Snippet & erweiterte JavaScript-API

Für 99% der Integrationen kopieren Sie das Snippet aus dem Publish-Tab in Ihre Website, und fertig. Dieses Snippet wird mit async und defer geladen und rendert den Chat automatisch.

Diese Seite dokumentiert die JavaScript-API für die restlichen Fälle: einen manuellen boot-Aufruf, mit dem Sie Timing, Parameter und die Chat-Instanz aus Ihrem eigenen Code steuern. Da die API den Auto-Boot ersetzt, fügen Sie dem widget.js-Skript-Tag bei manueller Verwendung keine Attribute async oder defer hinzu; andernfalls könnte der boot-Aufruf ausgeführt werden, bevor widget.js geladen ist.

vorsicht

Verwenden Sie die JavaScript-API nur, wenn Sie JavaScript wirklich verstehen und den Chat programmatisch beeinflussen müssen, d. h. Sie sind ein Entwickler. Für die meisten Anwendungsfälle sollte stattdessen das Code-Snippet aus dem Publish-Tab ausreichen.

Gründe für die Verwendung der JavaScript-API anstelle des Code-Snippets aus dem Publish-Tab in Kombination mit Widget-Parameter können sein: (1) Aus Datenschutzgründen möchten Sie Parameter per JavaScript senden und nicht als Widget-Query-Parameter, (2) Sie möchten Callback-Parameter verwenden, die jedoch veraltet sind.

Das LoyJoy-Skript registriert die globale Funktion LoyJoy im DOM-window-Objekt und rendert den Chat nicht. Es verändert auch keine anderen Teile des DOM.

<script src="https://stable.loyjoy.com/widget.js"></script>

gefahr

Fügen Sie dem obigen Skript KEINE Attribute async oder defer hinzu, da der folgende Code sonst zufällig in eine Race Condition laufen kann.

gefahr

Wenn Ihre Website eine Content Security Policy (CSP) hat, stellen Sie bitte sicher, dass Sie die erforderlichen CSP-Header für LoyJoy hinzufügen. Weitere Informationen finden Sie unter Content Security Policy (CSP).

Rendern Sie dann mit dem LoyJoy-boot-Befehl die LoyJoy-DOM-Chat-Elemente in das DOM, als Overlay, wie im LoyJoy-Manager konfiguriert.

<script>
LoyJoy('boot', {
  process: PROCESS_ID
})
</script>

Alternativ können Sie den LoyJoy-Chat auch in den Seitenfluss rendern. Dazu fügen Sie ein Div mit der ID loyjoy-chat und einer von Ihnen definierten Größe ein und lassen LoyJoy automatisch LoyJoy-DOM-Elemente in das Div injizieren.

<div id="loyjoy-chat" style="width: 376px; height: 600px; line-height: 0; padding: 0"></div>

<script>
LoyJoy('boot', {
  process: PROCESS_ID
})
</script>

Mehrere KI-Agenten auf einer Seite

Es kann immer nur ein LoyJoy-Chat verwendet werden. Sie können jedoch die Befehle remove und boot verwenden, um auf derselben Seite zwischen verschiedenen KI-Agenten zu wechseln.

Der erste Chat kann über die Widget-Parametermethode oder wie oben beschrieben in die Seite integriert werden:

<script src="https://stable.loyjoy.com/widget.js"></script>

<script>
LoyJoy('boot', {
  process: PROCESS_ID
})
</script>

Um zwischen verschiedenen KI-Agenten zu wechseln, können Sie den ersten Chat entfernen und den zweiten Chat starten, z. B. wenn ein Button angeklickt wird:

<button onclick="LoyJoy('remove'); LoyJoy('boot', { process: OTHER_PROCESS_ID })">Switch to Agent 2</button>

Konfigurationsparameter

Optional können Sie dem Snippet Konfigurationsparameter hinzufügen. Standardmäßig sollten solche Parameter im LoyJoy-Manager konfiguriert werden; es kann jedoch Ausnahmen geben, die einen programmatischen Zugriff wie folgt erfordern:

Gebietsschema (Locale)

Ein String im Format <sprache-iso-6391>-<region-iso-31662> (Zweibuchstaben-Codes) überschreibt die Einstellungen des Kunden zu Sprache und Region. Diese Sprache und Region werden als Sprache und Region des Kunden gespeichert.

<script>
LoyJoy('boot', {
  locale: 'de-CH',
  process: PROCESS_ID
})
</script>

Öffnen (Open)

Weist den Chat an, den Chat-Messenger unabhängig von anderen Konfigurationseinstellungen beim Laden zu öffnen.

<script>
LoyJoy('boot', {
  open: true,
  process: PROCESS_ID
})
</script>

Vollbild (Fullscreen)

Weist den Chat an, die Chat-UI für alle Bildschirmgrößen im Vollbildmodus zu rendern, also nicht nur auf Mobilgeräten, sondern auch auf Tablets usw. Dies ist hilfreich, wenn Sie den Chat in einer App (Android oder iOS) in einem WebView rendern möchten.

<script>
LoyJoy('boot', {
  fullscreen: true,
  process: PROCESS_ID
})
</script>

Neustart (Restart)

Weist den Chat an, den Prozess nach (1) einem Seiten-Neu laden, (2) dem Aufruf LoyJoy('boot') oder (3) dem Sprung zu einem anderen KI-Agenten neu zu starten. Dies entfernt den Chatverlauf und startet den KI-Agenten von vorn. Im Gegensatz zu reset bleibt die Session erhalten, d. h. der Kunde bleibt angemeldet und Variablen werden nicht entfernt.

<script>
LoyJoy('boot', {
  process: PROCESS_ID,
  restart: true
})
</script>

Zurücksetzen (Reset)

Weist den Chat an, den Prozess nach einem Seiten-Neu laden (oder nach einem neuen LoyJoy('boot')) zurückzusetzen. Dies entfernt den Chatverlauf und startet den KI-Agenten von vorn.

<script>
LoyJoy('boot', {
  process: PROCESS_ID,
  reset: true
})
</script>

Anzeigen (Show)

Weist den Chat an, den Chat-Messenger beim Laden der Seite anzuzeigen oder auszublenden. Standardmäßig anzeigen. Dies ist nützlich, wenn Sie den Chat-Messenger erst nach einer Nutzeraktion anzeigen möchten, z. B. nach einem Button-Klick.

<script>
LoyJoy('boot', {
  process: PROCESS_ID,
  show: false
})
</script>

Standardmäßig speichert der Chat den Chatverlauf und die Kundenvariablen in einem Local-Storage-Objekt loyjoy-chat. Dieses Verhalten kann entweder (1) konfigurativ in einem KI-Agenten im LoyJoy-Manager oder (2) programmatisch über die JavaScript-API deaktiviert werden. Das folgende Snippet deaktiviert den Local Storage programmatisch, sodass der Chat nicht in das Local-Storage-Objekt loyjoy-chat schreibt.

<script>
LoyJoy('boot', {
  cookie: false,
  process: PROCESS_ID
})
</script>

Ereignis-Listener

Der Chat emittiert Chat-Ereignisse wie open, close, sign-up, auf die Sie mit einer oder mehreren Ereignis-Listener-Callback-Funktionen hören können. Das Argument type enthält den Ereignisnamen wie open, close, sign-up, das Argument detail enthält ein Kontextobjekt mit Chat-Ereignis-Kontextinformationen wie process_id und process_name.

<script>
LoyJoy('boot', {
  eventListeners: [function (type, detail) {}],
  process: PROCESS_ID
})
</script>

Zusätzlich enthält das detail-Objekt beim Ereignis link_clicked die Eigenschaft url mit der URL des geklickten Links. Der Zugriff auf die URL würde also wie detail.url aussehen.

Frei gewählte Parameter

Übergibt frei gewählte Parameter an den KI-Agenten, die im BPMN-Prozess mit BPMN-Bedingungen und anderen Ausdrücken ausgewertet werden können. Beispielsweise kann mit der GetParam-Funktion auf die Parameter zugegriffen werden. Um Parameterwerte in Variablen zu speichern, verwenden Sie die GetParam-Funktion als Quelle im Variablen-Modul.

<script>
LoyJoy('boot', {
  params: {
    foo: 'bar'
  },
  process: PROCESS_ID
})
</script>

Callback-Parameter

Veraltet

Callback-Parameter sind veraltet und werden in einem zukünftigen Release entfernt. Verwenden Sie stattdessen Frei gewählte Parameter, die auch programmatisch gesetzt werden können.

Ähnlich wie bei frei gewählten Parametern können Sie eine Callback-Funktion angeben, die dynamisch ausgewertet wird. Der Callback löst sich zu einem Parameter auf, der im BPMN-Prozess mit der GetParam-Funktion verwendet werden kann.

<script>
LoyJoy('boot', {
  callbacks: {
    foo: () => window.location.href
  },
  process: PROCESS_ID
})
</script>

Nachricht (Message)

Setzt die erste Nachricht des Chats, die automatisch im Namen des Nutzers gesendet wird, wenn der Chat geöffnet wird. Dies ist nützlich, um eine Website-Suchleiste in einen KI-beantworteten Chat zu verwandeln: Der Nutzer gibt eine Suchanfrage ein, der Chat öffnet sich mit dieser Anfrage als erste Nachricht, und ein LoyJoy-KI-Agent beantwortet sie statt einer klassischen Suchmaschine.

<script>
LoyJoy('boot', {
  message: 'What is LoyJoy?',
  process: PROCESS_ID
})
</script>

gefahr

Dieses Verhalten funktioniert nur, wenn der Chat so konfiguriert ist, dass er auf Nutzernachrichten antwortet, z. B. wenn im Prozess ein Message-Start-Ereignis verwendet wird oder wenn im Prozess ein KI-Agent-Modul mit dem Modus "Im KI-Agent-Modul bleiben und auf Nutzereingaben warten" verwendet wird. Andernfalls wird die Nachricht gesendet, aber keine Antwort vom KI-Agenten ausgelöst.

info

Sie können den message-Parameter verwenden, um eine benutzerdefinierte Suchleiste oder ein Formular auf Ihrer Website zu implementieren. Der Nutzer gibt eine Suchanfrage in eine Suchleiste ein, die dann den Chat mit der Anfrage des Nutzers öffnet. Auf diese Weise kann ein intelligenter KI-basierter LoyJoy-Agent Suchanfragen auf Ihren Websites beantworten, statt einer regulären Suchmaschine.

<form onsubmit="LoyJoy('boot', {process: '<PROCESS_ID>', message: this.query.value, open: true}); return false;">
  <input name="query" type="text" placeholder="Search...">
  <button type="submit">Search</button>
</form>

Eine vollständige Schritt-für-Schritt-Einrichtung mit Best Practices und Troubleshooting finden Sie im Guide Verwandeln Sie die Suchleiste Ihrer Website in einen KI-Agenten.

Vorschläge (Suggestions)

Setzt Vorschläge für Nutzernachrichten, die dem Nutzer beim Öffnen des Chats vorgeschlagen werden sollen. Die Vorschläge werden als Buttons im Chat-Messenger angezeigt. Die Vorschläge werden nicht angezeigt, wenn der Chat bereits einen Nachrichtenverlauf hat. Vorschläge sind z. B. nützlich für KI-Agenten, bei denen der Nutzer aus einer Liste von Vorschlägen wählen kann, die dann als Eingabe für das KI-Modell verwendet werden.

<script>
LoyJoy('boot', {
  process: PROCESS_ID,
  suggestions: ['What is LoyJoy?']
})
</script>

Service Worker für Push-Benachrichtigungen

Standardmäßig versucht LoyJoy nicht, den Service Worker von /service-worker.js zu laden, um z. B. Push-Benachrichtigungen zu aktivieren. Um LoyJoy das Laden des Service Workers zu ermöglichen, können Sie den Parameter push verwenden.

<script>
LoyJoy('boot', {
  process: PROCESS_ID,
  push: true
})
</script>

IFrame

Weist den Chat an, den Chat-Messenger in einem iframe statt in einer Web Component zu rendern. Nicht empfohlen, aber möglicherweise notwendig, wenn das JavaScript Ihrer Hosting-Webseite DOM-Elemente von LoyJoy-Web-Components verändert und Sie das nicht beheben können.

<script>
LoyJoy('boot', {
  process: PROCESS_ID,
  iframe: true
})
</script>

View

Weist den Chat an, die Chat-UI zu einer bestimmten View-ID zu leiten. Die Prozess-ID ist obligatorisch, auch wenn die View-ID angegeben ist.

<script>
LoyJoy('boot', {
  process: PROCESS_ID,
  view: VIEW_ID
})
</script>

Den Chat programmatisch steuern

Öffnen

LoyJoy('open') öffnet den Chat-Messenger. Das Gegenteil von LoyJoy('close').

<script>LoyJoy('open')</script>

Schließen

LoyJoy('close') schließt den Chat-Messenger. Das Gegenteil von LoyJoy('open').

<script>LoyJoy('close')</script>

Umschalten

LoyJoy('toggle') öffnet den Chat, wenn er geschlossen ist, und schließt ihn, wenn er geöffnet ist.

<script>LoyJoy('toggle')</script>

Entfernen

LoyJoy('remove') entfernt die LoyJoy-DOM-Elemente von der Seite.

<script>LoyJoy('remove')</script>

Ausblenden

LoyJoy('hide') blendet die Chat-Blase aus (display: none), ohne sie aus dem DOM zu entfernen. Das Gegenteil von LoyJoy('show').

<script>LoyJoy('hide')</script>

Anzeigen

LoyJoy('show') macht die Chat-Blase wieder sichtbar. Das Gegenteil von LoyJoy('hide').

<script>LoyJoy('show')</script>

Sie können das Widget-Code-Snippet auch programmatisch erstellen. Dies ist nützlich, wenn Sie die Widget-Parameter dynamisch ändern möchten, wenn Sie das Widget-Code-Snippet nur unter bestimmten Bedingungen laden möchten oder wenn Sie ein JavaScript-Framework wie React, Angular oder Vue.js verwenden.

Das Warten auf das onload-Ereignis des Widget-Skripts ist wichtig, weil das Widget-Skript die LoyJoy-JavaScript-API lädt und das LoyJoy-Objekt erst nach dem Laden des Widget-Skripts verfügbar ist.

document.getElementById('loyjoy-script')?.remove()

var widgetScript = document.createElement('script')

widgetScript.async = true
widgetScript.defer = true
widgetScript.id = 'loyjoy-script'
widgetScript.onload = function () {
  LoyJoy('boot', {
    process: PROCESS_ID
  })
}
widgetScript.src = 'https://stable.loyjoy.com/widget/' + PROCESS_ID
widgetScript.type = 'text/javascript'

document.body.appendChild(widgetScript)