SoftMeter implementation - how to add Google Analytics to your program

SoftMeter is a library for Windows and Mac OSX that allows software developers to send "pageview", "event", "screenview" and "Exception" hits from inside their programs to their Google Analytics profile.

With SoftMeter, shareware authors can see the active installations of their programs in the same way they see the visits to their website.

The following steps will guide you to link the library with your application and start sending your program's usage data to your Google Analytics property.

Checklist of steps

# Task Duration
  A. Prerequisites  
A1 Read the SoftMeter EULA. Stop using SoftMeter if you do not agree to some of the terms. 10 min
  B. Prepare the reporting platform to "listen" to your software  
B1 Create a Google Analytics (GA) account if you do not already have one for your website monitoring. 15 min
B2 Inside your GA, create a new property, name it after the name of your software.
Best practice: Each software product you have should have its own GA property to allow easy separation of statistics.
You will be asked to select the reporting type between "Website" and "Mobile App".
Here is a comparison of the two reporting view types.
Select "Website" because "Mobile App" will require to fill in details about your firebase app, which you don't have.
This completes a) the creation of the Property, and b) the creation of the reporting view under that property
Write down the property ID number.
Later, you can create a "Mobile App" reporting view (if you want to send "screenView" events from your application).
5 min
B3 Download our demo application and the SoftMeter library.
Use your new property ID to send test hits to the reporting view.
Use the real-time view for start.
15 min
B4 Subscribe to the SoftMeter newsletter so you can receive status alerts and new version announcements. 2 min
B5 Success level 1 reached: You have a new GA property for your software, and you have sent test hits from SoftMeter. Now, you just need to send these hits from your own application.
Take a coffee break
20 min
  C. Implementation  
C1 "Watch", "Star" or "Fork" our GitHub repository. If you do not have a GitHub account, you can create one for free.  5 min
C2 If you are implementing installation/uninstall statistics:  
  For Inno setup, use our ready example. 20 min
  For Installaware, use our all-in-one function aioSendEvent_stdcall (you must use the __stdcall calling convention). 15 min
  For other installation packages, see our Inno setup and Installaware examples to implement installation analytics in a similar way. 1 hour
C3 If you are implementing runtime software analytics inside your software, see our examples.
You can start with a minimum of calling the sendScreenView() function on application launch.
Note for Windows applications: The SoftMeter DLL has both the __cdecl and __stdcall versions of its functions. You can use the set that is appropriate to your development language and tool.
4 hours
C4 Run your installation package or your software to see the hits arriving at your GA reporting.
Adjust your code and textual parameters of SoftMeter according to your wishes.
2 hours
C5 Add a paragraph in your EULA and a screen at the UI of your application to notify the users about the telemetry.
Download this sample telemetry consent EULA that you can use as a template to write your own.
If your users are also from the EU and the EEA, you must give them an opt-in/opt-out option, where the default is opt-out, in order to comply with the 2018 GDPR law about the personal data.
3 hours
C6 Success level 2: Well done. 
Take a good break. You can discuss your experience with your fellow developers and if you want send us any comments you might have.
2 hours
  D. Packaging and release  
D1 Include the SoftMeter library in your installation package. 1 hour
D2 Check our GitHub space and our news for the latest version of SoftMeter.
If a new version exists, you just need to replace the SoftMeter DLL (or dylib on Mac) with the new file.
Note: Every time you publish a new release of your software, it is highly recommended to use the latest version of SoftMeter. Subscribing to the SoftMeter newsletter and alerts and "Watching" our GitHub repository can help achieve this with minimal effort.
5 min
D3 Do you normal quality checks and publish the new release.  
D4 On the next day, log in to GA to see the first installation and usage statistics. 1 hour
D5 Success level 3: You are a hero. Modest or not, the truth is that you brought new information, of high value to your software development house.
You have implemented an advanced technology that allows you for the first time:
- to see what happens after the download,
- see the conversion rate of free to paid users
- to look at how your users use the features of your software,
- understand their needs and build better software,
- discover bugs immediately (via crash and exception reporting)
- work with focused effort.
Take some screenshots or print-outs fo your first reports, for your fellow developers and the management team.
 
  E. Post-launch taks and graceful project completion  
E1
Take our template reports and dashboards from the GA reports gallery and import them into your GA property.
We created these reports and dashboards to get you started quickly. From our templates, you can observe the key metrics of your software.
SoftMeter GA dashboard
GA solutions gallery for SoftMeter
2 hours
E2 At any time you can also build your own custom reports, or even take the data to Google data studio to perform a more advanced analysis.  
E3 If you only implemented Installation analytics, consider adding SoftMeter also in your application.
If you only implemented SoftMeter in your application, consider adding it also in your setup package.
 
E4 Consider purchasing a SoftMeter Pro license or making a donation to this project. 15 min
E5 Send us your feedback 5 min
E6 Success level 4: By using our library, and optionally buying the Pro edition, or donating to this project, you increased our development happiness.
A big Thank you!
 

Detailed steps

Step 1. Prepare your Google Analytics property to receive usage data from the library

You can send data to a new or to an existing Google Analytics property.

I recommend that you start with a new property (under the same GA account). It takes less than 3 minutes to create it and you can discard it anytime if you finally do not need it.

A new properly allows you to quickly focus on the data sent from your application during your tests and the first release.

The general recommendation is: one property for every software product that you want to track. All GA properties can be under the same GA account.

Under the new property, I recommend you create a "Mobile App" type of reporting view.

See detailed instructions here: How to create and test a Mobile App reporting view in Google Analytics

 

Step 2. Send "pageview", "event" and "screenview" hits to your property to verify they are collected ok.

To test the reporting view, follow the remaining instructions on How to create and test a Mobile App reporting view in Google Analytics

 

Step 3. Save the library file (.dll or .dylib) next to your program's executable or in a relative folder.

Chose the appropriate library that matches your program: 32 or 64 but DLL for Windows, the 64-bit dylib for Mac.

 

Step 4. Include in your source code the ready files.

For C++ Windows and/or Mac software: example files.

For Delphi/Pascal console software: example files.

For Delphi/Pascal GUI software: example files and blog article.

For Inno Setup (installer package): example files and blog article.

 

Step 5. Place calls to initialize and finalize the library.

At the start of your program call the functions


enableLogfile()

start()

and at the end of your program call


stop()

 

Step 6. Place some calls to send "pageviews", "screenviews" or "events" to google analytics.

On the various screens/forms/windows of your program put some calls to the functions


sendPageview()
sendEvent() 
sendScreenView()

On Google Analytics if you are using a "Website" type of reporting view, then your program should send PageViews and Events.

On Google Analytics if you are using a "Mobile App" type of reporting view, then your program should send ScreenViews and Events.

 

Step 7. Login to google analytics and watch the hits.

Go to the real-time view of Google Analytics and run your program.

See if the hits arrive in G.A.

Examine the log file for any errors.

 

Step 8. Adapt the hits according to your monitoring needs.

After you start seeing in G.A. the hits coming from your program, you can adapt your calls to the library to use a combination of Pageviews and Events or Screenviews and Events.

 

Step 9. Add a paragraph in your EULA and the UI of your application to notify the users about the telemetry.

It is part of the Google terms that you must inform your users about the telemetry. This is something like the "cookie policy" fly-out message that appears on many sites.

See this sample telemetry consent EULA that you can use as a template to write your own.

Also, you must give a choice to your users to opt-in or opt-out, something like a radio button under your Settings or About menu. According to the new GDPR EU law (May 2018), users must opt-in by themselves.

 

Step 10. Include the library file in your installation/distribution package.

Include the library file in your installer and do a full test as an end user. You can rename the library file if you wish to do so.

If for some reason a user deletes the library or if you omit it from the installation, the example code we gave, gracefull disables the SoftMeter API functions so that your program will not misbehave.

The API functions will return "false" as a result.

 

Something not working? Need support?.

If you meet difficulties, do not hesitate to contact us.

Add new comment

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.

plain text with line breaks

  • Allowed HTML tags: <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd> <p> <br>
  • No HTML tags allowed.
  • Lines and paragraphs break automatically.