SoftMeter SDK / API

SoftMeter (former libAppTelemetry) is a usage analytics library for desktop software.

You can easily link this library to your desktop application and send usage statistics to your Google Analytics account.

Minimal example in C:


// don't forget to get user's consent
bool userGaveConsent = .....(pick from the app settings)....

start("MyApp", "1.0", "Free trial", "Windows edition", "UA-12345-0", userGaveConsent);

// you can send any number and combination of pageViews, screenViews, events, exceptions
sendScreenview("Main screen");
sendEvent("Registration", "User entered registration code", 1 );
sendException("Error while importing a custom file", false);

stop(void);

We wrote the documentation in a form of checklist that can be used as an integration guide.

Full API: (see the latest version on GitHub)


// get the version string of the library. 
EXPORT_API const char*	getVersion(void);

// get the full path name of the log file. 
EXPORT_API const char*	getLogFilename(void);

// Enable or disable the log file. The default is disabled.
// - Parameter macBundleId is used only in Mac OS. Under Windows you can pass NULL.
// - Parameters appName and macBundleId affect the filename and the folder of the logfile.
//   They must contain only characters compatible with the OS. 
//	 E.g. they cannot contain characters such as /\:
EXPORT_API void enableLogfile(const char *appName, const char *macBundleId);
EXPORT_API void disableLogfile(void);

// initialize the library.
// Parameters:
// - appLicense examples: free/trial/full/paid/etc
// - appEdition examples: Apple store/Special build/Standard/IOS/Mac/Win/etc
// Must be called before: sendPageview(), sendEvent(), sendScreenview(), sendException(), stop()
EXPORT_API bool start(const char *appName, const char *appVersion,
							const char *appLicense, const char *appEdition,
							const char *propertyID, const bool  userGaveConsent);

// stop the library. 
// The function will wait for a maximum of 3 seconds for all pending async calls to gracefully finish.
// After stopping the library, you can call again start() if you need to reuse it.
EXPORT_API void stop(void);

// Use sendPageview() if you are monitoring your app via a Google Analytics "Website" reporting view.
// Call this function after program launch, on program exit and on every important form, window, screen 
// that you want to track. E.g. Main Window, Configuration settings, Main Window, Exiting.
// It will process your request asynchronously.
EXPORT_API bool sendPageview(const char *pagePath, const char *pageTitle);

// Similar to smSendPageView, use sendScreenview() if you are monitoring your app via a 
// Google Analytics "Mobile App" reporting view.
// It will process your request asynchronously.
EXPORT_API bool sendScreenview(const char *screenName);

// optionally call sendEvent() to log events in Google Analytics.
// With the events, you have an alternative way of tracking your program.
// You can use events to mark some important milestones in the use of your program,
// e.g. the user enters a registration code to convert the free trial to a full version.
// It will process your request asynchronously
EXPORT_API bool sendEvent(const char *eventAction, const char *eventLabel, const int eventValue );

// If you catch exceptions in your program, you can send them to Google Analutics.
// if isFatal = false, the incident will be logged in Google analtytics as Exception
// if isFatal = true, the incident will be logged in Google analtytics as Crash
EXPORT_API bool sendException(const char *exceptionDescription, const bool isFatal);

//	The function, aio_sendEvent() performs the whole sequence of start(), sendEvent(), stop.
//  This allows you to send with a single function call, an event to Google Analytics.
//  It was created for tools like Installaware where you can only call one function from the DLL 
//  before the DLL gets unloaded. In such cases, you cannot keep the DLL loaded in memory and do
//  successive function calls, preserving the internal state of the DLL. 
//  For its parameters, aio_sendEvent() combines the parameters of start() and sendEvent() 
//  In the DLLs there also its counterpart, aio_sendEvent_stdcall()
EXPORT_API bool aio_sendEvent(const char *appName, const smChar_t *appVersion,
                              const char *appLicense, const smChar_t *appEdition,
                              const char *propertyID, const bool  userGaveConsent,
                              const char *eventAction, const smChar_t *eventLabel, const int eventValue
                              );