Using the output tag to configure the placement of IBM Digital Analytics JavaScript snippets

In store JSP pages, the output tag (<cm:output/>) acts as a marker for the location to write JavaScript snippets for IBM Digital Analytics, formerly known as Coremetrics Analytics each time the page is rendered. These IBM Digital Analytics JavaScript snippets are defined in the analytics configuration file (biConfig.xml), within the <output> element. The default sample biConfig.xml file and the latest WebSphere Commerce starter stores are already set up to use the output tag for its intended purpose. If required, you can change the output tag location in starter store pages, or you can use the <output> tag to write additional content to a location in a store page.

Default implementation of the output tag

In the default sample biConfig.xml file, the output tag is defined using the <output> element, as shown here:
...
<output section = "header">
    <![CDATA[
    <script type="text/javascript" src="//libs.coremetrics.com/eluminate.js"></script> 
    <script type="text/javascript"> 
    cmSetupNormalization("krypto-_-krypto"); 
    // send data to production system 
    //cmSetClientID("99999999",true,"data.coremetrics.com","thesite.com"); 
    // send data to test system 
    cmSetClientID("69999999",false,"testdata.coremetrics.com","thesite.com"); 
    </script> 				
    ]]>
</output>
...

When a store page is rendered, all the content within the <output> element must be written to the page. The purpose of this JavaScript content is to include the IBM Digital Analytics library file (eluminate.js) and call the cmSetClientID function. IBM Digital Analytics uses this content when collecting analytics data.

To mark the location in the store page where the content within the <output> element must be written, the AuroraESite starter store that is published with WebSphere Commerce is tagged with the <cm:output /> tag. The tag looks like this:
<cm:output section="header" />

For these stores, the <cm:output /> tag is placed in the following file:

  • WebSphere Commerce DeveloperWCDE_installdir/workspace/Stores/WebContent/store_name/include/CommonJSToInclude.jspf
  • WC_eardir/Stores.war/store_name/include/CommonJSToInclude.jspf
Here is a snippet from the bottom of the CommonJSToInclude.jspf file showing the <cm:output /> tag:
...
<%@ include file="CommonJSToIncludeExt.jspf"%>
<%@ include file="CommonJSToIncludeBrazilExt.jspf"%>
<%@ include file="MultipleWishListSetup.jspf" %>
<%@ include file="../ShoppingArea/Configurator/SterlingConfiguratorJS.jspf" %>

<flow:ifEnabled feature="Analytics">
	<cm:output section="header" />
</flow:ifEnabled>

<!-- END CommonJSToInclude.jspf -->

The CommonJSToInclude.jspf file is a special file included in the <head> element of every starter store page. Its purpose is to include global variables and functions in all starter store pages. By including the <cm:output /> tag in this special file, the IBM Digital Analytics JavaScript snippets that are defined in the <output> element of the biConfig.xml file will be written to the <head> element of every store page.

The output tag and the auto tagging utility

If you have a custom store, rather than a store based on AuroraESite, you can use the auto tagging utility to automatically add the <cm:output /> tag to the <head> element of all your store pages, at the same time that the utility adds the <cm:pageview /> tag. This way, you do not need to add the <cm:output /> tag to each page manually.

The <output> element compared to the <instrumentation> element in the biConfig.xml file

Most biConfig.xml files that are implemented before WebSphere Commerce Version 7 Feature Pack 3 have an <instrumentation> element that contains IBM Digital Analytics JavaScript snippets similar to the <output> element. Here is an example:
...
<instrumentation>
    <![CDATA[
    <script language="JavaScript1.1" type="text/JavaScript" src="//libs.coremetrics.com/eluminate.js"></script>
    <script language="JavaScript1.1" type="text/JavaScript">
    cmSetClientID("12345",true,"data.coremetrics.com","localhost");
    </script>]]>
</instrumentation>

...
When a store page is rendered, the contents of the <instrumentation> element are written above the </body> tag near the end of the page.

In Feature Pack 3 or later biConfig.xml files, the <output> element is used instead of the <instrumentation> element. This means that the IBM Digital Analytics JavaScript snippets are now written within the <head> element rather than near the end of the page. Certain IBM Digital Analytics applications, such as IBM Digital Analytics AdTarget, require the snippets to be written near the top of the page.

The added benefit of the <output> element over the <instrumentation> element is to give you control over where the JavaScript snippets are written; however, if you use the <output> element, your store pages must contain a corresponding <cm:output /> tag to mark the location to write the JavaScript snippets.

Reasons to change the default output tag implementation

There are several reasons to change the default output tag implementation:
  1. You might want to write the IBM Digital Analytics JavaScript snippets to a different location in your store page, or write additional content to the page. To do so, you can change the location of the <cm:output /> tag in your store pages and change the content within the <output> element in your biConfig.xml file.
  2. You might want to write multiple IBM Digital Analytics JavaScript snippets to different locations in your store pages. If so, you can define multiple output tags in your biConfig.xml file, each with a different section parameter value. Here is an example that includes the default <output> tag definition for section = "header" and a second <output> tag definition for section = "body":
    
...
<store storeId = "10101" biprovider = "coremetrics" enabled = "true" debug = "true" 
      useHostedCMHLibraries = "true">
    <clientid>69999999</clientid>
    <output section = "header">
        <![CDATA[
        <script type="text/javascript" src="//libs.coremetrics.com/eluminate.js"></script> 
        <script type="text/javascript"> 
        cmSetupNormalization("krypto-_-krypto"); 
        // send data to production system 
        //cmSetClientID("99999999",true,"data.coremetrics.com","thesite.com"); 
        // send data to test system 
        cmSetClientID("69999999",false,"testdata.coremetrics.com","thesite.com"); 
        </script> 				
        ]]>
    </output>

    <output section = "body">
        <![CDATA[
        <script type="text/JavaScript">
        your_JavaScript_goes_here
        </script>
        ]]>
    </output>
</store>
...

    Then, in your store pages, you must have the following <cm:output /> tags at the appropriate locations:

    <cm:output section="header" />

    <cm:output section="body" />
The following procedures provide detailed steps about changing the configuration of the output tag.