CardioLog SaaS Client-Side API for SharePoint

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). 

The sendEvent JavaScript Function

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

/**
* @method sendEvent
* @param {JSON object} data
* @param {Function} [optional] function to be executed after the event is sent
*/
CardioLogAgent.API.sendEvent(data, eventCallback);

The sendEvent function accepts the following parameters:

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

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

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 send a click event on the DOWNLOAD button with the form fields values, add a call to the sendEvent function to the button onclick event as seen below:

When clicking on the button, a custom event of type ''Button Click" will be sent, indicating that the download button has been clicked on by the user. An "event sent" message will appear in the browser console.

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).

(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

Referrer Parameter

To monitor SharePoint content that is accessed via external applications, you can add the referrer parameter to the URL whenever you publish a link to a SharePoint page 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 Viva Engage (Yammer). 

For example, if you have included an internal SharePoint page link in an email, add the referrer parameter to the URL 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_2023 in order to display the link accordingly:

UTM Parameters

To track and analyze the performance of internal campaigns and understand which marketing efforts are driving traffic to your SharePoint site, you can use UTM parameters.

You can add any of the following UTM parameters to the end of a URL: 

1. utm_source: This parameter identifies the source of your traffic. It typically indicates where the link was placed, such as a specific website, newsletter, or social media platform.

2. utm_medium: This parameter specifies the medium through which the traffic is coming, such as email, social, or search.

3. utm_campaign: Campaigns are specific promotions or marketing initiatives that you want to track separately. This parameter allows you to identify the campaign associated with the URL.

4. utm_term: This parameter is used primarily for paid or promoted search campaigns, allowing you to specify the keywords associated with your campaign. It's less commonly used in other marketing channels.

5. utm_content: This parameter is used to differentiate between different pieces of content within the same campaign or source. For example, you can use it to track different versions of a banner or a link within an email.

For example, if you are sending out a monthly newsletter via email promoting a product launch event that was published in your SharePoint News section, add the following UTM parameters to the news article URL:

By adding these UTM parameters to your URL, you can track the effectiveness of your campaigns with greater granularity. When someone clicks on a URL containing UTM parameters and visits your site, the data is captured in CardioLog Analytics SaaS allowing you to analyze and measure the performance of each campaign, source, and medium separately. This information is valuable for optimizing your marketing strategies and understanding which channels are generating the most traffic and engagement.

How to see this data in the reports?

To learn how many visitors arrived at your SharePoint page from your referring application or internal campaign, you can filter your report by the referrer parameter or UTM parameters.

The referrer parameter and the UTM parameters' values are available in the CardioLog Analytics SaaS dataset in the following tables:

• SharePoint Usage table which stores all URL parameters in one string in the QueryString field.
• SharePoint Usage | Url Parameters table which stores all URL Parameters in key-value pairs, in the Key and Value fields.

The referrer parameter information is also available in the out-of the-box Navigation Overview report, in the Internal Traffic Sources table: