This article describes general characteristics and behavior of the Analytics monitor API. The API is described in detail in the API Reference.
Any API calls placed prior to calling
Start are simply ignored and will return without having any effect. The same goes for API calls made after
Stop. (With two exceptions mentioned later.)
This means that you do not have to write code like this, because the call to
TrackFeature is already ignored if the monitor has not yet been started:
if (monitor.Status.IsStarted) monitor.TrackFeature("SomeCategory.SomeFeature");
It also means that the only thing you need to do to disable Analytics entirely is simply to not call
This can be relevant if the end-user says "no" to tracking and you therefore wish to disable Analytics. In that case you do not need to place protective conditions around the API calls like this:
// DON'T DO THIS if (isAnalyticsEnabled) monitor.TrackFeature("SomeCategory.SomeFeature"); ... if (isAnalyticsEnabled) monitor.TrackFeature("SomeOtherCategory.SomeOtherFeature"); ... if (isAnalyticsEnabled) monitor.Stop();
Instead, you only need to just disable the
Start call and let all the other API calls be. Like so:
// Only enable Analytics if user approves if (isAnalyticsEnabled) monitor.Start(); ... monitor.TrackFeature("SomeFeature"); ... monitor.TrackFeature("SomeOtherFeature"); monitor.Stop();
There are two exceptions to this rule:
SetInstallationInfowill work even outside
- Some platforms have an explicit disposal call
Releasethat should be called after
When talking about API method return codes it makes sense to look at two groups:
- Factory methods to create monitor, settings, storage- and logging-objects
- Instance methods on those created objects, e.g. on the monitor object
All API methods do rigorous parameter checking to ensure that they are valid. It is harmless to pass e.g. null to an API method expecting a string, so you do not need to do so to guard against passing invalid parameters.
If a factory create method (
CreateMonitor, etc) fails then it will produce an error on the platform's standard debug console and indicate the failure in this manner:
- Windows (C, C++), iOS, MacOS: return
For instance, if you pass the string
"Hello World" as the product key to CreateSettings on .NET then write the reason for that to the
System.Diagnostics.Debug output and throw an exception that you should catch.
Instance methods (
TrackFeature, etc) never return errors if something is wrong. They are all void, so you never have to check their return codes (they have none) nor wrap them in
try-catch exception handlers to ensure they do not throw exceptions (they will not). You just call them as they are.
In case of errors it will be logged to the logger specified by the settings. You can read more about this in the article on Logging Monitor Activity. By default there is no logging enabled and you must explicitly setup logging if you wish to do so.
For instance, if you pass a null string or a string exceeding the maximum feature name length to
TrackFeature, then it will simply not track anything and will write the reason to the logger.
Rare error cases are not trapped
Not all error conditions can be caught by the monitor API. Here are some exceptions:
- On .NET the
StackOverflowExceptioncannot be caught
- Invoking methods on an invalid object (null or invalid pointer on e.g. C++) will typically fail without the monitor being involved at all
- On Windows C++, both C++ and SEH exceptions are handled internally but some situations are uncatchable, such as passing an unaligned pointer argument that causes a SIGBUS signal.
API calls are, with one exception, "non-blocking". This means that you do not have to e.g. create background threads to call the API methods for fear that they may take too long.
The one exception is
Stop, which can be blocking for up to 2 seconds (by default). This is by design so the monitor can deliver accumulated statistics to the Analytics servers before the application shuts down.
You can read much more about this in the article on Monitor API Overhead.
On all platforms, the monitor is exposed as an interface.
This means that you can easily substitute your own version of the monitor instance, if so desired. This can be useful for mocking and stubbing the monitor in unit tests.