HELP FILE

Google Analytics Integration with BoldChat Layered Windows

Integrate Google Analytics with Layered Chat Windows, track visitor interactions as Analytics events and gain accurate insight into visitor behavior.

As dynamic elements on a website, Layered Chat Windows require a mechanism to cache tracking information and provide accurate results. This step-by-step guide describes a Local Storage implementation that allows data to persist when a chat session is interrupted.

Note: Interruptions usually happen in the following circumstances:
  • Visitor navigates to a new page under the same domain.
  • Connection dropout occurs.
  • Visitor browses multiple pages on the website simultaneously.
  • Visitor closes and re-opens or reloads a page.
The Local Storage technology is compatible with the following browsers:

See the WebStorage article on Wikipedia for details.

Note: For information about Google Analytics and data residency, see Data Residency Options.

Prerequisites

All pages on your site must either include or reference the following code snippets:
Tip: Streamline code snippet delivery via Google Tag Manager.


Code locations in BoldChat for Task One, Task Two and Task Three.

Task One: Configure the Chat Frame Javascript Include

Add a Chat Frame Javascript Include to the Chat Window Definition deployed to your site. This code intercepts chat events and passes them to the chat window via the postMessage method.

Note: This is the method how Layered Chat internal events are already communicated between the Chat Frame (hosted on livechat[-eu].boldchat.com) and the Chat Window (the container, hosted on the same website that the visitor is browsing). Using this method we are basically extending the existing Chat communications methods by adding a new key ( gacomm) for these custom messages.

try {
  function sendtxt(txt) {
    var message = JSON.stringify({
      gacomm: txt
    });
    parent.parent.postMessage(message, "*");
  }
  sendtxt(bcConfig.chatOptions.page);
  window.console && console.log("Sent Chat Window Page: " + bcConfig.chatOptions.page);
  if (bcConfig.chatOptions.page == "chat") {
    var _tEvents = {
        "new-message": "bc_newHistoryMessageCallback"
      },
      _tFunction = function(i, type, fName) {
        if ((i == "new-message") && (bc.$("#bc-status-prompt").prev().hasClass("bc-operator-message"))) {
          sendtxt("answered");
        }
      }
  }
  for (var i in _tEvents) {
    window[_tEvents[i]] = _tFunction.bind(window, i, "function", _tEvents[i]);
  }
} catch (err) {
  window.console && console.error(err);
}
Tip: Looking for a quick solution? Download the full code here.

Task Two: Configure the Chat Window Javascript Include

Add a Chat Window Javascript Include to the Chat Window Definition deployed to your site.

Note: It is recommended to encapsulate the code snippets in this section in a try/catch phrase to detect potential issues later on.
  1. Open a try/catch and import inline the LS CACHE minified script.

    Note: The Chat Window Javascript Include code depends on the LS CACHE library to manage the expiration time of Local Storage entities. We strongly recommend that you include the following minified code on your website, instead of referencing the library:
    try {
    
    /**
    * lscache library
    * Copyright (c) 2011, Pamela Fox
    *
    * Licensed under the Apache License, Version 2.0 (the "License");
    * you may not use this file except in compliance with the License.
    * You may obtain a copy of the License at
    *
    * http://www.apache.org/licenses/LICENSE-2.0
    *
    * Unless required by applicable law or agreed to in writing, software
    * distributed under the License is distributed on an "AS IS" BASIS,
    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    * See the License for the specific language governing permissions and
    * limitations under the License.
    **/
    
    !function(a,b){"function"==typeof define&&define.amd?define([],b):"undefined"!=typeof module&&module.exports?module.exports=b():a.lscache=b()}(this,function(){function a(){var a="__lscachetest__",c=a;if(void 0!==m)return m;try{g(a,c),h(a),m=!0}catch(d){m=b(d)?!0:!1}return m}function b(a){return a&&"QUOTA_EXCEEDED_ERR"===a.name||"NS_ERROR_DOM_QUOTA_REACHED"===a.name||"QuotaExceededError"===a.name?!0:!1}function c(){return void 0===n&&(n=null!=window.JSON),n}function d(a){return a+p}function e(){return Math.floor((new Date).getTime()/r)}function f(a){return localStorage.getItem(o+t+a)}function g(a,b){localStorage.removeItem(o+t+a),localStorage.setItem(o+t+a,b)}function h(a){localStorage.removeItem(o+t+a)}function i(a){for(var b=new RegExp("^"+o+t+"(.*)"),c=localStorage.length-1;c>=0;--c){var e=localStorage.key(c);e=e&&e.match(b),e=e&&e[1],e&&e.indexOf(p)<0&&a(e,d(e))}}function j(a){var b=d(a);h(a),h(b)}function k(a){var b=d(a),c=f(b);if(c){var g=parseInt(c,q);if(e()>=g)return h(a),h(b),!0}}function l(a,b){u&&"console"in window&&"function"==typeof window.console.warn&&(window.console.warn("lscache - "+a),b&&window.console.warn("lscache - The error was: "+b.message))}var m,n,o="lscache-",p="-cacheexpiration",q=10,r=6e4,s=Math.floor(864e13/r),t="",u=!1,v={set:function(k,m,n){if(a()){if("string"!=typeof m){if(!c())return;try{m=JSON.stringify(m)}catch(o){return}}try{g(k,m)}catch(o){if(!b(o))return void l("Could not add item with key '"+k+"'",o);var p,r=[];i(function(a,b){var c=f(b);c=c?parseInt(c,q):s,r.push({key:a,size:(f(a)||"").length,expiration:c})}),r.sort(function(a,b){return b.expiration-a.expiration});for(var t=(m||"").length;r.length&&t>0;)p=r.pop(),l("Cache is full, removing item with key '"+k+"'"),j(p.key),t-=p.size;try{g(k,m)}catch(o){return void l("Could not add item with key '"+k+"', perhaps it's too big?",o)}}n?g(d(k),(e()+n).toString(q)):h(d(k))}},get:function(b){if(!a())return null;if(k(b))return null;var d=f(b);if(!d||!c())return d;try{return JSON.parse(d)}catch(e){return d}},remove:function(b){a()&&j(b)},supported:function(){return a()},flush:function(){a()&&i(function(a){j(a)})},flushExpired:function(){a()&&i(function(a){k(a)})},setBucket:function(a){t=a},resetBucket:function(){t=""},enableWarnings:function(a){u=a}};return v});
    Tip: Looking for a quick solution? Download the full code here.

  2. Define the events to be reported in Google Analytics.

    var ga_events = {
      	"prechat": 'PreChat Form Displayed',
      	"chat": "Chat Opened",
      	"answered": "Chat Answered",
      	"postchat": "Survey Displayed",
      	"email": "Email Form (Unavailable)",
      	"no-operators": "Unavailable Chat",
      	"chat-sent": "Survey Completed or Transcript",
      	"message-sent": "Unavailable Email Sent",
      	"final": "Chat Ended without Survey or Transcript"
    	}

  3. Validate messages for security reasons.

    The following code achieves the following:

    • Ensures messages come from the livechat[-eu].boldchat.com server
    • Parses messages
    • Checks localStorage for existing events to be de-duplicated and discarded, if necessary
    • Sends relevant events to Google Analytics

    Note how individual events are stored in the browser localStorage with a CID, a unique identifier for Chat windows that survives page re-loads, browser closing/reopening as well as navigation on different tabs under the same domain.

    The code also ensures that the user is able to start multiple simultaneous chats on different domains while events are accounted for separately and accurately.

    function listener(event) {
      if (event.origin !== "https://" + bcConfig.host) return;
      var pmessage = JSON.parse(event.data);
      if (pmessage.hasOwnProperty('gacomm')) {
        window.console && console.log("Received: " + event.data);
        var received = pmessage.gacomm + "---" + bcConfig.cid;
        var found = false;
        lscache.flushExpired();
        CIDs = lscache.get('CIDs');
        if (CIDs !== null) {
          var arrayLength = CIDs.length;
          for (var i = 0; i < arrayLength; i++) {
            if (CIDs[i] == received) {
              found = true;
              break;
            };
          };
        } else {
          CIDs = [];
        }
        if (!found) {
          CIDs.push(received);
          lscache.set('CIDs', CIDs, 60);
          window.console && console.log("Sending new event to GA: " + received);
          try {
            ga('send', 'event', {
              eventCategory: 'Live Chat',
              eventAction: ga_events[pmessage.gacomm],
              eventLabel: 'Chat Window'
            });
          } catch (err) {
            window.console && console.error("Google Analytics UA code not found on page");
          }
        }
      }
    }
    if (window.addEventListener) {
      addEventListener("message", listener, false)
    } else {
      attachEvent("onmessage", listener)
    }

  4. Close the try/catch:

    } catch (err) {
      window.console && console.error(err);
    }

Task Three: Video Chat Events (Optional)

Track video chat events by updating your Chat Frame and Chat Window Javascript Includes.

Note: The video chat feature works over the HTTPS exclusively. If your site does not support secure connections, BoldChat opens the chat in a popup window and switches to HTTPS. In this case, you must include the Google Analytics snippet at the top of the Chat Window Javascript Include code to be able to send tracking data to Google Analytics.

Tracking messages contain specific video chat events that are assigned to individual Event Categories. This data is appended to _tEvents objects.

  1. Use the following Chat Frame Javascript Include code on your site:

    /* Chat Frame Javascript Include */
    
    try {
      var VIDEOCHAT_CATEGORY = 'Video Chat';
    
      var trackEventByVideoSessionStatus = {
        3: { event: "videochat-started", initiatedBy: "By Visitor"},
        4: { event: "videochat-started", initiatedBy: "By Operator"},
        7: { event: "videochat-ended", initiatedBy: "By Operator"},
        8: { event: "videochat-ended",  initiatedBy: "By Visitor"}
      };
    
      function sendtxt(txt, category, parameter) {
        var message = JSON.stringify({
          gacomm: txt,
          eventCategory: category || 'Live Chat',
          eventParameter: parameter || 'Chat Window'
        });
    
        parent.parent.postMessage(message, "*");
      }
    
      sendtxt(bcConfig.chatOptions.page);
      window.console && console.log("Sent Chat Window Page: " + bcConfig.chatOptions.page);
      if (bcConfig.chatOptions.page == "chat") {
        var _tEvents = {
            "new-message": "bc_newHistoryMessageCallback",
            "video-support": "bc_chatWindowLoadedEventCallback",
            "video-statechange": "bc_videochatStatusChangedCallback"
          },
          _tFunction = function(i, type, fName, value) {
            if ((i == "new-message") && (bc.$("#bc-status-prompt").prev().hasClass("bc-operator-message"))) {
              sendtxt("answered");
            }
    
            if ((i == "video-support")) {
                if (bcConfig.videoSupport) {
                    sendtxt("videochat-available", VIDEOCHAT_CATEGORY);
                }
                else {
                    sendtxt("videochat-unavailable", VIDEOCHAT_CATEGORY);
                }
            }
    
            if ((i == "video-statechange")) {
                var trackEvent = trackEventByVideoSessionStatus[value];
                if (trackEvent) {
                  sendtxt(trackEvent.event, VIDEOCHAT_CATEGORY, trackEvent.initiatedBy);
                }
    
                if (bcConfig.videoSupport.isAudioOnly && trackEvent && trackEvent.event === "videochat-started") {
                  sendtxt("videochat-audio-only", VIDEOCHAT_CATEGORY);
                }
              }
          }
      }
      for (var i in _tEvents) {
        window[_tEvents[i]] = _tFunction.bind(window, i, "function", _tEvents[i]);
      }
    } catch (err) {
      window.console && console.error(err);
    }

    Tip: Looking for a quick solution? Download the full code here.

  2. In Google Analytics, ga_events objects must contain the new event definitions in the Chat Window Javascript Include.

    var ga_events = {
      "prechat": 'PreChat Form Displayed',
      "chat": "Chat Opened",
      "answered": "Chat Answered",
      "postchat": "Survey Displayed",
      "email": "Email Form (Unavailable)",
      "no-operators": "Unavailable Chat",
      "chat-sent": "Survey Completed or Transcript",
      "message-sent": "Unavailable Email Sent",
      "final": "Chat Ended without Survey or Transcript",
      "videochat-available": "Video Chat Available",
      "videochat-unavailable": "Video Chat Unavailable",
      "videochat-started": "Video Chat Started",
      "videochat-ended": "Video Chat Ended",
      "videochat-audio-only": "Chat is Audio Only"
    }
    
    Update the ga message to send new tracking parameters.

    function listener(event) {
      if (event.origin !== "https://livechat.boldchat.com") return;
      var pmessage = JSON.parse(event.data);
      if (pmessage.hasOwnProperty('gacomm') 
          && pmessage.hasOwnProperty('eventCategory') 
          && pmessage.hasOwnProperty('eventParameter')) {
        window.console && console.log("Received: " + event.data);
        var received = pmessage.gacomm + "-" + bcConfig.cid;
        var found = false;
        lscache.flushExpired();
        CIDs = lscache.get('CIDs');
        if (CIDs !== null) {
          var arrayLength = CIDs.length;
          for (var i = 0; i < arrayLength; i++) {
            if (CIDs[i] == received) {
              found = true;
              break;
            };
          };
        } else {
          CIDs = [];
        }
        if (!found) {
          CIDs.push(received);
          lscache.set('CIDs', CIDs, 60);
          window.console && console.log("Sending new event to GA: " + received);
          try {
            ga('send', 'event', {
              eventCategory: pmessage.eventCategory,
              eventAction: ga_events[pmessage.gacomm],
              eventLabel: pmessage.eventParameter
            });
          } catch (err) {
            window.console && console.error("Google Analytics UA code not found on page");
          }
        }
      }
    }
    if (window.addEventListener) {
      addEventListener("message", listener, false)
    } else {
      attachEvent("onmessage", listener)
    }
    } catch (err) {
      window.console && console.error(err);
    }

    Tip: Looking for a quick solution? Download the full code here.

Reporting

Events are reported with a few seconds' delay under the Real-Time Events section and they are processed and made available within 24 hours under the Behavior section as well as Dimensions in Custom Reports, allowing maximum flexibility to be tied to any other Google Analytics dimension and metric.



Troubleshooting

For troubleshooting purposes and to ensure that events are transmitted correctly, the code above outputs three log lines for each chat event in the browser console, if available.



Similarly, in case the Google Analytics code is not found by BoldChat on the hosting website page, the following error is thrown in the browser console, if available: