6 Enabling Data Capture for Different Types of Reports

This chapter shows you how to enable data capture on website visitors and their usage of pages that are published on Oracle WebCenter Sites. In this chapter, you will implement the AddAnalyticsImgTag and the associated code to enable data capture. Once the captured data is statistically processed, the results can be made available for various Analytics reports such as General Information, Content Information, User Information, and Engage reports.

This chapter contains the following sections:

6.1 Enabling Data Capture

Note:

The steps in this section require you to have a working knowledge of WebCenter Sites elements, Java, and JSP. If you plan to enable data capture on Engage assets, you must also have a thorough understanding of recommendations and segments.

Before starting the steps in this chapter, ensure WebCenter Sites administrators have completed the procedures for integrating Analytics with Web Center Sites, as described in the Oracle Fusion Middleware WebCenter Sites: Analytics Administrator's Guide.

Analytics can capture data on the usage of WebCenter Sites assets, on their visitors, and the visitors' searches only if published pages are tagged for data capture. In the case of Engage assets and internal searches, the assets themselves must be tagged for data capture.

This section shows you how to enable data capture for a variety of reports:

Completing the steps enables data capture for all reports in all report groups.

6.1.1 Enabling Data Capture for General, Content, and User Information Reports

In this section, you will enable data capture for all report groups except "Internal Searches" and "Engage."

To enable data capture for General, Content, and User Information Reports

Tag the pages on which the assets are displayed. Use the following code:

<%-- Analytics Image tag
     Data capture code for asset uses and user information
--%>
<ics:if condition='<%="true".equalsIgnoreCase(ics.GetProperty("analytics.enabled", "futuretense_xcel.ini", true))%>'>
<ics:then>

<ics:if condition='<%=ics.GetVar("packedargs") != null%>'>

<ics:then>
<render:unpackarg unpack="recid" remove="true"
packed='<%=ics.GetVar("packedargs")%>' outvar="packedargs"/>

</ics:then>

</ics:if>
<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>
</ics:then>
</ics:if>

Parameters

  • c:

    Type of asset being visited

  • cid:

    ID of an asset of a given type

  • site:

    Name of the content management site hosting the page

  • pagename:

    Name of the page being visited

  • pageurl:

    URL of the page being visited

    Note:

    • Be sure to tag pages that display the assets whose asset types are registered. If the pages remain untagged, empty reports will be generated. For registration procedures, see "Configuring an Asset Report" in the Oracle Fusion Middleware WebCenter Sites: Analytics Administrator's Guide.

    • If you are using the FirstSite II sample site, note that it uses a wrapper page that is called by all other pages. Add the data capture code (in this section) to the wrapper element (for example, ElementCatalog/FSIIWrapper). Do the same for any other site that uses a wrapper page. For any site that does not use a wrapper page, make sure that the c, cid, site and pagename parameters are properly passed from the page to the data capture code.

    • To enable generation of a site's "Entry - Exit Pages" report (which identifies a session's first and last pages), you can code either all pages on that site, or a wrapper page that is called by all other pages.

For each page request, the FatWire/Analytics/AddAnalyticsImgTag invokes the sensor servlet in Analytics to capture data on visitors browsing the page. The data includes visitors' geographic locations, IP addresses, browsing technologies, and session parameters. The remaining code captures usage information on WebCenter Sites assets displayed on the same page. The captured data is later processed statistically. The statistics are then available for "General Information" reports, "Content Information" reports, and "User Information" reports.

6.1.2 Enabling Data Capture for the "Internal Searches" Report

Enable data capture for "Internal Searches" report by calling the HTML img tag on every page where search data must be captured. Pass the following parameters:

<img
style="display:none;"
height="1"
width="1"
border="0"
src="<%=statisticsUrl%>
?siteName=<%= ics.GetVar("site")%>
&objType=SEARCH
&query=<SQL_query>
&objID=1
&directhits=<number_of_results>
&maxscore=<relevance_score>
&sessionID=<%=sessionId%>"
alt="pixel"
/>

Parameters

  • src

    URL of the data capture servlet for Analytics. The URL is configured in the analytics.datacaptureurl property, in futuretense.ini. Get the URL as follows:

    <property:get param="analytics.datacaptureurl" inifile="futuretense.ini" varname="datacaptureurl"/>
<% String statisticsUrl=
  ics.GetVar("datacaptureurl");%>

  • siteName

    Name of the content management site where the query is entered.

  • objType

    Object name for the internal SQL query. The value must be SEARCH.

  • query

    The query that is entered in the search field.

  • objID

    A random value (pass a value of "1").

  • directhits

    Number of results returned by the search query.

  • maxscore

    (Optional) the relevance score of the most relevant result.

    For example, 88.0 for a result that is 88% relevant to the keywords entered.

  • sessionID

    Browser session ID.

Example:

The following example shows how the img tag could look after the variables are replaced:

<img
style="display:none;"
height="1"
width="1"
border="0"
src="http://10.120.12.68:7001/analytics/statistics
?siteName=FirstSiteII
&objType=SEARCH
&query=Select * from Activities
&objID=1
&directhits=10
&maxscore=88.0
&sessionID=5E7B9B22F84F0FAB0E68108089AA1609"
alt="pixel"
/>

If your pages contain Engage assets and you wish to enable data capture, continue with Section 6.1.3, "Enabling Data Capture for Engage Reports." Otherwise, you have completed configuring Analytics. Test the system by following the steps in Section 6.2, "Testing Your Analytics Installation."

6.1.3 Enabling Data Capture for Engage Reports

Engage assets include recommendations, recommended assets (advertised in the recommendations), and segments to which the recommendations are made. Before starting the steps in this section, familiarize yourself with their general flow by referring to the steps in Figure 6-1. The same figure provides examples of Engage assets and their counterpart objects RecAsked and RecListed.

Note:

Data capture on segments is implicit via the segID parameter in the img tag, used to enable data capture.

Figure 6-1 Definitions of Engage Assets

Description of Figure 6-1 follows
Description of "Figure 6-1 Definitions of Engage Assets"

Note:

To complete the steps below, you must have a thorough understanding of recommendations and segments, as well as experience with Java and JSP.

To enable data capture on Engage assets

  1. Enable data capture on each recommendation (for an example of a recommendation, see Figure 6-1):

    1. Add the lines below to the recommendation's element:

      <%@ taglib prefix="property" uri="futuretense_cs/property.tld"%>
<%@ page import="java.util.*, java.text.*, java.io.*"%>
<%@ page import="at.onetoone.esa.tools.*"%>

      Note:

      The at.onetoone.esa.tools files are located in analyticscs.jar.

    2. Insert the HTML img tag below into the recommendation's element. The img tag will capture the ID and name of the recommendation as soon as the page is displayed to the visitor.

      Note:

      If you are using the FirstSite II sample site, add the img tag to ElementCatalog/AdvCols/FSIIDetail.

      <script type="text/javascript">

pixelreccalled = new Image();
      pixelreccalled.src = "<%=statisticsUrl%>?siteName
          =<%= ics.GetVar("site")%>
&objType=RecAsked&objID=<%=ics.GetVar("cid")%>
&objName=<%=ics.GetVar("reconame")%>

  &segID=<%=segmentidlist%>

  &sessionID=<%=sessionId%>

  &Referer=<%= referer %>

  &size=<%=screenResolution%>";
</script>
<noscript>
<img style="display:none;"
height="1"
width="1"
src="<%=statisticsUrl%>?siteName=<%= ics.GetVar("site")%>
&objType=RecAsked
&objID=<%=ics.GetVar("cid")%>
&objName=<%=ics.GetVar("reconame")%>
&segID=<%=segmentidlist%>
&sessionID=<%=sessionId%>
&Referer=<%= referer %>
&size=<%=screenResolution%>
alt="pixel" />
</noscript>

    Parameters

    • src

      URL of the data capture servlet for Analytics. The URL is configured in the analytics:datacaptureurl property, in futuretense.ini. Get the URL as follows:

      <property:get param="analytics.datacaptureurl" inifile="futuretense.ini" varname="datacaptureurl"/>

<% String statisticsUrl=
    ics.GetVar("datacaptureurl");%>

    • siteName

      Name of the content management site where the recommendation is displayed.

    • objType

      Object name for the displayed recommendation. The value must be RecAsked. (For an example of a recommendation, see the first step in Figure 6-1.) The objType is used to identify Engage assets (recommendations and segments), capture data on the assets, and create reports in the "Engage" report group.

    • objID

      Asset ID of the recommendation.

    • objName

      Name of the recommendation.

    • segID

      Either a comma-separated list of IDs of the segments to which the visitor belongs, or 0 if the visitor does not belong to a segment.

    • sessionID

      Browser session ID.

    • size

      Browser screen resolution.

    Example

    The following example shows how the img tag could look after the variables are replaced:

    <img
style="display:none;"
height="1"
width="1"
src="http://etravel.fatwire.com:80/analytics/statistics
?siteName =FirstSiteII
&objType=RecAsked&objID=1120593564193
&objName=FSIIItemOfTheWeek
&segID=0
&sessionID=B28822803C3843B8CC
&size=1280x1024"
alt="pixel"/>

  2. Enable data capture on each recommendation's list of recommended assets (for an example of such a list, see Figure 6-1).

    This step requires you to first encode three parameters, then insert the HTML img tag into the same recommendation element as in the previous step, but pass parameters which are specific to the list of recommended assets. Do the following:

    1. Encode the parameters objListName, objListID, and objListType as follows, using the Base64 file located in analyticscs.jar:

      String objListNameValue = Base64.encodeBytes(<comma-separated list of asset names in the recommendation>.getBytes(), Base64.DONT_BREAK_LINES);
String objListIDValue = Base64.encodeBytes(<comma-separated list of asset IDs in the recommendation>.getBytes(), Base64.DONT_BREAK_LINES);
String objListTypeValue = Base64.encodeBytes(<comma-separated list of asset types in the recommendation>.getBytes(), Base64.DONT_BREAK_LINES);

    2. Insert the HTML img tag with the following parameters into the JSP:

      Note:

      If you are using the FirstSite II sample site, add the img tag to ElementCatalog\AdvCols\FSIIDetail.

      For example code, see FSIIDetail.jsp (in the following directory: FatWire Analytics\examples\FirstSiteII\ElementCatalog/AdvCols).

      <script type="text/javascript">

imagereclisted = new Image();

imagereclisted.src = "<%=statisticsUrl%>?siteName=<%
 = ics.GetVar("site")%>
 &objType=RecListed
 &objID=<%=ics.GetVar("cid")%>
 &objName=<%=ics.GetVar("reconame")%>
 &objListID=<%=objListIDValue%>
 &objListName=<%=objListNameValue%>
 &objListType=<%=objListTypeValue%>
 &segID=<%=segmentidlist%>
 &sessionID=<%=sessionId%>
 &size=<%=screenResolution%>";
</script>
<noscript>

<img style="display:none;"
height="1"
width="1"
src="<%=statisticsUrl%>
?siteName=<%= ics.GetVar("site")%>
&objType=RecListed
&objID=<%=ics.GetVar("cid")%>
&objName=<%=ics.GetVar("reconame")%>
&objListID=<%=objListIDValue%>
&objListName=<%=objListNameValue%>
&objListType=<%=objListTypeValue%>
&segID=<%=segmentidlist%>
&sessionID=<%=sessionId%>
&size=<%=screenResolution%>"
alt="pixel"
/>

</noscript>

      Parameters

      • src

        URL of the data capture servlet for Analytics. The URL is configured in the analytics.datacaptureurl property, in futuretense.ini. Get the URL as follows:

        <property:get param="analytics.datacaptureurl" inifile="futuretense.ini" varname="datacaptureurl"/>

<% String statisticsUrl=
  ics.GetVar("datacaptureurl");%>

      • siteName

        Name of the content management site where the recommendation is listed.

      • objType

        Object name for the list of recommended assets. The value must be RecListed. (For an example of a list of recommended assets, see the second step in Figure 6-1.) The objType is used to identify Engage assets (recommendations and segments), capture data on the assets, and create reports in the "Engage" report group.

      • objID

        Asset ID of the recommendation.

      • objName

        Name of the recommendation.

      • objListName

        Comma-separated list of asset names in the recommendation. The value for this parameter is the value that was encoded in the previous step.

      • objListType

        Comma-separated list of asset types in the recommendation. The value for this parameter is the value that was encoded in the previous step.

      • segID

        Either a comma-separated list of IDs of the segments to which the visitor belongs, or 0 if the visitor does not belong to a segment.

      • sessionID

        Browser session ID.

      • size

        The browser screen resolution.

      Example:

      The following example shows how the img tag could look after the variables are replaced:

      <img
style="display:none;"
height="1"
width="1"
src="http://etravel.fatwire.com:80/analytics/statistics
?siteName=FirstSiteII
&objType=RecListed
&objID=1120593564193
&objName=FSIIItemOfTheWeek
&objListID=MTEzODY2MDI1NjExMQ===
&objListName=Q2hvY29ob2xpYyBXZWVrZW5k=
&objListType=UHJvZHVjdF9D=
&segID=0&sessionID=B28822803C3843B8CC496743D5B132B0
&size=1280x1024"
alt="pixel"
/>

    3. Add the recid parameter to the element that generates the links which make up the list of recommended assets (each link points from the recommendation to a recommended asset). Also, add the recid parameter to the pagecriteria variable for the element's SiteCatalog entry.

      Note:

      recid is the ID of the recommendation to which an asset belongs. For example code, see FSIISummary.jsp for Product_C (in the following directory: FatWire Analytics\examples\FirstSiteII\ElementCatalog\Product_C).

  3. Enable data capture on each recommended asset (for an example of a recommended asset, see Figure 6-1):

    1. If the data capture code from Section 6.1.1, "Enabling Data Capture for General, Content, and User Information Reports" does not exist in the recommended asset's JSP, add the code.

      Note:

      Data capture code can exist on a page displaying an Engage asset if that page was already coded for data capture on WebCenter Sites assets.

    2. Pass the recid parameter to the data capture element "FatWire/Analytics/AddAnalyticsImgTag" by inserting the following line into the data capture code in Section 6.1.1, "Enabling Data Capture for General, Content, and User Information Reports":

       <render:argument name="recid" value='<%=ics.GetVar
      ("recid")%>'/

      This enables Analytics to record which Engage asset has been selected.

  4. At this point, you have enabled data capture for each recommendation, its list of recommended assets, and its individual recommended assets. You have also implicitly enabled data capture for segments, via the segID parameter in the img tags.

    Continue to the next step to test your installation.

6.2 Testing Your Analytics Installation

You can test your code by testing your Analytics installation either on your own or with the help of the WebCenter Sites administrator and other users.

To test your Analytics installation

  1. Go to the web site and visit the pages you have tagged for data capture.

  2. Allow the data analysis jobs to finish processing the captured data.

    Note:

    The data analysis jobs process data that was captured within the past 24 hours. Bear in mind that a data analysis job is a resource-intensive process that can take a significant amount of time to complete, depending on the amount of raw data that was captured.

  3. Generate all the reports that users will be generating. For descriptions of the reports and instructions on generating them, see the Oracle Fusion Middleware WebCenter Sites: Analytics User's Guide.

Assuming a successful outcome, you are now ready to use Analytics.