Request a Demo Start Trial
These docs are for an old version of DeskMetrics!
Go to the latest docs
Windows Analytics
Download Windows Analytics SDK
version 6.2.0

C++ Apps

Introduction

This document will walk you through integrating the DeskMetrics Analytics SDK into a C++ application. We’ll be working through examples/HelloDeskMetricsCpp/HelloDeskMetricsCpp.cpp, so open up the Visual Studio project and follow along.

We’ll make use of the following files from the SDK zip:

Note: if your application is 64 bit, you’ll need to use dma_x64.lib and dma_x64.dll in place of dma.lib and dma.dll.

In the Visual Studio project settings:

Include DeskMetrics

#include "dma_analytics.h"
#include "picojson.h"

// Your app key - this can be found on the applications page of your DeskMetrics dashboard.
#define APP_KEY L"<YOUR_APP_KEY_HERE>"

Start

In your WinMain function, load the DeskMetrics properties that were previously saved by your installer, and start the SDK.

If you haven’t integrated DeskMetrics into your installer, you might want to use dma_set_property_* and dma_save_properties to establish a set of properties to be sent along with all of your events.

// Load the properties saved by the installer.
dma_load_properties(L"HKCU\\SOFTWARE\\HelloDeskMetrics\\_dm", false);

// Start the analytics session
dma_start(DMA_SESSION_TYPE_APPLICATION, APP_KEY);

If you’ve set up a custom domain for use with DeskMetrics you can use the api: dma_set_analytics_base_url before your call to dma_start.

// Remember to include your protocol:
dma_set_analytics_base_url(L"https://mysubdomain.company.com");

// Proceed to initialize the SDK as usual:
dma_start(DMA_SESSION_TYPE_APPLICATION, APP_KEY);

Remember that this API should only be called before dma_start; if you call dma_set_analytics_base_url afterwards then your events will not be sent using your custom domain.

Stop

At the end of your WinMain function, stop the SDK. If your application can exit via more than one code path, make sure you stop DeskMetrics in all cases.

// Stop the analytics session - you must *always* call this before your application exits
dma_stop(DMA_EXIT_STATE_SUCCEEDED, DMA_WAIT_INFINITE);

Sending events

The integration we’ve seen so far will automatically fire launch, exit, and heart_beat events. However, you’ll probably want some custom events as well. In this example, we fire a custom event each time the user clicks a button.

Let’s take a look at the WndProc function to see how this is achieved:

// Create a new event object.
// Just for fun, lets send some real data about the size of the computer's primary monitor:
picojson::object obj;
obj["screen_width"] = picojson::value((LONGLONG)GetSystemMetrics(SM_CXSCREEN));
obj["screen_height"] = picojson::value((LONGLONG)GetSystemMetrics(SM_CYSCREEN));
std::string json = picojson::value(obj).serialize();

// Send the 'button_click' event.  We convert the string to a wide string before sending
// because we're using the Unicode apis everywhere else.  However, we could just as easily
// send using the Ansi api:  dma_send_a("button_click", data.c_str());
dma_send(L"button_click", std::wstring(begin(json), end(json)).c_str());

We’ve used the picojson library to serialize the json object to a string, but you may use whichever library you like.

Thread safety

The DeskMetrics SDK is threadsafe.

However, it should be noted that: