With the CardioLog API you can:

Contents

CardioLog Client-Side API

The CardioLog tracking agent allows for a client-side API to send custom events, and easily monitor button and banner clicks, video plays, or interactions with other UI components. On any monitored page, you can call the following JavaScript functions:

The SendEvent JavaScript Function

This function allows you to send events via the client agent. The Agent uses AJAX (Asynchronous JavaScript And XML) to send the event to the server, and will not affect the user interaction with the page in any way.

Code sample for sending a page view event:


The SendEvent function accepts the following parameters:

Note: when calling the "SendEvent" function within a different frame from where it is defined, make sure to reference the frame object containing it. For example, by using parent.document.__Page.SendEvent()

Monitoring Banner Clicks

You can monitor clicks on UI elements such as banners, buttons, navigation menu entries, links, etc. In order to capture a click on a banner that links to an external site, make a call to the CardioLog SendEvent function before redirecting the user to the external destination page. IF the banner was implemented with simple HTML, you can insert this code:

<a href="http://www.google.comonclick="document.__Page.SendEvent('Visit', 'Banners > My Links > externalsite.com');"><img src="google_logo.gif"></a>

In our example, when a user clicks on the banner CardioLog will send an event of type "Visit" to the server, specifying which banner has been clicked by the user before redirecting to "externalsite" (ie., "Banners > My Links> externalsite.com"). We recommend defining a unique prefix for each group of UI components that will be displayed in reports (in this case, "Banners") .

How many times were my banners clicked? To see how many times your banners were clicked, use the Events report (chart or table), and select "Banners" in the Website Item field.

Who clicked on my banners? To see who clicked on your banners, use the Visitors by Events report (chart or table), and select "Banners" in the Website Item URL field.

Please note that CardioLog automatically tracks outbound links from SharePoint sites to external destinations. To see how many times your links were clicked, use the The CardioLog API report.

The SetReferrer JavaScript Function

When users navigate internal links, you can monitor both the referring navigation component such as banners or menu items, along with the referring page. The SetReferrer function allows you to set custom page referrer details that are sent to the CardioLog server via following events (using SendEvent).

Code Sample:

<a href="http://mysite/rnd/index.aspxonclick="document.__Page.SetReferrer('Banners > MySite > Research and Development');"><img src="rnd.gif"></a>

 The SetReferrer function accepts the following parameters:

Monitoring UI Referrers

In order to capture the referring UI component before redirecting the user, make a call to the CardioLog SetReferrer function. Assuming the banner was implemented with simple HTML, this is a code example:

<a href="http://mysite/rnd/index.aspxonclick="document.__Page.SetReferrer('Banners > MySite > Research and Development');"><img src="rnd.gif"></a>

How many visitors accessed my page through a UI referrer? To see how many visitors arrived on your page through your UI referrer, use the The CardioLog API report, and select the page in the Website Item URL field.

The SendGoal JavaScript Function

The SendGoal function allows for you to send JavaScript based goals via the client agent. The Agent uses AJAX (Asynchronous JavaScript and XML) to send the goal event to the server, and does not affect the user's experience with the page in any way.

Code Sample:

<input type="button" value="Signup to Newsletter" onclick="document.__Page.SendGoal(1);" />

 The SendGoal function accepts the following parameter:

Monitoring JavaScript Based Goals

In order to identify a JavaScript based goal, such as signing up for a newsletter, define the goal, and make a call to the CardioLog SendGoal function.

Assuming the signup button was implemented using simple HTML, the following code sample should work:

<input type="button" value="Signup to Newsletter" onclick="document.__Page.SendGoal(1);" />

Goal Reports: To monitor your goal progress, use the Goal reports, and select the relevant goal in the Visitor Segments > Goal field of the widget preferences.

Monitoring Internal E-Mail Campaigns Using the __referrer Parameter

The CardioLog Client-Side API supports identifying and monitoring external locations. You can use the _referrer parameter whenever you publish a link to your monitored environment and you wish to track the source of the referring page. This is most commonly used in email or social media. For example, if you have included an internal link in a promotional email add the __referrer parameter to track the number of users who visited your site via this link. Define a unique referrer name that will be displayed in reports, such as __referrer=email_promotion_Dec_2016 in order to display the link accordingly:

http://myportal/sites/rnd/default.aspx?__Referrer=email_promotion_Dec_2016

How many visitors arrived on my page through my email campaign? To see how many visitors arrived on your page through your email campaign, use the The CardioLog API report, and select the relevant page in the Website Item URL field.

CardioLog Server-Side API

By using the CardioLog Server-Side API, CardioLogAPI/Events.asmx web service, and the SendEvent method, you can send viewduration and search events, custom events, and track the URL of the referrer page.

The SendEvent Method

The SendEvent method in the CardioLogAPI/Events.asmx web service accepts the following parameters:

After the event is sent, the web service XML response will include the event identifier for future use, which you can later use to send events related to this event accordingly:

<agent>

 <log>

 <status id='0'>OK</status>

 <event id='211022'/>

 </log>

 </agent>

 In case of an error, the XML response will include the error description:

<agent>

<log>

 <status id='-1'>Invalid Path</status>

 </log>

 </agent>

Event Types

The SendEvent method supports four event types. The ID number is used in the Server-Side API. The Event Type Title is used in the Client-Side API.

To set the page referrer, use the following optional parameters to track the source of the page:

Referrer pages can be retrieved in CardioLog with the "Navigation" visual controls.

Search events can be viewed in CardioLog in the Onsite Searches report, popular search terms are displayed in the Onsite Search Phrases report.

Creating Custom Event Types

You can create custom event types and build custom reports using the CardioLog SDK. The custom event types can be used in the SendEvent function, for both Client-Side and Server-Side APIs. For example, if your website is a sales site and you wish to track each product sold, and then you can create a report on the number of items sold, and create a custom event type in CardioLog named "Items-Sold."

1. Add the custom event type to the CardioLog database by executing the following query against the CardioLog database:

INSERT INTO tab_event_type(id,description)

VALUES(100, 'Item-Sold')

GO

ID - must be 100 or higher
Description - event type title

2. Add the custom event type to the CardioLog tracking agent events array - edit the __eEvents array and add the custom event type in:

For MOSS 2007 only:
[CardioLog installation directory]\CardioLogAgent\MOSS2007_1.2.js

For SharePoint 2010 only:
[CardioLog installation directory]\CardioLogAgent\SP2010_1.2.js

For SharePoint 2013 only:
[CardioLog installation directory]\CardioLogAgent\SP2013_1.2.js

For SharePoint 2016 only:
[CardioLog installation directory]\CardioLogAgent\SP2016_1.2.js

Note: If you have implemented the Tracking Agent using the CardioLog Analytics SharePoint Feature on your WFE (Web Front End), edit the __eEvents array and add the custom event type accordingly:

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

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

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

For SharePoint 2016 only:
C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\LAYOUTS\CardioLogAgent\SP2016_1.2.js


__eEvents = {
Visit: { id: 0, name: "Visit" },
Leave: { id: 1, name: "Leave" },
Search: { id: 2, name: "Search" },
SearchResultItem: { id: 4, name: "SearchResultItem" },
SearchResultClick: { id: 5, name: "SearchResultClick" },
External: { id: 10, name: "External" },
Goal: { id: 20, name: "Goal" },
"Goal-Test": { id: 21, name: "Goal-Test" },
Test: { id: 22, name: "Test" },
Score: { id: 23, name: "Score" },
Ping: { id: 24, name: "Ping" },
Item-Sold: { id: 100, name: "Item-Sold" },
Unknown: { id: -1, name: "Unknown" }
};

3. Implement the call to the SendEvent function when an item is sold (using our Client-Side API or Server-Side API).

4. Create a custom report to display the number of items sold using the CardioLog SDK.

Non-Browser (Mobile) Apps

Mobile apps and other non-browser apps don't contain HTML pages, therefore, developers must determine when their apps should trigger page view requests. CardioLog Analytics can then aggregate this data in reports to display page views, unique visitors, session length, bounce rates, etc. This data gives insight into how users interact with the client app.

Developers can also track visitor actions that don't correspond directly to page views using other Event types. These user actions can include views of embedded videos, button clicks, downloads and more. This data can then be used to understand which features are most popular, and make informed decisions about the features that should be prioritized for further development.

The REST API

In order to track visitor actions for non-browser apps, developers must send usage event objects to the CardioLogAgent web application through HTTP POST requests in JSON format. The JSON string must be embedded in the request body. The POST response is provided in JSON format as well.

The Event Object

CardioLog Analytics usage event objects have the following properties:

In addition to event objects, the request body may include the following properties:

The JSON request format

The full JSON request format is as follows:

{
    "events": {
      "event": [
        {
          "u": "http://www.intlock.com/",
          "X": "|referral|blog.intlock.com|/about/||",
          "et": 0,
          "RI": 564940
        },
        {
          "X": "1",
          "Y": "7",
          "et": 23,
          "RI": 0
        }
      ]
    },
    "browserType": "Apple-iPhone5C2/1001.525",
    "sessionid": "861529144.325047542",
    "un": "INTLOCK\\tomj"
}

The API URL

The API URL for a SharePoint site is:

https://[SharePoint WFE]/_layouts/CardioLogAgent/tunnel.aspx?random= 895.3324414324015

Data Export API

With the Data Export API you can develop client applications to retreive data from the CardioLog reporting engine, and refine the results of the request using query parameters. It allows for more flexibility and customization than the CardioLog UI, giving you a great deal of freedom over how to display your reports, in terms of their design, filters and data content, and where the reports are displayed. It's also possible to brand your data with your organization's colors and logos to really take ownership of it.

The CardioLog reporting engine generates the report in XML format and as a chart image.

Use the Reports API Helper to generate a URL which can be embedded in a client application. When calling this URL the report will be generated based on the selected parameters.

  1. Browse: http://<cardiolog_server>:<port>/CardioLog/CLReport/ReportsAPIHelper.aspxYour browser may not support display of this image.
  1. Select a Report.
  2. Select the report parameters - Date RangeTime IntervalWebsite Item, Users and Groups
  3. Check Generate Chart Image to create an image and set its Width and Height (pixels).
  4. Click Get URL to generate the report URL
  5. Click Generate Report to generate the report.
  6. Click Show Advanced Options  and Get Report Preferences to modify report preferences.

The CardioLog Report XML Schema

The CardioLog report XML contains a preferences section (prefs node), and a data section (data node).

Chart

The chart x-axis values are displayed in the categories node, while y-axis values are displayed in the dataset node (each chart series is represented by a dataset node).

 

<xml id="root">
   <report>
      <call controlId="410" action="get" cached="False">
         <controlTitle>Chart</controlTitle>
         <title>Page Views</title>
         <prefs>
            <prefs>
               <enable3D>true</enable3D>
               <perspective>true</perspective>
               <legend>true</legend>
               <l_INSIDECHART>false</l_INSIDECHART>
               <l_STYLE>row</l_STYLE>
               <l_DOCKING>top</l_DOCKING>
               <labels>false</labels>
               <showtitle>false</showtitle>
               <showhelp>false</showhelp>
               <showpreferences>false</showpreferences>
               <timeframe>864000000000</timeframe>
               <timeInterval>864000000000</timeInterval>
               <rules>
                  <rule id="2022" status="on" title="Aggregated" type="Column" />
                  <rule id="2021" status="on" title="Specific" type="Column" />
                  <rule id="2046" status="off" title="Aggregated" type="Column"
                   period="1" />
                  <rule id="2129" status="off" title="Specific" type="Column" period="1" />
               </rules>
               <ctitle>Page Views</ctitle>
               <type>Column</type>
               <palette>BrightPastel</palette>
               <adgroup>2</adgroup>
               <adgroupname>Domain Users</adgroupname>
               <categories />
               <entityId>0:01264d16-4641-465a-bdfe-459f1cb10d35</entityId>
               <entityName>Collaboration Portal</entityName>
               <entityTree>0</entityTree>
            </prefs>
         </prefs>
         <data>
            <categories>
               <category name="Sun." />
               <category name="Mon." />
               <category name="Tue." />
               <category name="Wed." />
               <category name="Thu." />
               <category name="Fri." />
               <category name="Sat." />
            </categories>
            <dataset ruleId="2021" seriesname="Specific" type="Column">
               <set value="100" />
               <set value="212" />
               <set value="343" />
               <set value="256" />
               <set value="347" />
               <set value="103" />
               <set value="120" />
            </dataset>
            <dataset ruleId="2022" seriesname="Aggregated" type="Column">
               <set value="1390" />
               <set value="1456" />
               <set value="1437" />
               <set value="1367" />
               <set value="1278" />
               <set value="800" />
               <set value="678" />
            </dataset>
         </data>
      </call>
   </report>
</xml>

Table

The data section for Table reports is ready for HTML deployment.

 

<xml id="root">
   <report>
      <call controlId="411" action="get" cached="True">
         <controlTitle>Table</controlTitle>
         <title>Page Views</title>
         <prefs>
            <prefs>
               <showhelp>false</showhelp>
               <showpreferences>false</showpreferences>
               <timeframe>36000000000</timeframe>
               <timeInterval>36000000000</timeInterval>
               <maxrows>10</maxrows>
               <mincount>1</mincount>
               <reporttype>120</reporttype>
               <columns>
                  <column id="title" title="Title" width="35%" type="SPPage" />
                  <column id="url" title="Url" width="0" type="hidden" />
                  <column id="views" title="Views" sorted="true" width="15%" type="number" />
                  <column id="users" title="Unique Users" sorted="false" width="20%" type="number" />
                  <column id="avgDuration" title="Duration" sorted="false" width="15%" type="string" />
                  <column id="exitRate" title="Exit Rate" sorted="false" width="15%" type="number" />
               </columns>
               <ctitle>Page Views</ctitle>
               <chartType>static</chartType>
               <adgroup />
               <adgroupname />
               <categories />
               <entityId>0:b0426e68-8f34-4eb2-8702-012d5de1c143</entityId>
               <entityName>All</entityName>
               <entityTree>0</entityTree>
            </prefs>
         </prefs>
         <data><![CDATA[<table cache='True'>

<prefs>

<showhelp>false</showhelp>

<showpreferences>false</showpreferences>

<timeframe>36000000000</timeframe>

<timeInterval>36000000000</timeInterval>

<maxrows>10</maxrows>

<mincount>1</mincount>

<reporttype>120</reporttype>

<columns>

<column id="title" title="Title" width="35%" type="SPPage" />

<column id="url" title="Url" width="0" type="hidden" />

<column id="views" title="Views" sorted="true" width="15%" type="number" />

<column id="users" title="Unique Users" sorted="false" width="20%" type="number" />

<column id="avgDuration" title="Duration" sorted="false" width="15%" type="string" />

<column id="exitRate" title="Exit Rate" sorted="false" width="15%" type="number" />

</columns><ctitle>Page Views</ctitle><chartType>static</chartType><adgroup></adgroup><adgroupname></adgroupname><categories></categories><entityId>0:b0426e68-8f34-4eb2-8702-012d5de1c143</entityId><entityName>All</entityName><entityTree>0</entityTree>

</prefs>

<thead>

<td type='SPPage' width='35%' id='title'>Title</td>

<td type='hidden' width='0' id='url'>Url</td>

<td type='number' width='15%' sorted='true' direction='-1' id='views'>Views</td>

<td type='number' width='20%' id='users'>Unique Users</td>

<td type='string' width='15%' id='avgDuration'>Duration</td>

<td type='number' width='15%' id='exitRate'>Exit Rate</td>

</thead>

<tbody from='0' to='10' total='10'>

<tr>

<td>bl_SecondaryNav_Divider.jpg</td>

<td>http://scotland:81/Style Library/Images/bl_SecondaryNav_Divider.jpg</td>

<td>3</td>

<td>3</td>

<td>00:00:04</td>

<td>0%</td>

</tr>

<tr>

<td>Links</td>

<td>http://scotland:81/Lists/Links/AllItems.aspx</td>

<td>3</td>

<td>3</td>

<td>00:00:02</td>

<td>0%</td>

</tr>

<tr>

<td>Workflow Tasks</td>

<td>http://scotland:81/News/WorkflowTasks/AllItems.aspx</td>

<td>3</td>

<td>3</td>

<td>00:00:07</td>

<td>0%</td>

</tr>

<tr>

<td>Total Problems</td>

<td>http://scotland:81/Reports/Lists/Sample Dashboard KPI Definitions/DispForm.aspx?ID=1</td>

<td>3</td>

<td>3</td>

<td>00:00:05</td>

<td>0%</td>

</tr>

</tbody>

<startTime>1/1/0001 12:00:00 AM</startTime><endTime>1/1/0001 12:00:00 AM</endTime><rules>1</rules></table>]]>

         </data>

      </call>

   </report>

</xml>

Meter

The Meter data is displayed in the value node.

 

<xml id="root">

<report>

<call controlId="412" action="get" cached="True">

<controlTitle>Meter</controlTitle><title>Page Views</title>

<prefs>

<prefs><showhelp>false</showhelp><showpreferences>false</showpreferences><timeframe>36000000000</timeframe><timeInterval>36000000000</timeInterval><minvalue>0</minvalue><maxvalue>100</maxvalue><undershoot>0</undershoot><overshoot>100</overshoot><ctitle>Page Views</ctitle><chartType>static</chartType><adgroup></adgroup><adgroupname></adgroupname><categories></categories><entityId>0:b0426e68-8f34-4eb2-8702-012d5de1c143</entityId><entityName>All</entityName><entityTree>0</entityTree></prefs>

</prefs>

falsefalse3600000000036000000000101120Page Viewsstatic0:b0426e68-8f34-4eb2-8702-012d5de1c143All0 Title Url Views Unique Users Duration Exit Rate bl_SecondaryNav_Divider.jpghttp://scotland:81/Style Library/Images/bl_SecondaryNav_Divider.jpg 3 3 00:00:04 0% Links http://scotland:81/Lists/Links/AllItems.aspx 3 3 00:00:02 0% Workflow Taskshttp://scotland:81/News/WorkflowTasks/AllItems.aspx 3 3 00:00:07 0% Total Problems http://scotland:81/Reports/Lists/Sample Dashboard KPI Definitions/DispForm.aspx?ID=1 3 3 00:00:05 0% 1/1/0001 12:00:00 AM1/1/0001 12:00:00 AM1]]>

</data>

</call>

</report>

</xml>

Examples:

1. How to add values to the chart image

In order to add values to the chart in the Data Export API, click on "Show Advanced Settings" and then "Get Report Preferences".
In the preferences XML, edit the <labels>true</labels> key and set the value to true. This will add values to the chart.
 

2. How to display the page views meter value

<script>
function getPageViews() {

// 1. Call the web service "http://cardiologservername:port/CardioLog/clreport/reportsapi.aspx" with the parameters "action=xml&controlId=3015&timeframe=77760000000000&urls=&usersAndGroups=&categoryId="

// 2. Create an XML file from the response and find the <data> node: selectSingleNode("//data").text;

// 3. Find the <value> node value with regex. Example:

var re = new RegExp("(^[^$]*<value>)([^<]*)(<\/value>[^$]*$)", "i");
if (response.match(re)) value = response.replace(re, "$2");
document.getElementById("pageviews").innerHTML = "This Year this site was viewed " + value + " times!";

window.onload = function () {
getPageViews();
}

</script>

<body>
<div id ="pageviews" class="sample"> </div>
</body>
</html>