Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The CardioLog SaaS Tracking Agent offers a client-side API to send custom events using JavaScript, such as button clicks, banner clicks, navigation links or interactions with other UI components that display content dynamically (without redirecting to the actual content page URL). 

Table of Contents
maxLevel3

The sendEvent JavaScript Function

You can call the sendEvent JavaScript function on any monitored page in SharePoint (which includes the CardioLog Analytics SaaS Tracking Agent) to send events to CardioLog SaaS via the client browser. 

...

The sendEvent function accepts the following parameters:

data - Required. The event data in JSON format. For example:

Code Block
{
   "e":"Custom event",

...


   "eid":"E17221E709",
   "rid":"574DDE84E2",
   "sid":"4FC2D09FB6",
   "a":{
      "username":"i:0#.f|membership|admin@company.onmicrosoft.com"
   },
   "data":{
      "timeonpage":"65030",
      "loadtime":"0"
   },
   "u":"

...

https://

...

company.

...

sharepoint.com/

...

SitePages/Home.aspx",
   "qs":"",
   "ct":"2018-11-08 15:42:00",
   "ctoffset":"+02:00",
   "servertime":"2018-11-08 07:42:00",
   "servertimeoffset":"-06:00",
   "metaData": {
      "price": 5,
      "name": "

...

Some item"
   }
}

...

eventCallback - Optional. Function to be executed after the event is sent.

 

Parameter Name

Type

Description

Max Data Length

Example

e

string

Event name. Mandatory.

50 chars

"Pageview", "Search", "Search Result Click", "External Click", "Search Result Preview", "Duration", "Custom Event"

eid

string

Event ID.

10 chars

 "E7878CEF2A"

rid

string

Related Event Id (ID of previous 'Pageview' event).

10 chars

 "02E0D73FBF"

sid

string

Session Id. Should be same for all events within same browser session.

10 chars

 "39E186A874"

a.username

string

Full user account name.

256 chars

 "i:0#.f|membership|username@company.onmicrosoft.com"

u

string

Full URL path where the event occurred on or derived from:
1.

...

If URL has more than 1 query parameter, limit them to one
2. If it's a document - then it should be the document URL

1000 chars

"https://company.sharepoint.com/Home/Home.aspx?id=1"

qsstringQueryString of URL2000 chars"?id=1&q=2#s=1"

ct

DateTime

Client time.

 

 "2019-04-22 16:59:57"

ctoffset

string

Client time offset.

6 chars

“+03:00”

servertimeDateTimeServer time.  "2019-04-22 07:59:57"
servertimeoffsetstringServer time offset.6 chars"-06:00"

data.timeonpage

int

Time spent on page (after page is closed or URL is changed) in milliseconds

32-bit integer

65030
data.loadtimeint

Only for "Pageview" event:

Time it takes for the page to load in milliseconds

32-bit integer0

ua

string

User Agent

450 chars

"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.103 Safari/537.36"

spint

Only for "Search Result Click" event:
Position of search result on search result page

32-bit integer5
srint

Only for "Search" and "Search Result Click" events:

Total amount of search results on search results page

32-bit integer6
ststring

Only for "Search" and "Search Result Click" and "Search Result Preview" events:

Search term

255 chars"documents"
metadata A list of parameters and their values.

...

255 chars for key and value 
Code Sample

In this example, when a user clicks on the DOWNLOAD button on the home page, a popup window is opened with the download form:


Download Button


Download Form

...


In order to confirm that the event was sent successfully, open the browser Network tab and confirm that the request to the CardioLog Analytics SaaS events service (/cardiolog/api/client/events) returned the 200 status code.

 

Note: It is highly recommended to use the following code (or similar) to ensure that all the calls to the CardioLog API sendEvent function are executed and no events are lost (in case the CardioLog API object is not yet loaded on the page).

Info
iconfalse
(function (CardioLogAgent) {
  if (CardioLogAgent.API) {
    return;
  }

  var WAIT_FOR_SEC = 10;
  var WAIT_CHECK_INTERVAL_MSEC = 500;

  function createSendEventProxy() {
    var proxy = {
      calls: [],

      fn: function (data, callback) {
        proxy.calls.push({ data: data, callback: callback });
      }
    };

    return proxy;
  }

  var sendEventProxy = createSendEventProxy();
  var totalAttemptsCount = Math.ceil(WAIT_FOR_SEC * 1000 / WAIT_CHECK_INTERVAL_MSEC);

  function waitForSendEventInit(attemptNumber) {
    if (attemptNumber >= totalAttemptsCount) {
      return;
    }

    window.setTimeout(function () {
      if (CardioLogAgent.API.sendEvent === sendEventProxy.fn) {
        waitForSendEventInit(attemptNumber + 1);
      } else {
        var call;
        while ((call = sendEventProxy.calls.shift())) {
          CardioLogAgent.API.sendEvent(call.data, call.callback);
        }
      }
    }, WAIT_CHECK_INTERVAL_MSEC);
  }

  CardioLogAgent.API = { sendEvent: sendEventProxy.fn };
  waitForSendEventInit(0);
})(window.CardioLogAgent || (window.CardioLogAgent = {}));


Monitoring Internal Traffic Sources

To monitor SharePoint content that is accessed via external locations, you can use the referrer parameter whenever you publish a link to SharePoint and you wish to track the source of the referring application or page.

This is most commonly used in email or social networks such as Teams or Yammer. 

For example, if you have included an internal link in a promotional email add the referrer parameter to track the users who visited your site via this link. Define a unique referrer value that will be displayed in reports, such as referrer=email_promotion_Dec_2020 in order to display the link accordingly:

Code Block
https://intlock.sharepoint.com/sites/blogs/ceo_blog.aspx?referrer=email_promotion_Dec_2020

To see how many visitors arrived at your page through your email campaign, you can filter the Usage Overview report by the QueryString field which stores all URL parameters.

You can also create a new custom report and present this information in a separate table like so:

Image Added