Web Tracking with the Xponent Web Tag

In the Xponent Journey Hub Graph API Listener, a screen like the one below is shown if the Web Tracking and Recommendation Listener type is chosen. There are a number of Tracking Options that can be selected, and these update the JavaScript tracking code shown below the buttons.

This tracking code should be added to the header of any page on the website from which you wish to track activity. This is most typically performed with a tag manager. The JavaScript tag will automatically POST the activity to the graph into the schema location specified. 

The items that are tracked can be controlled in the _kw.events the object of the JavaScript. The allowed and default settings for the _kw.events object are as follows: 

This allows very fine control, on a page-by-page basis, of the web tracking activity.

For Example:

You can turn on geographic location tracking just on the pages where it is appropriate and expected by the consumer to do so. 

The provided JavaScript code looks similar to this (dependent on the options selected): 

<script>
  var _kw = {};
  _kw.options = {
    "listenerId": "listener-id-here",
    "listenerHost": "https://api.kitewheel.com/api/v1/listener/",
    "specifyCookieDomain": {"enabled": false},
    "doNotTrack": {"enabled": false}
  };
  _kw.events = {
    "trackViews": {"track": true},
    "trackClicks": {"track": true,"noConflict": false},
    "trackForms": {"track": true,"noConflict": false},
    "trackDropdowns": {"track": true},
    "trackButtons": {"track": true},
    "trackBlurs": {"track": true},
    "trackDivs": {"track": false},
    "trackGeo": {"track": false},
    "trackFingerprint": {"track": false}
  };
  _kw.success = function(data) {
    // Handle returned data here
  };
</script>
<script src="https://cdn.kitewheel.com/webTrack.v1.js"></script>

The JavaScript provides a _kw.success function that should be called to handle a successful recommendation event, i.e., change the website's content. 

The Xponent tag can be deployed by directly putting the JavaScript on every page or more, using a tag manager to control which pages the tag appears on. If you are using Google Tag Manager, you will need to make sure that the tag is deployed with the option "Support document. write" set to true. When the Xponent Tag is deployed correctly in Google Tag Manager, the JavaScript should look like this:

Web Tag Version

Xponent regularly updates the Xponent Web Tag to keep up to date with security issues and when adding new functionality. The latest version of the Xponent Web Tag should be used when starting new projects or when Xponent announces that clients should update for security reasons. Xponent will not change existing versions of the web tag to ensure that we do not break any functionality on websites that are using the web tag. 

It is recommended that third-party JavaScript is included using sub-resource integrity values to ensure that the  code that is included on the site is the actual Xponent code and has not been interfered with by an unknown intermediary. Using the "integrity" and "crossorigin" attributes on the HTML script tag is recommended. A full example is shown below, and the sub-resource integrity constraint values are listed on the Xponent Web Tag Release History page. 

These changes are not yet reflected in the Journey Hub user interface. 

<script>
  var _kw = {};
  _kw.options = {
    "listenerId": "listener-id-here",
    "listenerHost": "https://api.kitewheel.com/api/v1/listener/",
    "specifyCookieDomain": {"enabled": false},
    "doNotTrack": {"enabled": false},
    "stopBodyPropagation": {"enabled": false}
  };
  _kw.events = {
    "trackViews": {"track": true},
    "trackClicks": {"track": true,"noConflict": false},
    "trackForms": {"track": true,"noConflict": false},
    "trackDropdowns": {"track": true},
    "trackButtons": {"track": true},
    "trackBlurs": {"track": true},
    "trackDivs": {"track": false},
    "trackGeo": {"track": false},
    "trackFingerprint": {"track": false}
  };
  _kw.success = function(data) {
    // Handle returned data here
  };
  // Optionally set _kw.extras to be an object or a function to capture additional data
  _kw.extras = function() { return window.localStorage }
</script>
<script src="https://cdn.kitewheel.com/kwTagV1.js"
        integrity="sha384-fraS4CZ14R7Vg+DiE9x3GAuZPCYRTsWepQSvIdlyrbDOsu1lgeIFsClvE1WL2aoM"
        crossorigin="anonymous"></script>

Web Tracking Do-Not-Track Feature

The Xponent Graph API web tracking JavaScript has been modified to add a "doNotTrack" configuration section that specifies which HTML DOM elements and cookies should or should not be tracked. 

• cookies - the cookies specified will not be returned in the web tracking events
• names - any HTML DOM elements that match the list of names will not be returned
• ids - any HTML DOM elements with the specified ids will not be returned
• classes - any HTML DOM elements that have this class will not be tracked 

Setting the options in the UI will add the appropriate options to the snippet for use in the _kw. options object.

By default,  if Do Not Track is enabled, the values set will be 'deny list'. This is the 'Deny' setting. Any values specified in the cookies, names, id, or classes fields will be omitted from tracking.  If an element does not match one of those, it will be included in tracking as normal.

The above options would produce the following as part of the snippet for your webpage

For Example:

If you had an HTML body like this, and assuming you had the appropriate tracking enabled in general (e.g., tracking div clicks, blurs, form submits, etc)

<body>
  <h1>Hello world!</h1>
  <div id="content">
    <code id="response">This is a div tag</code>
  </div>
  <div id="testers">
    <a href="index.html" class="doNotTrack">This is a link!</a><br/>
    <div id="form">
      <form action="index.html" method="post">
        <input type="text" name="myText"/>
        <input type="password" name="passField"/>
        <input type="submit" value="Submit me"/>
      </form>
    </div>
  </div>
</body>

• The password field would not be tracked in a blur or included as a value in the form submit event because of the names setting 
• The clicks on the content div will not be tracked because of the id setting
• The click on the link will not be tracked as it has the "doNotTrack" class - this is the recommended approach
• The cookie "privateCookie" will not be returned as part of any packet 

If Do Not Track is enabled, and the setting is allowList, instead, the values will be treated as an “allow list” set.  That is, ONLY those values set in the fields will be included in tracking.  If an element does not match one of those, it will NOT be included in any tracking.

The above options would have the following effect on the HTML example.

• ONLY the following would be tracking.
  • The input field with the name 'myText' because of the name settings
  • Clicks on the content div because of the id settings

Caveats

• If attempting to deny a list or allow a list a dropdown change event, it can only be included/excluded in its entirety.  Add the name, id, or class to the <select> tag.  Adding an id, name, or class to only selected <option> tags within a <select> tag has no effect.

Web Components and Custom Element Tracking

WebTrack version 5 adds two additional options for use within _kw.options to allow for tracking of Web Components and custom elements.

Examples of elementPrefix usage:

• component name is bx-input, the elementPrefix is bx
• component name is ui5-select, the elementPrefix is ui5
• component name is bolt-textfield, the elementPrefix is bolt

Supported input types for elementPrefix:

• input
• text field
• textarea
• select
• radio
• radio-group
• radio-button
• checkbox

If the component library does not follow these naming conventions or a custom component is being used, add the names to selectors and Web Track will be able to track those components.

Submitting Form Data

In order for elements to be considered valid form controls for submission, each input MUST have a name attribute. This follows standards set by The World Wide Web Consortium (W3C).

<input type="text" name="this-attribute-is-required">

 <input-element name="custom-web-component" label="Custom Crafted Web Component"></input-element>

Form Submission

17.13.2 Successful controls:

A successful control is "valid" for submission. Every successful control has its control name and current value as part of the submitted form data set. A successful control must be defined within a FORM element and must have a control name.

Tracked Input Types

Fields that are not tracked and not included in formData (submitted data):
disabled fields

• fields without a name attribute
• password fields (password fields will also not be tracked on any type of event)
• radios or checkboxes that are not checked/selected or have a values
• select (dropdown) components without an option selected

Web Tracking JSON Structure 

{
    "cookies": {
        "kw-fingerprint-b17bc362301beb8a84e7347c7e666d84": "a10f0746dfd7d9bc3c16c3929682f13d",
        "kw": "89fba850-914d-11e7-ac47-bbc724996795",
        "kw-session-b17bc362301beb8a84e7347c7e666d84": "97c99ce0-97a5-11e7-83f1-6be334c9a090"
    },
    "tag": null,
    "href": null,
    "tagName": null,
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36",
    "kwSession": "97c99ce0-97a5-11e7-83f1-6be334c9a090",
    "epochTs": 1505212429690,
    "eventtype": "view",
    "winHeight": 960,
    "tagData": null,
    "formdata": null,
    "kwFingerprint": "a10f0746dfd7d9bc3c16c3929682f13d",
    "winWidth": 1920,
    "scrollPctHor": "0.00",
    "kwCookie": "89fba850-914d-11e7-ac47-bbc724996795",
    "timestamp": "2017-09-12 11:33:49.685",
    "tagId": null,
    "scrollPctVer": "0.00",
    "dropdown":{"name":"unnamed dropdown","value":"audi"},
    "eventtype":"change",
    "geoloc": {
        "timestamp": null,
        "coords": {
            "altitude": null,
            "longitude": null,
            "latitude": null,
            "altitudeAccuracy": null,
            "speed": null,
            "heading": null,
            "accuracy": null
        }
    },
    "mouseY": null,
    "mouseX": null,
    "_kw": {
        "headers": {
            "origin": "http://yourdomain.com",
            "content-length": "998",
            "accept-language": "en-GB,en;q=0.8",
            "accept-encoding": "gzip, deflate, br",
            "x-forwarded-port": "443",
            "x-forwarded-for": "0.0.0.0, 0.0.0.0",
            "accept": "application/json, text/javascript, */*; q=0.01",
            "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36",
            "host": "api.kitewheel.com",
            "x-forwarded-proto": "https",
            "referer": "www.google.com",
            "x-real-ip": "0.0.0.0",
            "content-type": "application/json; charset=UTF-8"
        },
        "method": "POST"
    },
    "url": "http://yourdomain.com",
    "referrer": "www.google.com",
    "extras": {}
}

• There are typically two referrer fields in the web tracking packet because there are two different ways to get it (from the browser and from the headers), which may give you different results.
  • The one included in the main set of attributes is the browser version, the one in _kw.headers is a straight dump of all HTTP headers
  • The browser is more likely to return “null,” but less likely to give you useless garbage ("this page was referred by itself") 
• It is only possible to include the Xponent web tracking script once per web page.