SoftMeter SDK / API

SoftMeter 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)....

// give your GA4 Api secret
setOptions("ApiSecret=<your_api_secret>");

start("MyApp", "1.0", "Free trial", "Windows edition", "G-xxxxxxxxx", 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. 
const char*	getVersion(void);

// get the full path name of the log file. 
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 /\:
void enableLogfile(const char *appName, const char *macBundleId);
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()
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.
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.
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.
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 actions done by the user of your program,
// e.g. the user enters a registration code to convert the free trial to a full version.
// The eventValue is an integer.
// If you want to send a string value, use the eventLabel parameter.
// It will process your request asynchronously
// SoftMeter Free edition: event hits are muted. Consider upgrading to the PRO edition.
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
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()
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
                              );