Use 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 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, we can change the output tag location in starter store pages, or we 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:

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 Madisons and Elite starter stores that are published with WebSphere Commerce Version 7 Feature Pack 3 enhancements are already tagged with the <cm:output /> tag. The tag looks like this:

For these stores, the <cm:output /> tag is placed in the following file: workspace_dir/crs-web/WebContent/store_name/include/CommonJSToInclude.jspf Here is a snippet from the bottom of the CommonJSToInclude.jspf file showing the <cm:output /> tag:

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 Madisons or Elite, we can use the auto tagging utility to automatically add the <cm:output /> tag to the <head> element of all the 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:

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 the store page, or write additional content to the page. To do so, we can change the location of the <cm:output /> tag in the 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 the store pages. If so, we 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 the store pages, we 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.

  1. Defining the output tag in the analytics configuration file (biConfig.xml)
    We can define an output tag in your biConfig.xml file by adding an <output> element. Within the <output> element, add the JavaScript snippets, or any other content, to write to a specific location in the store pages.

  2. Adding the output tag to the store JSP pages
    After you define the output tag in your biConfig.xml file, add the output tag to all the store pages. Place the output tag in the location in the page at which we want the JavaScript snippets for to be written in the store page.


Related concepts
Integrating a store with IBM Digital Analytics for WebSphere Commerce


Related tasks
Configure the IBM Digital Data Exchange integration


Related reference
Sample biConfig.xml file for IBM Digital Analytics