Widget-Code-Snippet & einfache Query-Parameter

Sie können einen LoyJoy-KI-Agenten in Ihre Website integrieren, indem Sie das Code-Snippet aus dem Publish-Tab kopieren und in Ihre Website einfügen.

Widget-Code-Snippet

Das folgende Code-Snippet registriert die globale Funktion LoyJoy im DOM-window-Objekt und rendert den Chat. PROCESS_ID muss durch Ihre eigene ID aus dem LoyJoy-Manager ersetzt werden.

<script async defer src="https://stable.loyjoy.com/widget.js?process=PROCESS_ID"></script>

Alternativ können Sie das Widget auch als ES-Modul laden. Dies ist erforderlich, wenn Ihre Hosting-Website eine strenge Content Security Policy (CSP) verwendet, die das Laden externer Skripte ohne das Attribut type="module" nicht erlaubt.

<script src="https://stable.loyjoy.com/widget.esm.js?process=PROCESS_ID" type="module"></script>

Das ES-Modul kann auch mit einer Nonce geladen werden, was erforderlich ist, wenn Ihre Hosting-Website eine strenge Content Security Policy (CSP) verwendet, die eine Nonce zum Laden externer Skripte verlangt.

<script src="https://stable.loyjoy.com/widget.esm.js?process=PROCESS_ID" nonce="loyjoy-test-nonce" type="module"></script>

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).

Einfache Query-Parameter

Der größte Teil der Konfiguration des LoyJoy-KI-Agenten wird direkt in LoyJoy vorgenommen, nicht im Code-Snippet. Es kann jedoch Fälle geben, in denen Sie das konfigurierte Verhalten überschreiben möchten. In der Schweiz möchten Sie z. B. für einen Chat-Agenten erzwingen, dass auf einer bestimmten Webseite die Sprache DE verwendet wird, auf einer anderen FR.

Sie können Query-Parameter verwenden, um den LoyJoy-Chat-Agenten zu steuern. Die folgenden Parameter sind verfügbar:

Widget-Parameter	Wert	Funktion
cookie	true oder false	LoyJoy-Cookie aktivieren / deaktivieren (Local-Storage-Objekt loyjoy-chat)
debug	true	Debug-Modus aktivieren, der in die JavaScript-Konsole loggt
fullscreen	true	Erzwingt, dass der Chat-Messenger immer im Vollbildmodus ist, nicht nur auf Mobilgeräten, sondern auch auf Tablets usw.
iframe	true	Erzwingt, dass der Chat-Messenger in einem iframe statt in einer Web Component gerendert wird. 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.
locale	Z. B. de oder de-CH	Setzt das Gebietsschema für den Chat. Z. B. damit der Chat auf der französisch lokalisierten Website immer auf Französisch startet
message	Z. B. What+is+LoyJoy	Setzt die erste Nachricht des Chats, die automatisch vom Nutzer gesendet werden soll, wenn der Chat geöffnet wird. Kann z. B. für ein Suchformular auf der Hosting-Webseite verwendet werden, das beim Absenden den Chat mit der Suchanfrage auslösen soll.
open	true oder false	Chat-Messenger beim Laden der Seite öffnen / Chat-Messenger beim Laden der Seite nicht öffnen
process	<PROCESS_ID>	Chat-UI zu der angegebenen Prozess-ID leiten
reset	true oder false	Chat-Verlauf beim Laden der Seite löschen
restart	true oder false	KI-Agenten nach dem Laden der Seite neu starten
serviceWorker	true oder false	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 serviceWorker verwenden.
show	true oder false	LoyJoy-Chat beim Laden der Seite anzeigen oder ausblenden. Standardmäßig anzeigen.
suggestions	Z. B. What+is+LoyJoy	Setzt Vorschläge für Nutzernachrichten, die dem Nutzer beim Öffnen des Chats vorgeschlagen werden sollen.
view	<VIEW_ID>	Chat-UI zu der angegebenen Home-View-ID leiten

So hängen Sie Query-Parameter an die widget.js/widget.esm.js-URL an

Sie können Parameter im Website-Integrationsskript hinzufügen. Im Standard-Integrationscode-Snippet ist nur der erforderliche Parameter process angegeben.

<script async defer src="https://stable.loyjoy.com/widget.js?process=PROCESS_ID"></script>

Um z. B. den Parameter open hinzuzufügen, können Sie ihn mit & verketteten:

<script async defer src="https://stable.loyjoy.com/widget.js?process=PROCESS_ID&open=true"></script>

Um z. B. den Parameter locale hinzuzufügen, können Sie ihn mit & verketten:

<script async defer src="https://stable.loyjoy.com/widget.js?process=PROCESS_ID&locale=de"></script>

So fügen Sie frei gewählte Parameter hinzu

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

<script async defer src="https://stable.loyjoy.com/widget.js?process=PROCESS_ID&foo=bar"></script>

Beachten Sie, dass Parameter als case-insensitive Strings übergeben werden. foo=bar ist z. B. dasselbe wie FOO=bar oder fOo=bar. Die Parameterwerte sind jedoch case-sensitive. foo=bar ist z. B. nicht dasselbe wie foo=BAR.

So lauschen Sie auf Ereignisse

Der Chat emittiert Chat-Ereignisse wie open, close, sign-up, auf die Sie mit JavaScript-Ereignis-Listenern hören können. Der JavaScript-Ereignisname ist event und wird für jedes Chat-Ereignis ausgelöst. Das Argument e enthält das JavaScript-Ereignisobjekt, das wie in der CustomEvent-Spezifikation definiert eine detail-Eigenschaft enthält. Diese detail-Eigenschaft enthält den Chat-Ereignis-type wie open, close, sign-up sowie ein weiteres verschachteltes detail-Objekt mit Kontextinformationen des Chat-Ereignisses wie process_id und process_name.

<script id="my-widget" async defer src="https://stable.loyjoy.com/widget.js?process=PROCESS_ID"></script>

<script>
document.getElementById('my-widget').addEventListener('event', function (e) {
  console.warn(e.detail)
})
</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 e.detail.detail.url aussehen.

Die hier gewählte ID my-widget ist nur ein Beispiel; Sie können jede beliebige ID wählen. Dass alle Chat-Ereignisse unter einem einzigen JavaScript-Ereignis event emittiert werden, ist eine Designentscheidung, um die Anzahl der JavaScript-Ereignis-Listener gering zu halten. Sie können nach bestimmten Chat-Ereignissen filtern, indem Sie die Eigenschaft type im detail-Objekt prüfen.

Widget-Code-Snippet programmatisch erstellen

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.

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

var widgetScript = document.createElement('script')

widgetScript.async = true
widgetScript.defer = true
widgetScript.id = 'loyjoy-script'
widgetScript.src = 'https://stable.loyjoy.com/widget.js?process=' + PROCESS_ID
widgetScript.type = 'text/javascript'

document.body.appendChild(widgetScript)