Knowledge Base/Analytics/Resources

Quick Guide

Thomas Høst Andersen
posted this on August 02, 2011 11:49

Intro

If you are not already a registered user, be sure to register for an account. Once registered you can login and download the appropriate monitor library for your platform, register your product and obtain your product key. This product key will allow you to integrate the monitor library into your application, and start monitoring how your application is being used. Before continuing be sure you have downloaded the appropriate monitor library, and have your product key ready. The monitor is currently available on the following platforms:

 

  • .NET (full framework)
  • .NET Compact Framework
  • Silverlight
  • COM (through COM interop and with a slightly reduced API)
  • Java
  • Android
  • Windows Phone 7
  • iOS
  • Win32/C++

 

Integrating the Analytics monitor

To integrate the monitor library in your application you really only need two lines to get started

.NET:
IAnalyticsMonitor monitor = AnalyticsMonitorFactory.Create("YOURPRODUCTKEYHERE");
monitor.Start(); 
java:
IAnalyticsMonitor monitor = AnalyticsMonitorFactory.Create("YOURPRODUCTKEYHERE", 
    "APPLICATION_VERSION");
monitor.Start(); 
C++:
IAnalyticsMonitor *monitor = AnalyticsMonitorFactory::Create("YOURPRODUCTKEYHERE", 
    "APPLICATION_VERSION");
monitor->Start(); 
Objective-C:
EQATECAnalyticsMonitor *monitor = [EQATECAnalyticsMonitor monitorWithProductId:@"YOURPRODUCTKEYHERE" version:@"APPLICATION_VERSION"];
[monitor start];
You need to insert your own product key into the Create method, to ensure that the data is being reported on your particular product. When you have integrated these calls into your application and referenced the monitor library, the monitoring has been started, and all starts of your application will be registered on the analytics servers.

 

Be sure to remember that you will have to start the monitor for the information to be collected. You can freely call all methods on the monitor instance when it hasn't been started, but information is not collected untill you explicitly call the start method.

 

One thing that you may be wondering, is when the monitor sends application usage statistics back to the servers. Statistics are sent to the servers when you start the monitor and when you stop the monitor. Features tracked in this period is aggregated and sent in a single message. The monitor also sends usage statistics back to the server if you either track an exception or send a log message even though the monitor is still running. This is done to allow long-running application to report problems back as soon as possible and not have to wait for the application to be stopped. When we send usage statistics messages back to the server we piggy-back the current feature usage onto the message to minimize the network payload. If the servers cannot be reached the monitor will cache the messages and attempt to resend the messages again at a later point.

 

Try running your application a few times and you should see the usage statistics start coming in. To access you statistics, login in here and go to the dashboard for your product. Dependent upon the delay on the server, you should see your usage statistics rising. Try disconnecting your computer from the network while running your application and verify that the monitor, when running the application again with the network plugged back in, will send the data run the previous application run.

 

Tracking feature usage

If you want to know more about the usage of your application than the number of times the application has been started, you can track the usage of specific features in your application. The monitor library allows you to track named features by using the following syntax:
.NET and java:
monitor.TrackFeature("Export.PDF"); 
C++:
monitor->TrackFeature("Export.PDF"); 
The above code increments the usage of the PDF exporting feature by one. This specific feature is made up, and you should replace it with a feature that makes sense in your application. You should note the dot-notationbeing used in the code. The Analytics server utilizes this dot.notation to group together features allowing you to better compare and contrast the feature usage in meaningfull groups. For instance, if our fictitious application could also export to, say, HTML, we could instead have tracked a feature named Export.HTML. This would allow you to know which of your exporting features are being used, instead of just relying on intuition and sporadic feedback. 
If you are interested in tracking the time spent for certain features you will need to use another pair of method:

.NET and java:
monitor.TrackFeatureStart("Export.Configure"); 
...
monitor.TrackFeatureStop("Export.Configure");
C++:
monitor->TrackFeatureStart("Export.Configure"); 
...
monitor->TrackFeatureStop("Export.Configure");
Wrapping these method calls around your feature will allow tracking of the time spent in a given feature. Ensure that you have a matching Start and Stop pair otherwise the timing of the features are not correctly tracked.

 

Also note that calling a Start and Stop pair does not correspond to calling the regular TrackFeature method so if you are interested in tracking both the number of times a feature has been used as well as the time spent in the feature you will need to use both tracking methods.

 

Tracking exceptions

You have done your best to anticipate all possible scenarios for your application, and provide the end users with a pleasant experience. However, there may be some aspects of the application usage you did not expect, and did not provide sufficient error handling for. This is a frustrating problem for the end user who may get a crashed application, but it is also a problem for you since you have no idea that this is happening. The monitor library allows you to collect exceptions from the application, and send them to the server for later inspection, allowing you to fix the errors in subsequent versions. To send an exception back to the server, use the syntax below:
.NET and java:
monitor.TrackException(exceptionInstance); 
C++:
monitor->TrackException(exceptionInstance); 
You pass an instance of an exception, and the monitor will send the exception information back to the server if possible. Note that these exceptions are not sent on the next startup like other usage statistics, but are sent immediately to the server to compensate for the fact that because of these exceptions the users might never start the application again.

 

One tip, that may be usefull in your application, is to hook up some global unhandled exception logic to the monitor. This will allow you to send these exceptions to the server before your application crashes, and therfore providing your with valuable information to improve your application stability. For instance, in .NET the following syntax redirects exceptions in the AppDomain to the monitor:
.NET:
AppDomain.CurrentDomain.UnhandledException += (s,e) => 
         monitor.TrackException(e.ExceptionObject as Exception); 
Java
Thread.setDefaultUncaughtExceptionHandler(new UncaughtExceptionHandler(){
       @Override
       public void uncaughtException(Thread arg0, Throwable arg1) {
         monitor.trackException(arg1);
     }});

There are other points of interception dependent upon your programming platform. For instance, if you are using WinForms the Application class has a static ThreadException event which also can be redirected to the monitor

Sending custom log messages

You may need to send information from the application to the server to report a specific scenario or to send other types of messages. Dependent upon your subscription plan, the server is able to accept a number of these custom messages. The following syntax will send a custom message to the server:
.NET and java:
monitor.SendLog("This is a special message"); 
C++:
monitor->SendLog("This is a special message"); 
The messages are constrained to 512 characters, and are only accepted on the server if the product is under a subscription plan that allows messages to be accepted.

Note that these log messages should be considered a last fallback option for sending information to the server, because the ability to do intelligent handling of free text on the server is very limited. So please, choose the scenarios where you make use of these log messages with care

Checking for new versions of your application

The monitor also allows you to subscribe to notifications of new versions being published. Through the administation interface on the server you can register released versions of your product, and the monitor library will pick up this information and raise the VersionAvailable event in case the current application has a lower version number than the one registered on the server. The event is raised asynchrously as the check for the version happens behind the scenes, and the event is only raised in the case of a newer version. To subscribe to the event, you could use the following syntax:
.NET:
monitor.VersionAvailable += (s,e) => 
     {
       MessageBox.Show("Version " + e.OfficialVersion + " is available"); 
     };
Java
monitor.addVersionAvailableListener(new IVersionAvailableListener(){
     @Override
     public void versionAvailable(VersionAvailableEventArgs args) {
       System.out.println(args.getOfficialVersion());                    
     }});
C++
class NewVersionConsumer : public EQATECAnalyticsMonitor::IVersionAvailableEventHandler
{
private:
void OnVersionAvailable(EQATECAnalyticsMonitor::VersionAvailableEventArgs *args);
};

...

NewVersionConsumer *consumer = new NewVersionConsumer();
monitor->VersionAvailable_add(dynamic_cast(consumer));                    
The precise handling of the event is entirely up you and how your application works. Dependent upon how the new version has been registered on the server, some additional information is available on the event arguments when handling the event. Besides the OfficialVersion property the event arguments include aDownloadUri property that could point to the location of the new application and a VersionDescription property which could be e.g. a teaser text, a change log or something completely different. It is left entirely up to you how to handle this event in the application.

Customizing the monitor

It is possible to customize some of the behavior of the monitor. This can be done by using theAnalyticsMonitorSettings instance when calling the Create method. The AnalyticsMonitorSettings class has a few properties which allows for customization. The instance is by default populated with sensible defaults, but you may want to do some things a bit differently.
  • Version: By default the instance assumes that the official version of the application can be taken from the version number of the calling assembly (this is only true for .NET applications, for java you need to supply the version explicitly). If this is not the case you should assign the version directly.
  • Location: Assign GPS location coordinates to this class to provide fine grained location information. This may be specifically useful for mobile devices with built in GPS.
  • ProxyConfig: Control the proxy settings for the outgoing request from the monitor. The monitor will use the system defaults unless otherwise instructed.
  • UseSSL: Specify if the data should be delivered using the SSL protocol.
  • SynchronizeAutomatically: By default the monitor controls when data is delivered to the servers. However, there may be situations where it makes more sense for you to control when the monitor should attempt to connect to the servers (perhaps you only want to connect when your device is tethered). By setting this property to false you take responsibility and can instruct the monitor to attempt to connect using the ForceSync method call on the monitor.
  • ServerUri: The address to the server has a default format which contacts the analytics server. If you whish to point the monitor to another address, you can specifify the address directly.
  • StorageInterface: The monitor saves usage statistics between starts in a storage area. A default storage is assigned dependent on the where the monitor is executing, but if you wish to provide a different storage, you could implement the IStorage interface and be responsible for loading and saving data
  • StorageSaveInterval: The state of the current usages are peridically saved to the storage area to avoid losing too much information if the application unexpectedly terminates without calling the Stopmethod on the monitor instance. The default interval is one minute.
  • LoggingInterface: All calls on the monitor API are safe in as much as they will not throw exceptions if e.g. the server is unreachable. If you would like to receive some of the internal logging from the monitor you can implement the ILogAnalyticsMonitor interface and handle the logging messages as you see fit.
  • DailyNetworkUtilizationInKB: If this limit is explicitly specified  the monitor will stop sending data to the servers until the next day. This can be used to limit the bandwidth consumption if your application makes use of e.g. pay-as-you-go data subscriptions.
  • MaxStorageSizeInKB: If you have a limited amount of disk storage you can specify that the data stored by the monitor should be limited to a certain size. If limited the monitor will selectively store only the most essential data and discard the remaining data. Note that delivery of data to the servers are still attempted, this property only controls the size written to disk.
  • TestMode: This property is intended as an easy way to specify that the monitor is in a testing environment. Currently this have the affect that the new version information received from the servers will take non-published version that you have created into account. This should allow you to test how this information will be processed once the application is indeed published. In the future the behavior of this property may be expanded to include other aspects that support the developers and testers in the integration with the EQATEC Analytics servers and API.
 
Topic is closed for comments