2 Exercise 1: Adding a New Parameter for Data Capture

This exercise shows you how to add a new parameter to Analytics for data capture.

This exercise contains the following sections:

Section 2.1, "Overview"
Section 2.2, "Adding the New Parameter to the Image Tag and Its JSP"
Section 2.3, "Next Steps"

2.1 Overview

In this exercise, based on the FirstSite II sample site, you will configure Analytics to start capturing data on a new parameter, agent. The new agent parameter will be used for capturing raw data on the browsers used by visitors of your site.

Once you add the new agent parameter to Analytics, you will proceed to the next exercise (Chapter 3, "Exercise 2: Adding a New Parameter to the DetailDefinition Table") in order to configure Analytics to recognize the new agent parameter. Then, you will follow instructions in Chapter 4, "Exercise 3: Developing a New Analytics Job" to create an Analytics job that statistically processes the new parameter for display in a report ("NewBrowsers" report in this tutorial). The statistics of the processed agent parameter will be displayed as a table column in the "NewBrowsers" report once you create the report, as shown in Chapter 5, "Exercise 4: Creating and Preparing a Report for Viewing."

Note:

Throughout this exercise, we assume you are working exclusively with the FirstSite II sample site. Select this site whenever prompted in the Analytics or WebCenter Sites interfaces.

2.2 Adding the New Parameter to the Image Tag and Its JSP

The first step is to make Analytics aware of the new parameter so that it starts capturing data on that parameter. In our example, you will do so by adding the parameter to the Analytics image tag inside the FSIIWrapper element and to the AddAnalyticsImgTag JSP. When you complete the steps below, the sensor servlet will start capturing the parameter values and storing them as raw data.

Add the new parameter to the Analytics image tag call in the FSIIWrapper element:
1. Log in to the WebCenter Sites Admin interface as an administrator or another user who has the permissions to edit "CSElement" assets.
2. When prompted, select the FirstSite II sample site.
3. In the button bar, click Search.
4. In the list of asset types, click Find CSElement.
5. In the "Search" form, enter FSIIWrapper into the search field and click Search.
6. In the list of results, click the Edit (pencil) icon next to the FSIIWrapper asset.
7. WebCenter Sites displays the "FSIIWrapper" asset in the "Edit" form.
8. In the section selector at the top of the form, click Element.
9. WebCenter Sites displays the "Element" section of the "Edit" form.
10. To make editing the element code easier, select all of the text in the Element Logic field, then copy and paste it into a text editor of your choice. Save the code to a temporary file.
  - In the element code, locate the call to the Analytics image tag, shown below:
```
<render:callelement elementname="Analytics/AddAnalyticsImgTag">
    <render:argument name="c" value='<%=ics.GetVar("c")%>'/>
    <render:argument name="cid" value='<%=ics.GetVar("cid")%>'/>
    <render:argument name="site" value='<%=ics.GetVar("site")%>'/>
    <render:argument name="pagename" value='<%=ics.GetVar("childpagename")%>'/>
    <render:argument name="recid" value='<%=ics.GetVar("recid")%>'/>
</render:callelement>
```
  - Insert the following statement at the end of the Analytics image tag call, but before the closing </render:callelement> tag:
```
<render:argument name="agent" value='<%= request.getHeader("User-Agent")%>'/>
```
    Note:
    
    The agent variable must be set before the Analytics image tag is called.
  - The modified Analytics image tag call should look as follows:
```
<render:callelement elementname="Analytics/AddAnalyticsImgTag">
<render:argument name="c" value='<%=ics.GetVar("c")%>'/>
<render:argument name="cid" value='<%=ics.GetVar("cid")%>'/>
<render:argument name="site" value='<%=ics.GetVar("site")%>'/>
<render:argument name="pagename" value='<%=ics.GetVar("childpagename")%>'/>
<render:argument name="recid" value='<%=ics.GetVar("recid")%>'/>
<render:argument name="agent" value='<%= request.getHeader( "User-Agent" )
%>'/>
   </render:callelement>
```
  - Save and close the file.

Add the new parameter to the Analytics image tag JSP.

Start WebCenter Sites Explorer.
In the WebCenter Sites Explorer screen, select File, then Open Content Server to display the "Content Server Login" dialog box.
Enter the following values:
- Host name or address – The host name or IP address. You must not leave this blank.
- Username – Your WebCenter Sites user name.
- Password – Your WebCenter Sites password.
- Port – The port number (the default is 8080).
- Protocol – Typically, this is HTTP. (You may select HTTPS if the web server is running SSL).
- Application server URL path – Select the CS servlet (/cs/CatalogManager) option.
Your completed login form should be similar to the one in Figure 2-1:

Figure 2-1 WebCenter Sites Explorer Login Form

Description of "Figure 2-1 WebCenter Sites Explorer Login Form"
Click OK to log in.

The Sites Explorer window appears.
In the localhost tree, expand the following: Tables, then ElementCatalog, and then Analytics.
In the Analytics table, open the AddAnalyticsImgTag JSP.
Copy and paste the AddAnalyticsImgTag.jsp code in a text editor and locate the following lines:
```
String recid = ics.GetVar("recid");
String siteName = ics.GetVar("site");
```

Add the following line after the two lines listed in step g (directly above:)

String agent = ics.GetVar("agent");

The modified section will look as follows:

String recid = ics.GetVar("recid");
String siteName = ics.GetVar("site");
String agent = ics.GetVar("agent");

Locate the following piece of code and insert the bold-type code in the exact locations shown:

<script type="text/javascript">
<!--
var jsParam = '';
if(self.StatPixelParamFromPage) {jsParam=StatPixelParamFromPage;};
var color = 'n/a'; var size = 'n/a'; var puri = '';
var java = navigator.javaEnabled();
var nav = navigator.appName;
var agent = navigator.userAgent;
var objValue = '';
var write = (navigator.appName=='Netscape' && (navigator.appVersion.charAt(0)=='2' ||    navigator.appVersion.charAt(0)=='3')) ? false:true;
if (write==true) {
size = screen.width + "x" + screen.height;
color = (nav!='Netscape') ? screen.colorDepth:screen.pixelDepth;
objValue= encodeURIComponent('<%= ics.GetVar("assetname") %>');
puri = '?siteName=<%= siteName %>&objType=<%= UobjType %>&objID=<%= id
%>&objName=' +objValue+'&sessionID=<%= TsessionID %>
&agent=<%= agent %>&Referer=<%= referer
%>&nav='+nav+'&size='+size+'&color='+color+'&java=
'+java+'&js=true'+jsParam;
puri += '<%= recparameter%>';
puri += '<%= urlEncparameter%>';
//alert(puri);
document.write('<img style="display:none;" height="1" width="1" border="0" src="<%= statisticSensorPath%>'+puri+'" alt="pixel" /
>');
}
//-->
</script>
<noscript>
<img style="display:none;" height="1" width="1" src="<%= statisticSensorPath%>?siteName=<%= siteName%>&objType=<%= UobjType%>&objID=<%= id%>&objName=<%= ics.GetVar("assetname")%>&URLENC=<%= ics.GetVar("objUrl")
%>&sessionID=<%= TsessionID%>
&agent=<%= agent %>&Referer=<%= referer%>&js=false"
alt="pixel" />
</noscript>

When you have made your modifications, select all of the code in your text editor, then copy and paste it back into the Sites Explorer field.
Save and close the file.
Restart the application server for your changes to take effect.

2.3 Next Steps

In Chapter 3, "Exercise 2: Adding a New Parameter to the DetailDefinition Table," you will add the agent parameter to the DETAILDEFINITION table for data capture. This enables Analytics to process the agent parameter which, in turn, makes the parameter available to an Analytics job (which you will create in Chapter 4, "Exercise 3: Developing a New Analytics Job") to process the raw data captured by the new agent parameter. The new Analytics job will process the agent parameter for display in a report ("NewBrowsers" report in this tutorial). The processed agent parameter will be displayed as a table column in the "NewBrowsers" report.