Widget Code Snippet & Simple Query Parameters

You can integrate a LoyJoy experience into your website by copying the code snippet from the Publish tab and pasting it into your website.

The following code snippets registers the global function LoyJoy in the DOM window object and renders the chat. PROCESS_ID must be replaced with your own ID from the LoyJoy manager.

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

Simple Query Parameters

Most of the configuration of the LoyJoy experience is done in LoyJoy directly, not in the code snippet. However, there might be cases where you want to override the configured behavior. E.g. in Switzerland you might want to enforce for a chat experience, that on a specific webpage language DE should be used, and FR on another.

You can use query parameters to control the LoyJoy chat experience. The following parameters are available:

Widget-parameter	Value	Function
`cookie`	`true` or `false`	Enable / disable the LoyJoy cookie (local storage object `loyjoy-chat`)
`debug`	`true`	Enable debug mode that logs to JavaScript console
`fullscreen`	`true`	Force that the chat messenger is always in fullscreen, not only on mobile but also on tablets etc.
`iframe`	`true`	Force that the chat messenger renders in an iframe instead of a web component. Not recommended, however might be necessary if JavaScript of your hosting web page modifies DOM elements of LoyJoy web components and you cannot fix this.
`locale`	E.g. `de` or `de-CH`	Set the locale for the chat. For example to have the chat always start in French on the French localized website
`open`	`true` or `false`	Open chat messenger on page load / Do not open chat messenger on page load
`reset`	`true` or `false`	Delete chat history on page load
`restart`	`true` or `false`	Start experience again after page load
`serviceWorkerDisable`	`true` or `false`	By default LoyJoy will try to load the service worker from /service-worker.js to enable e.g. push notifications. To prevent LoyJoy from trying to load the service worker you can use the parameter serviceWorkerDisable. This is useful, if there is no /service-worker.js present and you want to prevent an HTTP 404 error.
`show`	`true` or `false`	Hide LoyJoy chat on page

How to Append Query Parameters to the `widget.js` URL

You can add parameters in the website integration script. In the standard integration code snippet only the required process parameter is given.

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

To add e.g. the open parameter, you can chain it by using &:

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

To add e.g. the locale parameter, you can chain it by using &:

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

How to Add Freely Selected Parameters

You can pass freely selected parameters to the experience that can be evaluated in the BPMN process using BPMN conditions and other expressions. The parameters can be accessed with the GetParam function in LoyJoy.

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

How to Listen for Events

The chat emits chat events such as open, close, sign-up that you can listen for with JavaScript event listeners. The JavaScript event name is event and will be triggered for any chat event. The argument e contains the JavaScript event object, which as defined in the CustomEvent specification contains a detail property. This detail property contains the chat event type such as open, close, sign-up and another nested detail object with chat event context information such as process_id and 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>

The ID my-widget chosen here is just an example and you can choose any ID you like. Emitting all chat events under a single JavaScript event event is a design decision to keep the number of JavaScript event listeners low. You can filter for specific chat events by checking the type property in the detail object.

You can also create the widget code snippet programmatically. This is useful if you want to dynamically change the widget parameters, if you want to load the widget code snippet only under certain conditions or if you are using a JavaScript framework like React, Angular or Vue.js.

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)

Widget Code Snippet & Simple Query Parameters