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:
- picojson.h (or another json library, if you prefer)
Note: if your application is 64 bit, you’ll need to use
dma_x64.dll in place of
Link the dependency
In the Visual Studio project settings:
Linker > Input > Additional Dependencies
- Add the folder containing
Linker > General > Additional Library Directories
- Copy the
dllto a location where the system will know to look for it (eg. next to your executable)
- Copy over
picojson.hto your project directory where the compiler will find them or, optionally set an include path to the sdk directory in the project settings:
C/C++ > General > Additional Include Directories
- At the top of the source file we’ve include
picojson.h(optional). We’ve also defined our app key:
#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>"
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_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
// 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.
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);
The integration we’ve seen so far will automatically fire
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.
The DeskMetrics SDK is threadsafe.
However, it should be noted that:
dma_sendcalls will not succeed until
dma_starthas been called successfully. Ensure you call
dma_startbefore starting threads that use DeskMetrics
- Using DeskMetrics after it has been stopped is illegal. Join all threads that use DeskMetrics before stopping the SDK