Request a Demo Start Trial
JavaScript Analytics
Download JavaScript Analytics SDK
version 2.2.0

JavaScript Analytics

This document covers the DeskMetrics JavaScript SDK in general and step by step integration instructions for web pages.

Get the Library

Download the JavaScript SDK, or pull it directly from our CDN:

<script src="//cdn.dmjsapis.com/sdk/deskmetrics-2.2.0-min.js"></script>

Or install using npm:

npm install deskmetrics

Types

options

Properties
string appId Your app ID, found in the DeskMetrics dashboard.
string (optional) propertyKey The key used to store properties between sessions, defaults to deskmetrics.properties.
string (optional) propertyFileName The full file path used to store properties between sessions in nodejs and Electron apps, defaults to deskmetrics.properties.
boolean (optional) sendHeartBeat Indicates whether to send a heart_beat event, defaults to true for Chrome Extensions and Electron apps and false otherwise.
boolean (optional) sendLaunch Indicates whether to send a launch event, defaults to true for Chrome Extensions and Electron apps and false otherwise.
boolean (optional) sendPageView Indicates whether to send a page_view event, defaults to true for web pages and false otherwise.
string (optional) landingPageDomain For extensions, the domain of your inline install page EG: my.domain.com. DeskMetrics will pick up any properties you’ve set under the landingPagePropertyKey.
string (optional) landingPagePropertyKey For extensions, the key used to store properties on your inline install page, defaults to deskmetrics.properties.
string (optional) analyticsBaseUrl The base URL of the DeskMetrics analytics API. If you’ve set up a custom domain for use with DeskMetrics then configure it here.
string (optional) shortBaseUrl The base URL of the DeskMetrics short API used by Chrome Extension integrations. If you’ve set up a custom domain for use with DeskMetrics then configure it here.

Methods

start(object options, function callback)

Starts the SDK loading any properties set during previous sessions.

Parameters
object options Options must include your app ID.
function (optional) callback Callback on complete. The callback parameter should be a function that looks like this: function() {...};
Returns
Promise Promise that will be resolved on complete.

getProperty(string name)

Gets a property that’s set to be included on all your events.

Returns
The property value.

setProperty(string name, object value)

Sets a property to be included on all your events.

send(string name, object data, function callback)

Sends an event.

Parameters
string name Name of the event.
object data Properties to attach to the event.
function (optional) callback Callback on complete. The callback parameter should be a function that looks like this: function(XMLHttpRequest xhr) {...};
Returns
Promise Promise that will be resolved on complete with the XMLHttpRequest object.

setUninstallURL(string url)

Sets a URL to be visited on uninstall. Applies to Chrome Extension integrations only.

Parameters
string url Url to be visited on uninstall.

Web Page Integration

Include the DeskMetrics JavaScript SDK.

<script src="//cdn.pingstatsnet.com/sdk/deskmetrics-2.1.0-min.js"></script>

Start the SDK. Your app ID can be found online in the DeskMetrics dashboard.

$dm.start({ 'appId': '<-- YOUR APP ID -->' }, callback);

In this example, we’ve provided a callback to start where we’ll set properties to be included on all events. Getting/setting properties in a start callback is recommended because properties from previous session(s) are loaded and available but the SDK has not yet sent events.

function callback() {

    var params = ['utm_source', 'utm_medium', 'utm_term', 'utm_content', 'utm_campaign'];

    // set utm parameters from query string
    for (var i = 0; i < params.length; i++) {

        // DeskMetrics persists values between sessions, so use an existing value rather than overwrite
        var v = $dm.getProperty(params[i]) || getParameterByName(params[i]);
        $dm.setProperty(params[i], v);
    }
};

// http://stackoverflow.com/questions/901115/how-can-i-get-query-string-values-in-javascript
function getParameterByName(name) {
    name = name.replace(/[\[]/, "\\[").replace(/[\]]/, "\\]");
    var regex = new RegExp("[\\?&]" + name + "=([^&#]*)"),
        results = regex.exec(location.search);
    return results === null ? "" : decodeURIComponent(results[1].replace(/\+/g, " "));
}

We’re ready to send an event:

$dm.send('hello_world', {});

Gotchas!

What if we want to fire an event when a user leaves a page by clicking an outside link? If we’re not careful, the XHR request will not complete before the browser navigates away. We can address this issue by firing the event and passing a callback function to be executed once the request is complete.

In this callback, we’ll trigger the actual navigation:

// Suppose the links on the page look like this:
// <a class="navigate-away" href="#" data-destination="https://google.com">Bye bye!</a>

$('.navigate-away').click(function() {
    var destination = $(this).data('destination');
    $dm.send('navigate', {to: destination}, function(xhr) {
        window.location.href = destination;
    });
});