SoftMeter SDK / API

SoftMeter (former libAppTelemetry) is a usage analytics library for desktop (MacOS, Windows) software and IOS apps.

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: (The code below is only a sample. 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
                              );