Jump to: navigation, search

Configuring the Instrumentation Script

The Tracker Application instrumentation script is a small piece of JavaScript code that you paste into your website to enable Web Engagement functionality. If you plan to use the Genesys Chat Widget or other Genesys Widgets, you must create your instrumentation using Genesys Widgets, in which case the Tracker Application provides built-in integration with Genesys Widgets.

Important
The rest of this article describes how to configure your instrumentation script. However, you must only use this technique if you are going to use the Tracker Application with "legacy" GWE Widgets. If you are using Genesys Widgets you must use the appropriate instrumentation script.

You typically add the instrumentation script to your site when you are ready to move your application to a production environment with a Web Engagement cluster. If you are working in a standalone deployment in a lab environment, you can use the default ZAP Proxy implementation to inject the instrumentation script into the pages of your web site on the fly.

You can complete the steps on this page to do the following:

  1. Copy-paste basic instrumentation script.
  2. Configure the script, if necessary for your solution.
  3. Add the script to your website.

Copy-paste the Instrumentation Script

Important
This section is only for use in creating a standalone Tracker application that uses the native Web Engagement widgets. If you are using Genesys Widgets you must use the appropriate instrumentation script.

Start

  1. Go to one of the chapters with the instrumentation script (such as Basic Instrumentation, Basic Configuration with the Chat JS Application, and Advanced Configuration chapters).
  2. Copy instrumentation script and save it on your file system.
  3. In the saved script:
    • Replace server:port with HTTP entry point to the Web Engagement Cluster (either Load Balancer or direct address of direct address of one of the servers). For example, http://myserver.genesys.com:9081
    • Replace server:securePort with HTTPS entry point to the Web Engagement Cluster (either Load Balancer or direct address of direct address of one of the servers). For example, https://myserver.genesys.com:3214
    • Replace GPE.min.js with other supported type of Tracker JS Application, if you need it

End

Next Steps

Configuring the Instrumentation Script

The Tracker Application activates the Monitoring and Notification functions in Genesys Web Engagement by inserting the GTCJ.min.js package into the page. This package includes jQuery, the Monitoring Agent, and the Notification Agent. The Tracker Application actually provides several packages that contain different functions and libraries. You can use these packages to enable different Web Engagement functionality on your website.

The table below shows the packages, in minified form, that are included with the Tracker Application.

Script jQuery Monitoring Agent Notification Agent Chat
GT.min.js no yes no no
GTJ.min.js yes yes no no
GTC.min.js no yes yes no
GTCJ.min.js yes yes yes no
GPE.min.js yes yes yes yes
Important
You must not make any changes to the scripts listed in the table above; any modifications will not be supported by Genesys. Please refer to the Genesys Web Engagement API Reference for information about the supported APIs.

The Tracker Application instrumentation script consists of two parts: configuration and script loader.

Script Loader

To load the Tracker Application, you just need to include the JavaScript in your web pages. This asynchronously loads the application, which means that it won't block other elements on your web pages from loading.

One solution for loading the script could be: 

(function(gpe) {
    if (document.getElementById(gpe)) return;
    var s = document.createElement('script'); s.id = gpe;
    s.src = ('https:' == document.location.protocol ? 'https://<Web Engagement Server>:<Secure Web Engagement Server Port>':
        'http://<Web Engagement Server>:<Web Engagement Server Port>') + '/server/resources/js/build/GTCJ.min.js';
    (document.getElementsByTagName('head')[0] || document.body).appendChild(s);
})('_gt');
Important
The script above uses the default "_gt" as the configuration global variable.

For more information about best practices for loading the script, see Adding the Instrumentation Script to Your Website.

Configuration

By default, the Tracker Application script uses the "_gt" global variable (you can change this in the script loader — see Changing the Global Configuration Variable for details) that must be initialized before the script loader is actually added to the page.

The following configuration options are available in the script:

Parameter Required Type Default Value Description Example value
cookieExpires no number Base expiration value is 3 years. With this option you are able to shift expiration, in seconds. Note, that this options does not overwrite expiration, it is shift it to base 3 years value. Set expiration shifted to 17 seconds : "17", cookies will be set with 3 years + 17 seconds expiration time

Set expiration to absolute value 60 seconds : "-94607940", which is -3*365*24*60*60+60 seconds

debug no boolean false Show Monitoring Agent debug information in the browser console. true
debugCometD no boolean false Show CometD debug information in the browser console. true
disableAutoSystemEvents no boolean false Disable automatic sending of the following system events: VisitStarted, PageEntered, PageExited. true
disableIntegrationAgent no boolean false Supported starting with version 8.5.100.17. Disables the possibility of communication between TrackerJS script and other browser windows.
Note: InTools functionality will not work in this case. 		true
disableWebSockets 		no boolean false Disable websockets transport for the notification agent. By default, the Notification Agent uses websocket transport when it is possible. Make sure that your load balancers support websocket connections; otherwise, disable it — Disabling Websocket CometD Transport. true
domainName no string Second-level domain (SLD). Name of the domain where the cookie is stored. For the domain sub.genesys.com, the second-level domain is genesys.com
dslResource no string - The DSL resource location. If dslResource is not defined, then the DSL is not loaded. http://genesyslab.com:9081/server/api/resources/v1/dsl/domain-model.xml
httpEndpoint yes (if "httpsEndpoint" is undefined) string - The URL of the Web Engagement Server. http://genesyslab.com:9081
httpsEndpoint yes (if "httpEndpoint" is undefined) string - The secure URL of the Web Engagement Server. https://genesyslab.com:8443
languageCode 		no string en-US Localization tag for language and region. Used for categorization. en-US
name no string - Name of the application. This option is a part of the cloud multi-tenant, multi-domain system. Currently not used. genesyslab
page no object - Sets the page configuration for events. In some cases, you might want to set a parameter and have the value persist across multiple push events. To override the page url of each event with your own custom url, you can either set the new url on each push command, or you can use current option. Note: This option should only be used with Single Page Applications. 
_gt.push(['config', {<br class="mw_emptyline">    page: {<br class="mw_emptyline">        url: 'http://example.com/my-page-url?id=1',        title: 'My Page Title'<br class="mw_emptyline">    }<br class="mw_emptyline">}]);
page:title no string document.title The title of the current page (this title is used in the PageEntered event by default).  
page:url no string window.location.href The URL of the current page. This option is used for all subsequent events sent from the page.  
preventIframeMonitoring no boolean false If preventIframeMonitoring is true, the Monitoring Agent does not generate system and business events if the agent is loaded in an iframe. See preventIframeMonitoring for details. true
skipCategories no boolean false Do not include category information with server response to initial page request. This option can be used when a website does not need to use categories. true


Basic Configuration

Basic configuration is the default Tracking functionality: 

var _gt = window._gt || [];
_gt.push(['config', {
        dslResource:    ('https:' == document.location.protocol ? 'https://server:securePort' :
                        'http://server:port') + '/server/api/resources/v1/dsl/domain-model.xml',
        httpEndpoint: 'http://server:port',
        httpsEndpoint: 'https://server:securePort'     
}]);
              
(function(gpe) {
        if (document.getElementById(gpe)) return;
        var s = document.createElement('script'); s.id = gpe; 
        s.src = (   'https:' == document.location.protocol ? 'https://server:securePort' :
                    'http://server:port') + '/server/resources/js/build/GTCJ.min.js';    
        (document.getElementsByTagName('head')[0] || document.body).appendChild(s);
})('_gt');

This snippet represents the minimum configuration needed to track a page asynchronously. The _gt (Genesys Tracker) object is what makes the asynchronous syntax possible. It acts as a queue, which is a first-in, first-out data structure that collects API calls until Genesys Web Engagement is ready to execute them. To add something to the queue, you can use the _gt.push method. See the Monitoring JS API for more information.

Basic Configuration with the Chat JS Application

To add chat functionality to the basic configuration by loading the Chat JS Application, your script should now look something like this: 

var _gt = window._gt || [];
_gt.push(['config', {
    dslResource:    ('https:' == document.location.protocol ? 'https://server:securePort' :
                    'http://server:port') + '/server/api/resources/v1/dsl/domain-model.xml',
    httpEndpoint: 'http://server:port',
    httpsEndpoint: 'https://server:securePort' 
    }]);
     
var _gwc = {
    widgetUrl: ('https:' == document.location.protocol ? 'https://server:securePort' :
                    'http://server:port') + '/server/api/resources/v1/chatWidget.html'
};
         
(function(gpe) {
    if (document.getElementById(gpe)) return;
    var s = document.createElement('script'); s.id = gpe;  
    s.src = (   'https:' == document.location.protocol ? 'https://server:securePort' :
                'http://server:port') + '/server/resources/js/build/GPE.min.js';         
    (document.getElementsByTagName('head')[0] || document.body).appendChild(s);
})('_gt');

Advanced Configuration

The snippet below shows the instrumentation script with extended configuration (refer to the configuration options table for details): 

var _gt = _gt || [];
_gt.push(['config', {
    name:             'demo',
    domainName:       'localhost',
    languageCode:     'en-US',
    dslResource:    ('https:' == document.location.protocol ? 'https://server:securePort':
        'http://server:port') + '/server/api/resources/v1/dsl/domain-model.xml',
    httpEndpoint: 'http://server:port',
    httpsEndpoint: 'https://server:securePort'
    languageCode:     'en-US',
    debug:            true,
    debugCometD:       true,
    preventIframeMonitoring: true,
}]);
     
(function(gpe) {
    if (document.getElementById(gpe)) return;
    var s = document.createElement('script'); s.id = gpe;
    s.src = (   'https:' == document.location.protocol ? 'https://server:securePort' :
        'http://server:port') + '/server/resources/js/build/GTCJ.min.js';
    (document.getElementsByTagName('head')[0] || document.body).appendChild(s);
})('_gt');

preventIframeMonitoring

Some websites have iframe (or frame) elements on the page. If a website is instrumented so that the Monitoring Agent is loaded on all web pages (even in an iframe), the agent generates events for all pages, including iframes. For example, this means that a page with an iframe generates two PageEntered events, one for the main page and one for the iframe.

To prevent this, you can use a special initialization parameter, preventIframeMonitoring. This parameter is optional and has a default value of false. If true, the Monitoring Agent does not generate system and business events if it is loaded in an iframe.

Changing the Global Configuration Variable

You can change the global configuration variable for the Tracker Application by using the data-gpe-var attribute. For example: 

(function(gpe) {
    if (document.getElementById(gpe)) return;
    var s = document.createElement('script'); s.id = gpe;
    s.src = ('https:' == document.location.protocol ? 'https://server:securePort':
        'http://server:port') + '/server/resources/js/build/GTCJ.min.js';
    s.setAttribute('data-gpe-var', gpe); // set global variable name for Tracker Application
    (document.getElementsByTagName('head')[0] || document.body).appendChild(s);
})('_myVariable');

In the example above global variable "_myVariable" is now used instead of "_gt".

Providing an External jQuery Library

If you already have a jQuery library on your website, you can reduce the size of the Genesys Web Engagement JavaScript files by using the packages without jQuery (GT.min.js or GTC.min.js). In this case, make sure that jQuery is available on your site through the global variable window.jQuery and that jQuery is loaded before the Genesys Tracker Application.

If the jQuery library is present on some pages and not others, you must insert the following snippet of code before the instrumentation script: 

<script>
window.jQuery || document.write("<script src='http://code.jquery.com/jquery-1.11.0.min.js'>\x3C/script>")
</script>

Disabling Websocket CometD Transport

To disable websockets CometD transport, use the transports option in your instrumentation script: 

_gt.push(['config', {   
    disableWebSockets: true,
    ....
}]);

Next Steps

Adding the Instrumentation Script to Your Website

To add the instrumentation script, you need to have access to the source code for your website. If you already have an older version of the instrumentation script on your site, make sure you remove it from each page before you add the new one. If you have customizations you want to add back to your pages after you add the new snippet, you can use a text or HTML editor to open and save a copy of each file.

The instrumentation script is loaded asynchronously. One of the main advantages of the asynchronous script is that you can position it at the top of the HTML document. This increases the likelihood that the tracking beacon will be sent before the user leaves the page. Genesys recommends placing the script at the bottom of the <head> section for best performance.

For the best performance across all browsers, Genesys recommends that you position other scripts in your site either before the instrumentation script in the <head> section or after both the instrumentation script and all page content (at the bottom of the HTML body).

Make sure that the document type is defined in the head of each of your web pages. If it is not defined, Genesys Web Engagement will not work on your website. 

<!DOCTYPE html>

Prerequisites

Start

  1. Select and copy the script from your file.
  2. Paste the script at the bottom of the <head> section of your web pages:
    • You can do this manually on each web page that you want to monitor.
    • You can do this in the header template of your website, if you have one.
  3. If your website includes additional scripts, do one of the following to optimize performance:
    • Place your scripts above the instrumentation script in the <head> section.
    • Make sure your scripts are located after the webpage contents (at the bottom of the body section).

End

Next Steps

This page was last edited on April 15, 2021, at 18:26.
Comments or questions about this documentation? Contact us for support!