Quick Guide

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 folling platforms:

.NET (full framework)
.NET Compact Framework
Silverlight
COM (through COM interop and with a slightly reduced API)
Java

Integrating the Analytics monitor

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

IAnalyticsMonitor monitor = AnalyticsMonitorFactory.Create("YOURPRODUCTKEYHERE");
monitor.Start();

This is slightly different for java:

IAnalyticsMonitor monitor = AnalyticsMonitorFactory.Create("YOURPRODUCTKEYHERE", 
    "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:

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-notation being 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:

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:

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:

AppDomain.CurrentDomain.UnhandledException += (s,e) => 
         monitor.TrackException(e.ExceptionObject as Exception);

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:

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:

monitor.VersionAvailable += (s,e) => 
     {
       MessageBox.Show("Version " + e.OfficialVersion + " is available"); 
     };

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 a DownloadUri 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 the AnalyticsMonitorSettings 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.
InstallationID: A product can be configured to track the usages of the application by having the server send a cookie id to the individual application. This cookie is then returned to the server along with all subsequent requests. The cookie ID is anonymous and holds no identification of the user of the application. However, if you as application programmer wish to attach e.g. a product serial number or other anonymous installation identification to this cookie, you can set the InstallationID. The monitor will send this information (a string restricted to 50 characters) to the server and register it along with the cookie ID. Note that the installation ID is optional and is in no way required for having the cookie ID identification work. Also ensure that the installation ID does not compromise the privacy of the application user and the end user license agreement as the information is sent over the wire to the server.
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.
Storage: 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 Stop method 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.
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.