SoftMeter SDK / API
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 );