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 );