Genesys Widgets Deployment Guide
This guide provides the steps required to instrument your website with Genesys Widgets.
Normally, cookies can not be transferred between sub-domains of a website unless they are configured to do so. Genesys Widgets automatically detects the domain of the host site and configures all cookies to be transferable between sub-domains. 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 sub-domains. 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.
127.0.0.1 localhost 127.0.0.1 localhost.com
Starting 9.0.004.03 version, 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.
How Can I Deploy Genesys Widgets?
We support two deployment methods:
Deploying Genesys Widgets (Lazy-Loading)
A good starting point is the following script:
This script does the following:
- Loads cxbus.min.js. This makes the global CXBus instance available.
- Configures CXBus to turn on debug logging and set the path to the Widgets plugin folder.
- Load your configuration file, widgets.config.js. (This is an imaginary file. You must create it).
- 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).
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.
In some cases, you might not want to load plugins on-demand, or the demand is to load them at startup. A good example is SideBar. You probably want this plugin to appear on the screen immediately so the customer can use it. To make this possible, you can specify which plugins you want to preload at startup in your configuration.
_genesys.widgets.main.preload = [ "sidebar" ];
You may 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.
You may find other plugins or features of plugins that necessitate preloading.
Deploying Genesys Widgets (All-in-One)
A good starting point is the following script:
<script src-"widgets/widgets.config.js"></script> <script src="widgets/widgets.min.js"></script> <link id="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.
Releases hosted on Genesys Content Delivery Network (CDN)
Genesys Widgets is now available over Genesys CDN, providing optimized load times and instant access to new releases.
Note that <version> and <filenames> are placeholders.
This value varies based on the deployment method you choose.
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 Genesys Widgets Releases notes.
Using Genesys Widgets CDN with versions
Starting in the 9.0.006.02 release, all 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
To get the last available released version under a specific (Major).(Minor) version (this also includes any hot fixes for that release).
To get a specific release/hot-fix version
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.
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:
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:
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:
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:
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: