Tracking Agent Configuration

Contents


Configuring Data Collection for Anonymous Users

CardioLog can identify anonymous users by their workstation IP address, or by creating a unique id and storing it in a browser cookie.

Using unique ID

Pros - The most accurate method for identifying unique anonymous users, even when using proxy/VPN.
Cons -  When a visitor deletes his cookies, the next visit will generate a new unique ID. When cookies are disabled, each visit generates a new unique ID. When a visitor uses multiple browsers, such as Internet Explorer and Firefox, a unique ID will be generated for each browser.
 
 
Perform the following steps in order to configure data collection for anonymous users, using a unique ID:
  1. In [Installation directory]\CardioLogAgent\js\AgentEmbed.js, set the “SupportAnonymousUsers” parameter to “true”:

    In versions lower than 2.0.8.0
    In [Installation directory]\CardioLogAgent\AgentEmbed.aspx, set the “SupportAnonymousUsers” parameter to “true”:

    element.SupportAnonymousUsers = true;
  2. In the file system, verify that the [Installation directory]\CardioLogAgent directory security allows access for anonymous users:
     
    Right click the [Installation directory]\CardioLogAgent directory, choose Properties > Security > Add > Add the ANONYMOUS LOGON user.
  3. In IIS, verify that the CardioLogAgent web application directory security allows Anonymous Access:

    Click the CardioLogAgent web application in IIS, choose Authentication, enable Anonymous Authentication and disable Windows Authentication.
  4. In [Installation directory]\CardioLogAgent\Web.config, set the “overwriteConnectedUser” parameter to “true”:

    <add key="overwriteConnectedUser" value="true" />

Note: by default, the user name will be a unique id in the following format - "Anonymous_XXXX" 

[Installation directory] - by default, the CardioLogAgent folder is located in the CardioLog Installation folder. If the "CardioLog Analytics" SharePoint feature is installed, the CardioLogAgent folder is located on all SharePoint WFEs under the SharePoint website "_layouts" folder.

Using IP address

Pros - Enables individual IPs in reports - works when browser cookies are disabled.
Cons - When using a proxy/VPN in order to access the internal network, the CardioLog tracking agent will not be able to obtain the client workstation IP, and the registered IP will be the proxy IP. In this case the unique users metric is inaccurate. 
 
Note: CardioLog collects the workstation IP anyway, for geographic location.

Perform the following steps in order to configure data collection for anonymous users, using the workstation IP address:

  1. Follow the steps above for configuring data collection for anonymous users, using a unique ID.
  2. Edit  [CardioLog Installation Folder]\EventCollector\web.config and set the value of the "UseIPAddressForAnonymousUserName" key to "true":

    <add key="UseIPAddressForAnonymousUserName" value="true" />

Monitoring authenticated users in an Anonymous environment after they sign in

CardioLog can identify authenticated users in an anonymous environment by retrieving the user name from SharePoint or programmatically.

Getting the SharePoint signed in user

CardioLog can identify authenticated users in an anonymous environment by retrieving the signed in user in SharePoint.

In order to extend the tracking code to retrieve the user ID from SharePoint:
  1. Configure the tracking agent for Anonymous users.
  2. Edit the following key to the [Installation directory]\CardioLogAgent\web.config file under the <appSettings> section:
    <add key="UseSPAuth" value="true"/>
In versions lower than 2.0.8.0:
  1. Configure the tracking agent for Anonymous users.
  2. Add the following key to the [Installation directory]\CardioLogAgent\web.config file under the <appSettings> section:
    <add key="GetUserNameCustom" value=" function GetUsername() { __trace(&quot;GetUsername&quot;); var currentUsername = __readCookie(&quot;_userid&quot;); var currentUserId = __readCookie(&quot;spUserid&quot;); if (typeof(_spPageContextInfo) != &quot;undefined&quot;) { if (!currentUserId || currentUserId != _spPageContextInfo.userId) { currentUsername = null; __saveCookie(&quot;spUserid&quot;, _spPageContextInfo.userId, 1000, element.CookieDomain); } } var useridInput = this.document.getElementById(&quot;userid&quot;); if (useridInput &amp;&amp; useridInput.value != &quot;&quot;) { currentUsername = useridInput.value; } else if (currentUsername == null || currentUsername == &quot;&quot;) { if (typeof (getSPUserAccount) != &quot;undefined&quot;) { currentUsername = getSPUserAccount(); } else { currentUsername = &quot;Anonymous_&quot;+Math.random()*100000; } } __saveCookie(&quot;_userid&quot;, currentUsername, 1000, element.CookieDomain); __trace(&quot;GetUsername return: &quot;+currentUsername); return currentUsername; }"/>
  3. Add the following code to the [Installation directory]\CardioLogAgent\SP20XX_1.2.js file (10 for SharePoint 2010, 13 for SharePoint 2013), OR the [Installation directory]\CardioLogAgent\MOSS2007_1.2.js file (for MOSS 2007).
    [Installation directory] - by default, the CardioLogAgent folder is located in the CardioLog Installation folder. If the "CardioLog Analytics" SharePoint feature is installed, the CardioLogAgent folder is located on all SharePoint WFEs under the SharePoint website "_layouts" folder.
  4. Append the following code to the end of the file:

function normalizeSPUserAccount(userName) {
// return userName;
var splitedTokens = userName.split("|");
return splitedTokens[splitedTokens.length - 1].replace("&nbsp;", "");
}

//this function is used to retrieve user account for sharepoint online
function getSPUserAccount() {
var _current_user_name = "Anonymous_" + Math.random() * 100000;
var url = window.location.protocol + "//" + window.location.host;

if (typeof _spPageContextInfo !== "undefined") { //2010,2013,Online
url += _spPageContextInfo.webServerRelativeUrl;
}
else if (L_Menu_BaseUrl) { //2007
url += L_Menu_BaseUrl == "" ? "/" : L_Menu_BaseUrl;
}
url += "/_layouts/userdisp.aspx?Force=True&d=" + new Date().getTime();

var xmlhttp;
if (window.XMLHttpRequest) { // code for IE7+, Firefox, Chrome, Opera, Safari
xmlhttp = new XMLHttpRequest();
} else { // code for IE6, IE5
xmlhttp = new ActiveXObject("Microsoft.XMLHTTP");
}
xmlhttp.open("GET", url, false);
xmlhttp.send(null);
if (xmlhttp.statusText == "OK") {
try {
if (!(typeof __Page === 'undefined'))
var spenv = __Page.agent;
var strToSearch = '<td valign="top" class="ms-formbody" width="350px" id="SPFieldText">'; //2013,online
if (!(typeof spenv === 'undefined')) {
if (spenv.indexOf("2010") != -1)
strToSearch = '<td valign="top" class="ms-formbody" width="450px" id="SPFieldText">';
else if (spenv.indexOf("2007") != -1)
strToSearch = '<TD valign="top" class="ms-formbody" width="450px" ID="SPFieldText">';
}
var pos = xmlhttp.responseText.indexOf(strToSearch);
if (pos >= 0) {
var dispnamePropertiesHtml = xmlhttp.responseText.substring(xmlhttp.responseText.indexOf(strToSearch) + strToSearch.length, xmlhttp.responseText.length);
dispnamePropertiesHtml = dispnamePropertiesHtml.toLowerCase();
dispnamePropertiesHtml = dispnamePropertiesHtml.substring(0, dispnamePropertiesHtml.indexOf('</td>') - 5);
dispnamePropertiesHtml = dispnamePropertiesHtml.substring(dispnamePropertiesHtml.indexOf('-->') + 3, dispnamePropertiesHtml.length);
_current_user_name = normalizeSPUserAccount(dispnamePropertiesHtml.trim());
}
} catch (ex) {
__trace(ex.message);
}
}
if (!_current_user_name || _current_user_name == "") {
_current_user_name = "Anonymous_" + Math.random() * 100000;
}
return _current_user_name;
}

Getting the user id programmatically

CardioLog can identify authenticated users in an anonymous environment by retrieving the user name programmatically from a unique element value that is hidden in the client side code.

In order to extend the tracking code to retreive the user ID programmatically:

  1. Configure the tracking agent for Anonymous users.
  2. Pass the user's account name through SharePoint's server side code to a hidden element called "userid" in the client side code:

<input type="hidden" id="userid" name= "userid" value="DOMAIN\useraccountname">

For example, you can retrieve the user name from the _spUserId JavaScript global variable in SharePoint.
To verify this variable exists in your SharePoint pages, browse to a SharePoint page and enter javascript:alert(_spUserId) in the browser address bar. Verify that you see a popup with a valid Id number.

Configuring the Tracking Agent with SSL

The CardioLog tracking agent can be easily configured to work with SSL.

Upon activating CardioLog, the Configuration Wizard will be displayed. This wizard will help you configure the Tracking Agent - a tool designed to monitor visitor behavior in SharePoint.

In order to configure the tracking agent to work with SSL, perform the following steps:

  1. In IIS, configure the CardioLog web site to enable both http and https calls (set an SSL port and add a server certificate) 
  2. In Step 2 of the Configuration Wizard, click Show Advanced Settings and check Require secure channel (SSL)

Alternatively, do one of the following instead (in order to avoid possible authentication prompt or browser security messages when working with SSL):

  1. In Step 2 of the Configuration Wizard, install the "CardioLog Analytics" SharePoint feature.
  2. Skip Step 2 of the Configuration Wizard and manually install the Tracking Agent web application on the SharePoint machine (perform the following steps for every WFE):
    • Create a CardioLogAgent folder under the SharePoint _layouts folder:

      "_layouts" folder location on MOSS 2007:
      C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\TEMPLATE\LAYOUTS\

      "_layouts" folder location on SharePoint 2010 and SharePoint 2013:
      C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\LAYOUTS\

    • Copy the installation files into the new folder from [CardioLog Installation Folder]\CardioLogAgent\.
    • Open IIS on the SharePoint machine, create a new virtual directory named CardioLogAgent under the SharePoint website "_layouts" folder, which points to the copied CardioLogAgent folder.
    • Set the following properties for the new virtual directory - ASP.NET 2.0, Integrated Windows Authentication. Verify that you can browse to  https://sharepointportal/_layouts/CardioLogAgent/AgentEmbed.aspx
    • Open the copied CardioLogAgent directory, open the web.config file and edit the following keys, located in the <appSettings> section:

      <add key="CardioLogAgentRoot" value="/_layouts"/> 

    • Edit the Java Script tracking code to change the Tracking Agent location.
      By default, the Java Script tracking code is embedded within a common Java Script file on your SharePoint WFEs -

      For MOSS 2007 only:
      C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\TEMPLATE\LAYOUTS\1033\core.js

      For SharePoint 2010 only:
      C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\LAYOUTS\1033\init.js

      For SharePoint 2013 only:
      C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\15\TEMPLATE\LAYOUTS\init.js

      The code is located at the end of the file, between these comments: "//Intlock tracking code start", "//Intlock tracking code end".

      ca.src='/_layouts/CardioLogAgent/ca.aspx?_random='+Math.random();

      tt.src='/_layouts/CardioLogAgent/AgentEmbed.aspx?env=[SharePoint version]&r='+Math.random()*100000;

       [SharePoint version]: MOSS2007, SP2010 or SP2013
    • Verify event collection.

      Click Ctrl+F12 or the "Agent Console" bookmark and wait for several seconds. Verify that you see the tracking agent console.
      To add the "Agent Console" bookmark to your browser, follow the instructions in http://cardiolog_server_name:port/CardioLog/Configuration/AgentConsoleBookmarklet.aspx (edit the CardioLog server name and port).

Configuring timeouts for the Tracking Agent

Setting a timeout for tracking usage data

The tracking agent web application passes on the usage information, via HTTP/S web requests, to the EventCollector web application - which writes the data into the CardioLog database.

To configure the timeout settings for the Tracking Agent when the EventCollector web application is not available, edit the following keys in [Installation directory]\CardioLogAgent\Web.config file (values are in milliseconds):

<!-- Timeout in case the EventCollector web application is not available (the default is 10 seconds).-->

<add key="requestTimeOut" value="10000" />

<!-- How long to wait before trying again to access the EventCollector web application (the default is one minute).-->
<add key="serverResponseTimeOut" value="60000" />

 [Installation directory] - by default, the CardioLogAgent folder is located in the CardioLog Installation folder. If the "CardioLog Analytics" SharePoint feature is installed, the CardioLogAgent folder is located on all SharePoint WFEs under the SharePoint website "_layouts" folder.

Setting a timeout for content personalization

Information about the visitor segments is downloaded to the client browser with each page request. The JavaScript code hides the content of the page, adds or modifies page elements and finally re-displays the page according to visitor segments.
In order to personalize the page content, the default timeout for loading the visitor segments information is 5 seconds.
To configure the timeout setting in case of a connection error, edit the following key in the JavaScript tracking code (value is in milliseconds):
var iignoreca = setTimeout(ignoreca, 5000); 

By default, the Java Script tracking code is embedded within a common Java Script file on your SharePoint WFEs -

For MOSS 2007 only:
C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\TEMPLATE\LAYOUTS\1033\core.js

For SharePoint 2010 only:
C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\LAYOUTS\1033\init.js

For SharePoint 2013 only:
C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\15\TEMPLATE\LAYOUTS\init.js

If the "CardioLog Analytics" SharePoint feature is installed, the Java Script tracking code is embedded within a Java Script file on your SharePoint WFEs -

For MOSS 2007 only:
C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\TEMPLATE\LAYOUTS\CardioLogAgent\CardioLogAgent.js

For SharePoint 2010 and SharePoint 2013 only:
C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\LAYOUTS\CardioLogAgent\CardioLogAgent.js

Configuring Session Idle Time

Visits (Sessions) are defined as the activity of one visitor within a single browser session. If a user is inactive on your site for 30 minutes or more, any future activity will be attributed to a new session. Users that leave your site and return within 30 minutes will be counted as part of the original session. 
To set the maximum idle time after which the session id is reset, edit the following key in [Installation directory]\CardioLogAgent\js\AgentEmbed.js file (value is in minutes):

element.SessionTimer = 30; // Renew session (in minutes)

[Installation directory] - by default, the CardioLogAgent folder is located in the CardioLog Installation folder. If the "CardioLog Analytics" SharePoint feature is installed, the CardioLogAgent folder is located on all SharePoint WFEs under the SharePoint website "_layouts" folder. 

Capturing Time on Site for Single-Page Visits

Time on site is calculated by adding up the time a visitor spends on a page for each page in the session, including the last page in the session.
Learn more about capturing time on site for single-page visits.

Fire "pulse" events every few seconds for continual recording

By default, CardioLog Analytics JavaScript tracking code fires “pulse” events every few seconds, until the visitor leaves the page either by navigating away from it or by closing the browser.  
These “pulse” events are then processed by the reporting engine to calculate the overall amount of time a visitor spends on a page in a more accurate way, including single-page and last-page visits.

To configure the "pulse" events time intervals, edit the following keys in [CardioLog Installation directory]\EventCollector\web.config file:

<!-- The starting interval (default 3 seconds) - the first ping event will be sent after a visitor spends 3 seconds on the page. -->
<add key="PingInterval" value="3000" />

<!-- The time taken from minimum to maximum interval (default 30 seconds) - ping events will be sent every 3 seconds in the first 30 seconds a visitor is on the page. -->
<add key="PingIntervalAscendTime" value="30000" />

<!-- The final interval (default 30 seconds) - ping events after a visitor spends 30 seconds on the page will be sent every 30 seconds. -->
<add key="PingIntervalMax" value="30000" /> 

Finding the optimal ping configuration to reduce traffic to the CardioLog server, and still get accurate visit duration reports, depends on a few factors - the amount of traffic and common user behaviour on the portal.

PingInterval - You can change this value to 5 seconds (which is still a reasonable "bounce" value), considering the time it takes to fully load the home page. 

PingIntervalAscendTime - You can change this value to 5-10 seconds.

PingIntervalMax - If the portal is a work tool for your end users, and they usually spend more than a minute on it, you can change this value to 60 seconds.

Measure the time between visits to different pages 

CardioLog Analytics can calculate time on site by measuring the time between visits to different pages on your site - meaning, for example, that if a visitor clicks on Page A at 11 A.M. and then on Page B at 11.05 A.M., the time spent on Page A will be reported as five minutes.
A "duration" event will be sent only when the visitor leaves the page and goes to another page, reducing traffic to the CardioLog server.

If a user only visits a single page, it may not be possible to determine the length of time the visitor spent on the site. Something has to occur to fire off the Java Script tracking code and that’s usually a click to go to another page.

To measure time on site with "duration" events and turn off "pulse" events, edit the following key in [Installation directory]\CardioLogAgent\js\AgentEmbed.js file:

element.Ping = false;

[Installation directory] - by default, the CardioLogAgent folder is located in the CardioLog Installation folder. If the "CardioLog Analytics" SharePoint feature is installed, the CardioLogAgent folder is located on all SharePoint WFEs under the SharePoint website "_layouts" folder. 

 

 

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.
Powered by Zendesk