This chapter covers the following topics:
Oracle Web Analytics is pre-integrated with Oracle E-Business Suite applications, like Oracle iStore, to track user activities in those applications and report on the same. Oracle Web Analytics can also be used to track and report on user activities in non-Oracle E-Business Suite Web sites and applications. This chapter details the implementation steps required to use Oracle Web Analytics for tracking of user activities in non-Oracle E-Business Suite Web sites.
Following is the high-level process for implementing the Oracle Web Analytics integration with third-party Web sites.
Step 1 - Enable Page Tracking
Step 2 - Publish Tracking Attributes
Step 3 - Publish Business Events
Step 4 - Set Up Privacy Preference
The following three JavaScript files are needed to track page access:
ibwTrackingConfig.js: This file contains configuration variables that need to be customized for the Web site. The variables are provided in the table below.
ibwTrackingFunction.js: This file contains the tracking JavaScript code that will run every time the page is displayed on a browser. This file may change from version to version and hence should not be customized.
ibwTrackingMain.js: This file includes the two files above.
Supplied by Oracle Web Analytics, these three files are present in the folder, <APPLICATION TOP>/html/, of an Oracle E-Business Suite instance. Copy these files over to the Web site being tracked.
Each page in the Web site to be tracked should contain the following line at the bottom of the page:
<script src="<path>/ibwTrackingMain.js”></script>
Example: If <path> is /admin for example, the actual line will be:
<script src="/admin/ibwTrackingMain.js”></script>
The following tables shows the JavaScript variables whose value you need to set in the file, ibwTrackingMain.js.
| Name | Description | Value |
|---|---|---|
| waAbsolutePath | This variable should be the absolute server path to access the ibwTrackingConfig.js and ibwTrackingFunctions.js files | <host>:<port>/<path>, where host and port correspond to the non-Oracle E-Business Suite instance. |
The following table shows the JavaScript variables whose values you need to set in the file ibwTrackingConfig.js.
| Name | Description | Value |
|---|---|---|
| WaServletUrl | Web Analytics Servlet URL over HTTP. The servlet will receive tracking requests from non-secure pages which have included JavaScript files provided by Web Analytics. | Value of the profile option, Apps Servlet Agent, plus the value of the profile option, Web Analytics: Relative Servlet URL for Tracking Cached Pages Example: http://host:port/OA_HTML/ibwTrackingServlet |
| waSecuredServletUrl | Web Analytics Servlet URL over HTTPS | The ibwTrackingServlet entry point in SSL enabled environments |
| waEnableTracking | Flag to enable or disable tracking | Y or N |
| waInstanceIdentifier | A unique string for the Web Analytics instance. This variable is used to name cookies to prevent multiple Web Analytics instances the same domain (e.g., a test environment and a production environment) overwriting cookies. | Value of the profile option, Applications Database ID |
| waEnableDebug | Flag to enable or disable debugging of client-side scripting. If enabled, any tracking errors will be sent to the Web Analytics servlet. | Y or N |
| waDomains | Array to store multi-domain PrivacyPreferenceServlet URL; this is only the definition; the value of this variable doesn’t need to be set in this file. See the section about setting up the privacy policy for the appropriate values. | n/a |
This is an optional step that can provide additional tracking information to the tracking engine.
JavaScript accepts certain parameters which can be exposed as JavaScript variables within Script tags in the output page. The output page refers to the third-party Web pages to be tracked. The Script tag containing the JavaScript variables can be placed anywhere in the output page. The following table lists the supported variables.
| Name | Description | Allowed Values |
|---|---|---|
| waPageCode | Variable containing the Page Code | Any value |
| waPageName | Variable containing the Page Name | Any value -- Oracle Web Analytics uses the following rules to identify Page Name:
|
| waSiteCode | Variable containing the Site Code | Site Code of the current page if already set up |
| waFwdPage | Variable containing forwarded URL in the case of a server-side forwards | The URL that is being rendered on the screen; this can be populated if the page rendered is different from what the user sought in the previous page; normally this situation occurs in the case of a server-side forwards. |
| waContext | Variable containing context type and context ID for a page (separated by the period character (.) | Any valid value for the context ID Example: <script language>=”JavaScript”waContext =’SECTION:1002’</script> |
| waInventoryOrg | Variable containing the Inventory Organization ID of a product | The Inventory Organization ID of the product being published; this variable should be defined for product context Example: <script language>=”JavaScript” waInventoryOrg = ‘ORCL’</script> |
Note: All of these variables are optional attributes that can be published for tracking purposes.
Sites need to publish Business Events just like publishing other attributes for tracking. Oracle Web Analytics supplies the waEvent variable for capturing Business Events. The value of the Event variable should adhere to the syntax mentioned in this section.
| Parameter | Description | Allowed values |
|---|---|---|
| waEvent | Variable containing Event | Values mentioned for each Event, adhering to the syntax mentioned in the following section |
Oracle Web Analytics tracks three kinds of events:
Inquiries
Order Inquiries
Payment Inquiries
Invoice Inquiries
Site Search
Registration
Event: [ Event Attribute Name{=Event Attribute Value}]
Where:
Brackets [ ] indicate zero or more
Braces { } indicate 0 or 1
Also, ‘Event’ should be one of the values in the second column of the below table and ‘Event Attribute Name’ should be one of the values in the third column of the below table. The ‘Event Attribute Value’ could be anything that will have a meaning.
Example 1:
<script language=”JavaScript”>var waEvent=’ORDINQ:ORDID=219029’;</script>
Example 2:
<script language=”JavaScript”>var waEvent=’SRCH:SRCHSTR=Webanalytics:SRCHSIZE=10:SRCHMORE’;</script>
Oracle Web Analytics understands the following Events and Event Attribute Values:
| Event | Event Code | Event Attribute Name | Event Attribute Value |
|---|---|---|---|
| Order Inquiry | ORDINQ | ORDID | Order ID of the order queried |
| Payment Inquiry | PMTINQ | PMTID | Payment ID or equivalent of the payment queried |
| Invoice Inquiry | INVINQ | INVID | Invoice ID of the invoice queried |
| Site Search Event This Event should be exposed only when search was performed and not when user is clicking on next link to browse the search results. |
SRCH | SRCHSTR | Value of the search string |
| SRCHSIZE | Number of hits for this search string | ||
| SRCHMORE | N/A This attribute should used if the SRCSIZE is more than what is being displayed. |
||
| User Registration | USRREG | N/A | N/A |
To ensure that Oracle Web Analytics is able to track Oracle Single Sign-On (SSO) authenticated visitors, the Oracle SSO Server and Oracle Web Analytics tracking servlet need to share the same lowest common domain.
As a one-time implementation step, implementers must do the following to let Oracle Web Analytics understand the Login Event. This event is needed so that Oracle Web Analytics can honor the authenticated user privacy preference and identify the authenticated users for tracking purposes.
For third-party sites, implementers should follow these steps to publish the Login Event for Web Analytics.
Step 1 - Follow the steps for implementing the IPASCustomCookieInterface in the Third-Party Integration Modules in Oracle Application Server Single Sign-On Administrator’s Guide.
Step 2 - Use the source code provided below to create the class file and deploy according to the Step 1.
import java.io.IOException;
import java.net.MalformedURLException;
import java.net.URLConnection;
import java.net.URL;
import java.util.StringTokenizer;
import java.util.HashMap;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.Cookie;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.InputStream;
import oracle.security.sso.ias904.toolkit.IPASUserInfo;
import oracle.security.sso.ias904.toolkit.IPASCustomCookieInterface;
public class CustomCookie implements IPASCustomCookieInterface
{
private static String shortCookieDomain = null;
public Cookie[] getCustomCookie(IPASUserInfo user, HttpServletRequest req)
{
/*<-- OWA SSO LOGIN IMPLEMENTATION: Start -->*/
/*
* Value of this variable should be changed according to the implementation.
* The value of the profile ‘Applications Database ID’
*/
String instanceIdentifier = "";
/*
* Value of this variable should be changed according to the implementation.
* Value of the profile ‘Apps Servlet Agent’ + Value of the profile ‘Web Analytics: Relative
* Servlet URL for Tracking Cached Pages’
* Ex:
* “http://host:port/OA_HTML/ibwTrackingServlet”
*/
String servletURL = "";
/*<--- Don't change the code from here ---->*/
Cookie[] cookieList = req.getCookies();
Cookie visitCookie = null;
Cookie visitorCookie = null;
StringBuffer sbVisit = new StringBuffer("ORA_IBW_VT_");
sbVisit.append(instanceIdentifier);
StringBuffer sbVisitor = new StringBuffer("ORA_IBW_VR_");
sbVisitor.append(instanceIdentifier);
//Get the existing OWA cookies if present
if (cookieList != null)
{
for (int i = 0;i<cookieList.length ;i++ )
{
Cookie cookie = cookieList[i];
if (sbVisit.toString().equals(cookie.getName()))
{
visitCookie = cookie;
}
else if (sbVisitor.toString().equals(cookie.getName()))
{
visitorCookie = cookie;
}
if (visitCookie != null && visitorCookie != null)
{
break;
}
}
}
//Send the data to OWA tracking servlet and get an appropriate response
StringBuffer urlString = new StringBuffer(servletURL);
urlString.append("?ty=5$guid=");
urlString.append(user.getUserGUID());
if (visitCookie != null)
{
urlString.append("$vtc=");
urlString.append(visitCookie.getValue());
}
if (visitorCookie != null)
{
urlString.append("$vrc=");
urlString.append(visitorCookie.getValue());
}
StringBuffer outputFromServlet = null;
try
{
URL url = new URL(urlString.toString());
URLConnection conn = url.openConnection();
if (conn == null)
{
return null;
}
conn.setDoOutput(false);
conn.setRequestProperty("referer",req.getRequestURL().toString());
InputStream inputStream = conn.getInputStream();
BufferedReader rd = new BufferedReader(new InputStreamReader(inputStream));
String line;
while ((line = rd.readLine()) != null)
{
if (outputFromServlet == null)
{
outputFromServlet = new StringBuffer();
}
outputFromServlet.append(line);
}
rd.close();
}
catch (MalformedURLException ex)
{
return null;
}
catch (IOException ex)
{
return null;
}
if (outputFromServlet == null)
{
return null;
}
//Set the new cookies in the client browser.
StringTokenizer stringTokenizer = new StringTokenizer(outputFromServlet.toString(),"$");
Cookie newVisitCookie = null;
Cookie newVisitorCookie = null;
HashMap attribMap = new HashMap(10);
while (stringTokenizer.hasMoreTokens())
{
String cookieValue = stringTokenizer.nextToken();
if (cookieValue.indexOf("=") != -1)
{
attribMap.put(cookieValue.substring(0,cookieValue.indexOf("=")),cookieValue.substring(cookieValue.indexOf("=") + 1,cookieValue.length()));
}
}
if (attribMap.get("vtc") != null)
{
newVisitCookie = new Cookie(sbVisit.toString(),(String)attribMap.get("vtc"));
newVisitCookie.setPath("/");
newVisitCookie.setDomain(getLowestCommonDomain(req));
}
if (attribMap.get("vrc") != null && attribMap.get("vrp") != null)
{
int age = 0;
try
{
age = Integer.parseInt((String) attribMap.get("vrp"));
}
catch (NumberFormatException ex)
{
//exception we shouldnt set visitor cookie
}
if (age != 0)
{
newVisitorCookie = new Cookie(sbVisitor.toString(),(String)attribMap.get("vrc"));
newVisitorCookie.setPath("/");
newVisitorCookie.setDomain(getLowestCommonDomain(req));
newVisitorCookie.setMaxAge(age);
}
}
Cookie[] retVal = new Cookie[2];
if (newVisitCookie != null)
{
retVal[0] = newVisitCookie;
}
if (newVisitorCookie != null)
{
retVal[1] = newVisitorCookie;
}
return retVal;
}//END getCustomCookie
//Get the lowest common domain
public String getLowestCommonDomain(HttpServletRequest request)
{
if (shortCookieDomain == null) {
String server = request.getServerName();
int dot1 = server.lastIndexOf(".");
String topdomain = server.substring(dot1+1);
if (topdomain.equalsIgnoreCase("com") ||
topdomain.equalsIgnoreCase("edu") ||
topdomain.equalsIgnoreCase("net") ||
topdomain.equalsIgnoreCase("org") ||
topdomain.equalsIgnoreCase("gov") ||
topdomain.equalsIgnoreCase("mil") ||
topdomain.equalsIgnoreCase("int")) {
int dot2 = server.lastIndexOf(".", dot1-1);
if (dot2 == -1)
shortCookieDomain = server;
else
shortCookieDomain = server.substring(dot2);
}
else {
int dot2 = server.lastIndexOf(".", dot1-1);
int dot3 = server.lastIndexOf(".", dot2-1);
if (dot3 == -1)
shortCookieDomain = server;
else
shortCookieDomain = server.substring(dot3);
}
}
return shortCookieDomain;
}
/*<-- OWA SSO LOGIN IMPLEMENTATION: End -->*/
The Logout Event from the Oracle SSO Server must also be understood by the Oracle Web Analytics servlet to end the visit of the user. Hence, this event should be communicated to the Oracle Web Analytics servlet.
For third-party sites, implementers should follow these steps to publish the Logout Event for Web Analytics.
Step 1 - Follow the steps for customizing the logout page for the Oracle SSO Server as mentioned in the SSO documentation
Step 2 - Customize the Logout page to embed an image that will allow the Oracle Web Analytics servlet to track the Logout Event. This image tag should be like this:
<img height=0 width=0 border=0 src=”http://externalsite.xyz.com/servlets/ExtSiteTrckngSrvlt?ty=2$tj=<random number>”/>
Where:
src should be equal to the URL where Web Analytics servlet has been deployed, which is the value of the profile option, Apps Servlet Agent, plus the value of the profile option, Web Analytics: Relative Servlet URL for Tracking Cached Pages
URL parameter (query string) should be the way it is mentioned in the SSO documentation
<random number> could be the current system time or any number so that browser doesn’t consider the image tag from its cache
Oracle Web Analytics supports allowing users to communicate their privacy preference, to opt-in or opt-out of being tracked. In third-party Web sites, several steps are required to implement the functionality. For an introduction to the privacy policy and privacy preference in Oracle Web Analytics, see the "Privacy Policy" section of the chapter, Administering Tracking Features.
This guide assumes that implementers are going to provide their own Privacy Statement page, which will contain a hyperlink to the Oracle Web Analytics Privacy Preference page.
Web Analytics ships a JSP for the privacy preference display: ibwCWadPrivacyPref.jsp.
Since the blocking cookie (which tells Oracle Web Analytics to not track an anonymous user) is limited to storing only one domain, cookies established at the other domains have stale data. This can result in the dishonoring of the user’s privacy preference, since the user might still be tracked on some of the sites even though his preference was not to be tracked or vice versa.
Example: A user is currently opted out and the cookies in all the domains have proper data. If he elects to “Opt In” on the Privacy Preference page, the blocking flag in one domain gets removed, but the cookies in all the other domains are not updated. So when this user visits any other site (different domain), he would not be tracked by Oracle Web Analytics (as the cookie in that domain has the blocking flag).
Following is a summary of the steps that must be performed to address the cookies in multiple domains issue:
To synchronize the cookie in all the different domains, implementers should have some server-side component in every application server hosting the different domains.
Implementers should deploy a servlet to update the cookies in the domain different from that of the Oracle E-Business Suite. The following code should be compiled for the servlet (this servlet is referred to as "PrivacyPreferenceServlet".)
import java.io.UnsupportedEncodingException;
import java.net.URLDecoder;
import java.util.StringTokenizer;
import javax.servlet.http.Cookie;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
/*
* This servlet should be deployed in the application servers hosting 3rd party site
* in multi domain scenario. This will update the visitor cookie for the block flag
* in that domain
*/
public class PrivacyPreferenceServlet extends HttpServlet
{
public PrivacyPreferenceServlet()
{
}
public void doPost(HttpServletRequest request, HttpServletResponse response)
{
doGet(request, response);
}
public void doGet(HttpServletRequest request, HttpServletResponse response)
{
String queryString = request.getQueryString();
boolean userPref = false;
String instanceId = null;
if (queryString == null)
{
return;
}
String preference = request.getParameter("op");
if (preference != null)
{
userPref = "Y".equals(preference);
instanceId = request.getParameter("instanceIdentifer");
}
else
{
//The querystring is not proper hence returning without setting the cookie
return;
}
if (instanceId == null)
{
//The querystring is not proper hence returning without setting the cookie
return;
}
Cookie[] cookieList = request.getCookies();
if (cookieList != null)
{
for (int index = 0; index < cookieList.length; index++)
{
if (cookieList[index].getName().equals("ORA_IBW_VR_" + instanceId))
{
//Found the cookie
String cookieContent = URLDecoder.decode(cookieList[index].getValue());
StringTokenizer cst = new StringTokenizer(cookieContent, "~");
String visitorId = cst.nextToken();
cookieList[index].setValue(visitorId + ((userPref)?"~Y":"~N"));
cookieList[index].setPath("/");
response.addCookie(cookieList[index]);
return;
}
}
}
//Cookie was not found hence not updating anything
}
}
To deploy the servlet, implementers should follow the steps particular to the application server being used.
If creating an equivalent server-side component due to restrictions in their application server, implementers should follow the logic or programming steps mentioned below:
There will be two parameters sent in the request header:
op: This parameter specifies the user's option. Y = opted out; N = opted in.
instanceIdentifer: This is a string which identifies the unique instance of Web Analytics. This value will be equivalent to the value configured in the section, "Step 1 - Enable Page Tracking", above.
If either of these parameters is null or empty, Web Analytics won't perform anything, and exits.
If both parameters are present, Web Analytics will search the request header for the cookie whose name is ORA_IBW_VR_ concatenated with the instanceIdentifier string.
If the cookie doesn’t exist, Web Analytics won't perform anything, and exits.
The cookie content could be either of the following two formats: ‘a’~Y or ‘a~N’.
Web Analytics splits the cookie content string based on ‘~’ as the separator if it is in the earlier format.
Now the new cookie content will be either:
a if op = N
a~Y if op = Y
Web Analytics sets this new cookie content in the response and exits.
Implementers must add a list of all the domains where the above server-side component can be reached in the array mentioned in the table in the section, "Step 1 - Enable Page Tracking", above. The sample HTML code given below represents the same:
//List of domains where the PrivacyPreferenceServlet is deployed
waDomains[0] = 'http:\/\/web.xyz.com\/servlet\/PrivacyPreferenceServlet’;
waDomains[1]= 'http:\/\/store.abc.com\/servlet\/PrivacyPreferenceServlet’ ;
waDomains[2]= 'http:\/\/site.pqr.com\/servlet\/PrivacyPreferenceServlet’;