WID/Current/Developer/GWCDeployment

• Developer

Here's how to instrument your website with Genesys Widgets.

Related documentation:

• How Widgets works

Use Genesys Widgets to add chat, callback, or Co-browse to your website, whether you use human agents alone or enhance their capabilities with Genesys chatbots or voicebots. These lightweight widgets provide either passive or predictive customer support—or both. All Genesys products currently support WebChat, while most support callback and Co-browse—but these are only the first available widgets that you can add to your website. Genesys will provide new types of widgets in future releases.

Genesys Widgets provide:

• Multi-language support
• Easy setup and configuration

You can also use the Widget Bus API to integrate Genesys Widgets with your own scripts, whether by invoking widget commands or receiving widget events. For example, you can launch widgets from your own scripts, or execute custom code when a widget is closed.

Note: Genesys Widgets require cookies to function, whether for saving UI state or for maintaining an active session with an agent as users navigate your website.

• Widgets API Reference

Audience

This document is for website developers who are in charge of website code. You must have knowledge of HTML, JavaScript, and CSS.

Cookies

Genesys Widgets uses cookies to store non-sensitive data in the browser. These cookies are used to restore a chat session, to track the state of the UI, to store a user's decision, and more. The end-user's browser must allow cookies for Genesys Widgets to operate properly.

Important

No personally identifiable information (PII) is ever stored in cookies, local storage, or session storage by Genesys Widgets

Sub-domains

Cookies can't normally be transferred between the subdomains of a website unless they are configured to do so. Genesys Widgets automatically detects the domain of the host site and configures all cookies so they can be transferred between subdomains. For example, you could start a chat on www.testsite.com and restore that chat session on store.testsite.com, support.testsite.com, or portal.testsite.com.

Cookie support in test environments

Genesys Widgets uses special cookies that persist across subdomains. This is a critical feature for plugins like WebChat that need to restore an active chat session while navigating around a website. The side effect of using this type of cookie is they won't work when using test environment domain names such as "localhost" or an IP address. You must use a fully-qualified domain name (FQDN) such as "localhost.com" or any other variant that can be identified as a domain name. Cookies will also fail to work if you run the test site as an HTML file path directly in the browser.

One workaround is to update your system's hosts file to create an FQDN alias for "localhost", your test environment's name, or an IP address.

Example

  127.0.0.1       localhost
  127.0.0.1       localhost.com

A fully-qualified domain name (FQDN) such as "localhost.com" or any other variant that can be identified as a domain name is not mandatory but recommended. These cookies will also work when using test environment domain names such as "localhost" or an IP address.

Deployment methods

Genesys supports two deployment methods:

• Lazy loading—Lazy loading breaks the JavaScript bundle into individual plugin files and loads them into the page only as you need them. This is the preferred method of deploying Genesys Widgets.

• All-in-one—The All-In-one method is the "classic" method of deploying Genesys Widgets. In this method, you have one JavaScript file and one CSS file that contain all plugins and resources.

Lazy-loading deployment

Files

• widgets/cxbus.min.js
• widgets/plugins/widgets-core.min.js
• widgets/plugins/*.*

You can use the following script to get started with lazy-loading deployment:

<script src="widgets/cxbus.min.js" onload="javascript:CXBus.configure({debug:true,pluginsPath:'build/plugins/'});CXBus.loadFile('path/to/widgets.config.js').done(function(){CXBus.loadPlugin('widgets-core')});"></script>

This script does the following:

1. Loads cxbus.min.js. This makes the global CXBus instance available.
2. Configures CXBus to turn on debug logging and set the path to the Widgets plugin folder.
3. Loads your configuration file, in this case, widgets.config.js. (If you use a configuration file, you must create it yourself.)
4. Loads widgets-core, the core Genesys Widgets library.

Use this script as a starting point and customize it as needed.

Remember that your configuration can be defined inline on the page or loaded in as a separate file (as shown in this script).

Important

Whichever method you choose, you must ensure your configuration is in the page before you load widgets-core. Otherwise, widgets-core cannot read the configuration.

Important

Refer to this article for help configuring Genesys Widgets.

On-Demand Lazy Loading

Genesys Widgets is designed to load plugins into the page on demand as you use the product. For example, if you call the command WebChat.open, CXBus fetches the webchat.min.js plugin from the plugins/ folder and loads it into the page. Any WebChat command triggers it to load. Likewise, WebChat calls WebChatService commands, thus CXBus loads webchatservice.min.js into the page as well.

Preloading Plugins

Sometimes you need to load your plugins on startup. For example, it's probably a good idea to have the SideBar plugin appear immediately, so the customer can use it right away. To do this, use the following JavaScript code:

    
    _genesys.widgets.main.preload = [

        "sidebar"
    ];

You can specify as many plugins as you want in the preload list. The plugins load in order after you load Widgets Core.

All plugin names are lower-case. Please refer to the file names in the plugins/ folder. For example, to preload webchat.min.js, specify webchat, the first part of the file name.

Some of your other plugins might also need to be preloaded.

All-in-one deployment

Files

• widgets/widgets.min.css
• widgets/widgets.min.js

You can use the following script to get started with all-in-one deployment:

<script src-"widgets/widgets.config.js"></script>
<script src="widgets/widgets.min.js"></script>
<link id="genesys-widgets-styles" data-origID="genesys-widgets-styles"  data-origID="genesys-widgets-styles"  data-origID="genesys-widgets-styles"  href="http://www.yourhost.com/path/to/widgets.min.css" type="text/css" rel="stylesheet"/>

First, you must define your configuration for Genesys Widgets. You can do this inline on the page by using a script tag, or you can store it in a separate file and load it in before widgets.min.js. In the script example above, we assume your configuration is stored in another file. You must create the widgets.config.js file for this script to function properly.

Important

Whichever method you choose, you must ensure your configuration is in the page before you load widgets.min.js. Otherwise, widgets.min.js cannot read the configuration.

Important

Refer to this article for help configuring Genesys Widgets.

Releases hosted on Genesys Content Delivery Network (CDN)

Genesys Widgets is now available over the Genesys Content Delivery Network (CDN), providing optimized load times and instant access to new releases.

<br class="mw_emptyline">https://app.genesys.cloud/widgets/<version>/<filenames><br class="mw_emptyline"></filenames></version>

Note that <version> and <filenames> are placeholders.

</filenames></version>

<filenames></filenames>

This value varies based on the deployment method you choose.

Tip

If the CDN URL you are trying to access is not found, either the release or the file you are looking for is not yet available.

<version></version>

version can take one of the following 3 values.

• 9.0 - (Major) - A version that is company-wide or
• 9.0.xxx - (Major).(Minor) - Minor version is product specific and is tied to each Widget’s iteration or
• 9.0.xxx.xx - (Major).(Minor).(Release candidate) - Specific release version

For all the available released versions, refer to the Widgets Release Notes.

Using Genesys Widgets CDN with versions

Starting in the 9.0.006.02 release, all of the released versions are accessible from the Genesys CDN URL. The sections below explain how to access the latest available released version or a specific released version using Genesys CDN.

To get the latest released version under the 9.0 family

https://app.genesys.cloud/widgets/9.0/widgets.min.js

To get the last available released version under a specific (Major).(Minor) version (this also includes any hot fixes for that release).

https://app.genesys.cloud/widgets/9.0.xxx/widgets.min.js
Example: https://app.genesys.cloud/widgets/9.0.006/widgets.min.js

To get a specific release/hot-fix version

https://app.genesys.cloud/widgets/9.0.xxx.xx/widgets.min.js
Example: https://app.genesys.cloud/widgets/9.0.006.02/widgets.min.js

Important

Release 9.0.006.02 and all subsequent versions are available in the CDN. However, some of the older versions of Genesys Widgets are not available there.

Versioning examples with scenarios

When a new release version comes out, it is available under all the 3 different CDN URLs below. In this example, if 9.0.006.01 is the first ever release announced, then it is available under the following CDN URLs.

• /9.0/
• /9.0.006/
• /9.0.006.01/

When 9.0.007.04 is released, it is available under /9.0/ but not under /9.0.006/ or /9.0.006.01/. Instead, /9.0.007/ and /9.0.007.04/ CDN URLs are created and this release is available under them:

• /9.0/
• /9.0.007/
• /9.0.007.04/

If a hot fix (such as 9.0.006.02) is released after 9.0.007.04 is released, then the hot fix is available under the following CDN URLs:

• /9.0.006/
• /9.0.006.02/

If a hot fix (such as 9.0.007.05) is released before announcing any new release, then it is available under the following CDN URLs:

• /9.0/
• /9.0.007/
• /9.0.007.05/

Deployment Methods

Lazy Loading

Recommended approach: When using the lazy loading method, the base Genesys CDN URL must be prefixed in the lazy loading deployment script. The <filenames> value is not needed in this scenario because they are auto-loaded from the base CDN configured. Here is what the deployment script looks like when using 9.0.006.02 release:

<script src="https://app.genesys.cloud/widgets/9.0.006.02/cxbus.min.js" onload="javascript:CXBus.configure({debug:true,pluginsPath:''https://app.genesys.cloud/widgets/9.0.006.02/plugins/''});CXBus.loadFile('path/to/widgets.config.js').done(function(){CXBus.loadPlugin('widgets-core')});"></script>

All-in-One

Legacy approach (deprecated): When using the all-in-one deployment method, the values are the files mentioned in the All-in-one section. For example, if you would like to use widgets.min.js and widgets.min.css under 9.0.006.02 release, CDN URLs will look like this:

<br class="mw_emptyline">https://app.genesys.cloud/widgets/9.0.006.02/widgets.min.js<br class="mw_emptyline">https://app.genesys.cloud/widgets/9.0.006.02/widgets.min.css<br class="mw_emptyline">

Important

Lazy loading is the recommended method for Widgets. The (All-in-one) method is deprecated.

For more information

The following articles can help you set your up widgets correctly:

• Supported browsers
• Cookies
• Configure widgets and services
• Localize widgets and services
• Customize appearance

And these articles provide important information on the background and usage of Genesys Widgets:

• How Genesys Widgets works
• The Widgets API Reference covers all of the commands and events for each widget, and discusses how to configure and localize each one.