Upgrading your Webtrends JavaScript Tag from v9 to v10

Although the v10 JavaScript tag has changed significantly from previous releases, you can easily upgrade from a prior version.

Note: The V10 JavaScript tag requires SmartSource Data Collector version 9.2.1 or higher.

You can place the v10 tag anywhere on the page. Since the tag is loaded asynchronously, it does not block page rendering in any way. You can place the tag in the <head> section or anywhere within the <body> section with minimal impact on page rendering times. In addition, the tag runs in the background, so there is minimal impact on user experience after the page has loaded.

Upgrading is a 4 step process:

  1. Transform Configuration Settings
  2. Migrate Customizations
  3. Change HTML Markup
  4. Test

Before you begin, you'll need to have:

Transform Configuration Settings

For v10, the configuration settings are separated from the tag logic. In v9, configuration settings are changed by editing the user modifiable properties of the WebTrends object constructor (webtrends.js):
function WebTrends(){
	var that=this;
	// begin: user modifiable
	this.dcsid="dcs9x99xxxx9xxx9xx9xxxx9x_9x9x";
	this.domain="statse.webtrendslive.com";
	this.timezone=-3;
	this.fpcdom=".foo.com";
	this.enabled=true;
	this.i18n=false;
	this.fpc="WT_FPC";
	this.paidsearchparams="gclid";
	this.splitvalue="";
	this.preserve=false;
	// end: user modifiable
	.
	.
	.
}	
In v10, configuration settings are changed by editing the parameter that is passed to the init() method of the Webtrends object. This parameter is a JSON object comprised of name/value pairs which correspond to configuration settings. The init() method is called as part of the instantiation of the Webtrends object (webtrends.html):
<!-- START OF SmartSource Data Collector TAG v10.2.0 -->
<!-- Copyright (c) 2011 Webtrends Inc.  All rights reserved. -->
<script>
window.webtrendsAsyncInit = function(){
    var dcs=new Webtrends.dcs().init({
        dcsid:"dcs9x99xxxx9xxx9xx9xxxx9x_9x9x",
        domain:"statse.webtrendslive.com",
        timezone:-3
        }).track();
};
As you can see, the name value pairs in v10 are exactly the same as the properties in v9. To transform your v9 settings, follow these steps:
  1. Open the v9 copy of webtrends.js in an editor
  2. Copy the user modifiable section to a scratch buffer
    	this.dcsid="dcs9x99xxxx9xxx9xx9xxxx9x_9x9x";
    	this.domain="statse.webtrendslive.com";
    	this.timezone=-3;
    	this.fpcdom=".foo.com";
    	this.enabled=true;
    	this.i18n=false;
    	this.fpc="WT_FPC";
    	this.paidsearchparams="gclid";
    	this.splitvalue="";
    	this.preserve=false;
    
  3. Edit the scratch buffer as follows:
    • Remove all occurrences of "this."
    • Replace all semicolons ";" with commas ","
    • Replace all equal signs "=" with colons ":"
    • Remove the final comma
    The result should look something like this:
    	dcsid:"dcs9x99xxxx9xxx9xx9xxxx9x_9x9x",
    	domain:"statse.webtrendslive.com",
    	timezone:-3,
    	fpcdom:".foo.com",
    	enabled:true,
    	i18n:false,
    	fpc:"WT_FPC",
    	paidsearchparams:"gclid",
    	splitvalue:"",
    	preserve:false
    
  4. Open the v10 copy of webtrends.html in an editor and examine the configuration settings:
    window.webtrendsAsyncInit = function(){
        var dcs=new Webtrends.dcs().init({
          dcsid:"dcs9x99xxxx9xxx9xx9xxxx9x_9x9x",
            domain:"statse.webtrendslive.com",
            timezone:-3
            }).track();
    };
    
  5. Overwrite the v10 configuration settings with the settings from the v9 scratch buffer
    window.webtrendsAsyncInit = function(){
        var dcs=new Webtrends.dcs().init({
    	dcsid:"dcs9x99xxxx9xxx9xx9xxxx9x_9x9x",
    	domain:"statse.webtrendslive.com",
    	timezone:-3,
    	fpcdom:".foo.com",
    	enabled:true,
    	i18n:false,
    	fpc:"WT_FPC",
    	paidsearchparams:"gclid",
    	splitvalue:"",
    	preserve:false
            }).track();
    };

Migrate Customizations

Tag customizations can come in many forms. This topic will cover the simplest case of ad hoc JavaScript on the page used to set custom parameters. The recommended way to set custom parameters is using <meta> tags. In some cases, you may need to use JavaScript for this purpose (i.e. gather custom parameter data dynamically). The v9 tag contained a method called dcsCustom that allowed you to change parameters on a page using JavaScript. For example:
<script type="text/javascript">
_tag.dcsCustom=function(){
// extract info from to URL
_tag.DCSext.t_B02 = document.URL.split('/')[3];
_tag.DCSext.z_brand = XlateBrand(document.URL).Name;
_tag.dcsCollect();
</script>

To achieve this using the v10 tag, edit the JavaScript as follows:

  1. Rename references from "_tag." to "dcs."
  2. Incorporate custom variables using the inline HTML approach or the loader approach.
    • Inline HTML:

      1. Separate the dcs.track() method call and insert the custom variable assignments in between the dcs.init() and the dcs.track() method calls.
      2. Continuing the example:
        window.webtrendsAsyncInit = function(){
            var dcs=new Webtrends.dcs().init({
                dcsid:"dcs9x99xxxx9xxx9xx9xxxx9x_9x9x",
                domain:"statse.webtrendslive.com",
                timezone:-3
                });
            // extract info from to URL
            dcs.DCSext.t_B02 = document.URL.split('/')[3];
            dcs.DCSext.z_brand = XlateBrand(document.URL).Name;
            dcs.track();
        
    • Loader:

      To use the loader approach, add a webtrendsAsyncLoad function definition before the script block that includes webtrends.load.js:
      <script>
      window.webtrendsAsyncLoad=function(dcs){
      dcs.DCSext.t_B02 = document.URL.split('/')[3];
            dcs.DCSext.z_brand = XlateBrand(document.URL).Name;
      }
      </script>
      <script type="text/javascript" src="/scripts/webtrends.load.js"></script>
      

Change HTML Markup

You replace the v9 markup with the v10 markup. Examples of the markup can be found in the webtrends.html file which is delivered in a .zip file by Webtrends Tag Builder (https://tagbuilder.webtrends.com).

  1. Delete the v9 markup
    <!-- START OF SmartSource Data Collector TAG -->
    <!-- Copyright (c) 1996-2011 Webtrends Inc.  All rights reserved. -->
    <!-- Version: 9.4.0 -->
    .
    .
    .
    <!-- END OF SmartSource Data Collector TAG -->
    
  2. Add the v10 markup
    <!-- START OF SmartSource Data Collector TAG v10.2.0 -->
    <!-- Copyright (c) 2011 Webtrends Inc.  All rights reserved. -->
    .
    .
    .
    <!-- END OF SmartSource Data Collector TAG v10.2.0 -->
    
  3. The v10 markup contains an anonymous function that loads the webtrends.js file by creating a script tag dynamically. This function references the external JavaScript file webtrends.js. Make sure that the reference agrees with the actual location on your web server. For example, if you put your JavaScript files in the "/scripts" folder, then the code should look like this:
    (function(){
        var s=document.createElement("script"); s.async=true; s.src="/scripts/webtrends.js";    
        var s2=document.getElementsByTagName("script")[0]; s2.parentNode.insertBefore(s,s2);
    }());
    
    Note: If you are using the minified version of the tag, the name of the file is webtrends.min.js

Test

Load a test page containing your HTML markup into a browser. Using an HTTP traffic sniffing tool such as Fiddler, you should see something similar to the following:
GET   200   text/html   http://mysite/webtrends.html
GET   200   application/x-javascript   http://mysite/webtrends.js
GET   200   application/x-javascript    http://statse.webtrendslive.com/dcs.../wtid.js?callback=Webtrends.dcss.dcs9x99xxxx9xxxxxxx9xxxx9x_9x9x.dcsGetIdCallback
GET   303   Redirect to   http://statse.webtrendslive.com/dcs.../dcs.gif?dcsredirect=126&dcstlh=0&dcstlv=0&dcsdat=1324085229740&dcssip=...	http://statse.webtrendslive.com/dcs.../dcs.gif?&dcsdat=1324085229740&dcssip=...
GET   200  image/gif   http://statse.webtrendslive.com/dcs.../dcs.gif?dcstlh=0&dcstlv=0&dcsdat=1324085229740&dcssip=...