Request a Demo Start Trial
JavaScript Analytics
Download JavaScript Analytics SDK
version 2.3.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.3.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.
boolean (optional) enableLogging Indicates whether to log debug and error messages to the console, defaults to false.

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.

Parameters
string name Name of the property.
Returns
any The property value.

setProperty(string name, any value)

Sets a property to be included on all your events.

Parameters
string name Name of the property.
any value The property value.

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.

parseQueryString(string queryString)

Parses a query string into an object.

Parameters
string queryString Query string to be parsed. Leading ? or # are ignored.
Returns
object A collection of key and value pairs.

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.

setEntityData(object data, function callback)

Sets properties to be included on all your events. Entity data is stored on DeskMetrics’ servers and included whenever an event is received by specifying the corresponding dm.entity_id property.

Parameters
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(string entityId) {...};
Returns
Promise Promise that will be resolved on complete with the entityId.

attributeEntityId(function callback)

Attempts to resolve an entityId so that entity data set by the DeskMetrics JavaScript SDK or a DeskMetrics tracking link in a browser can be attributed to an Electron app running on Mac or Windows. Applies to Electron app integrations only.

Parameters
function (optional) callback Callback on complete. The callback parameter should be a function that looks like this: function(string entityId) {...};
Returns
Promise Promise that will be resolved on complete with the entityId.

Web Page Integration

Include the DeskMetrics JavaScript SDK.

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

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

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

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.

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

    // let's set some properties

    var qs = $dm.parseQueryString(location.search);

    // DeskMetrics persists values between sessions, so use an existing value rather than overwrite
    $dm.setProperty('utm_source', $dm.getProperty('utm_source') || qs['utm_source']);
    $dm.setProperty('utm_medium', $dm.getProperty('utm_medium') || qs['utm_medium']);
    $dm.setProperty('utm_term', $dm.getProperty('utm_term') || qs['utm_term']);
    $dm.setProperty('utm_content', $dm.getProperty('utm_content') || qs['utm_content']);
    $dm.setProperty('utm_campaign', $dm.getProperty('utm_campaign') || qs['utm_campaign']);
});

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;
    });
});