Xamarin Insights is an easy-to-use analytic and crash reporting tool available to all currently licensed Xamarin developers. Use Xamarin Insights to gain insight into how customers are using an application and to diagnose errors quickly and accurately.

How it Works

Xamarin Insights consists of a NuGet package that can be added to any mobile or desktop application, and a Web Portal used to configure an application and to view the analytics and crash reporting data collected.

Adding Xamarin Insights to an application requires four basic steps:

1. Including the Insights NuGet - Adding the Insights NuGet package (Xamarin.Insights) to the application.
2. Initialization - Initializing Xamarin Insights inside the application to monitor.
3. User Registration - Registering the current user with Xamarin Insights.
4. Reporting - Logging crashes and/or application events (such as feature usage) with Xamarin Insights for later retrieval on the Xamarin Insights Web Portal.

When including Xamarin Insights in production applications, the developer should inform the user that they are collecting analytics and crash reporting data to help improve the quality of the app. The application should also provide a mechanism (dialog box, setting, etc.) for them to opt out of the reporting.

Xamarin Insights Life Cycle

The following diagram shows the lifecycle of a typical application using Xamarin Insights for analytic and crash reporting:

The following steps occur:

• The developer registers an application with the Xamarin Insights Web Portal and includes the Xamarin Insights NuGet package in the application.
• When the application is later run in the wild, if it has an open Internet connection, logging information such as crash reporting and/or application events are sent through the Internet to the Xamarin Insights web server.
• If the application does not have an open Internet connection, the Xamarin Insights data is logged locally on the device. Later when a network connection is re-established, the log data is transmitted to the Xamarin Insights web server.
• At any point the developer can log into Xamarin Insights Web Portal and see the results of the analytics or crash reporting for the application.

Application Registration and Initialization

Before an application can implement Xamarin Insights and perform analytic and crash reporting, the developer must first register the application within the Xamarin Insights Web Portal. The developer will need to visit http://insights.xamarin.com, add a new application, and copy into their code the Insights API key generated for the new app. This key is required when initializing Insights issue tracking within the application.

The process of initializing an application with the Xamarin Insights NuGet differs based on the platform being developed for. For example, the following code can be added to the static Main() method in Application class of an iOS application to register the API key with Xamarin Insights:

using Xamarin;
...
Insights.Initialize("Your API Key");
UIApplication.Main (args, null, "AppDelegate");
        
          

Identifying the Device User

When using Xamarin Insights to collect analytic and crash reports from an application the developer can optionally identify the individual user of the application on the device:

Insights.Identify("Unique User ID", "Key", "Value");
        
          

Catching Exceptions

When running Xamarin Insights in an application, the service will catch all exceptions during the lifetime of the application. These exceptions are sent to the server when they occur (if there is a network connection) or the next time the application is started.

When an exception occurs outside of a try/catch, all of the exception is sent to the server. By using a try/catch enclosure, the developer can limit the amount of information sent to the Xamarin Insights service due to an exception and they can tailor the response to give a clear picture of the crash and the state of the device:

try
 {
      using (var text = File.OpenText("saved_game001.txt"))
      {
           Console.WriteLine("{0}", text.ReadLine());
           ...
      }
 }
 catch (FileNotFoundException ex)
 {
      Insights.Report(ex, new Dictionary<string,string>
      {
           { "Filename", "saved_game001.txt" },
           { "Where", "Reload game" },
           { "Issue", "Index of available games is corrupted" }
      });
}
        
          

There might be situations where the developer does not wish to send uncaught exceptions (outside of a try/catch block) to the Xamarin Insights service. In those situations, simply set the Insights.DisableExceptionCatching property to false.

Tracking Application Events and Time Tracking

In addition to reporting exceptions, Xamarin Insights can also be used to track application events such as when the user enters a given feature:

Insights.Track("MusicTrackPlayed", new Dictionary <string,string>{
    {"TrackID", "E1D8AB93"},
    {"Length", "183"}
});
        
          

Or Xamarin Insights can track the amount of time required to execute a feature:

using (var handle = Insights.TrackTime("TimeToLogin")) {
    await SubmitLoginInformation("myuserid", "mypassword");
    // ... more code goes here ...
}  
      
          

The difference between Track and TrackTime is at the server level. While the two methods look the same, Track is used purely for tracking analytic processes whereas TrackTime allows for time graphing facilities when viewing on the log data on the Xamarin Insights Web Portal.