Cross Platform C#

How To Drill Into Problems with Xamarin Insights

Here's a nifty tool that can help you get to the heart of issues in your mobile apps that aren't easy to track down.

• By Wallace McClure
• 03/16/2016

You've completed the initial version of your mobile app. You've deployed it. And now, you've started to get reports of exceptions in your app. It doesn't happen all of the time, and it doesn't happen to all users, only some of them. What's worse is that the errors aren't often repeatable. For some reason, the issues some users are having can't be repeated in your office. You drive around and try to repeat the errors but you can't, so you wonder if it's is a location issue. Perhaps it's a cell signal issue. Perhaps the issue is the version of the OS the user is running. You're stuck and you don't know what's causing the errors. You need more information in order to solve the problem, so where do you turn? Xamarin has released a product just for this situation. It's called Xamarin Insights.

Xamarin Insights in a Nutshell
Xamarin Insights allows you to get information about your application while it's running on user devices. It can be used to determine information about your application, stack traces, device info, events leading up to the crash and other diagnostic information. Along with this, crash information is grouped together, so developers are able to identify trends and find the cause of the problems fast.

Getting started with Insights is actually fairly simple. In your application, you'll want to do the following:

• Add the Xamarin Insights NuGet package to the project.
• Add the Xamarin namespace to the necessary files.
• Add code into the necessary class. For Android, this code looks like:

  var appContext = this.ApplicationContext;
  Insights.Initialize("your app key goes here", appContext);

For iOS:

Insights.Initialize("your app key goes here");

Once the code runs, Insights is ready to be called. Here's some example code within Android that will run when an exception is called. In this example, when a click is performed on a button, an exception is intentionally thrown. In the catch statement, an Insight report is made:

button.Click += delegate {
  try {
    button.Text = string.Format("{0} clicks!", count++);
    throw (new ApplicationException("Something bad happened."));
  }
  catch(ApplicationException ae)
  {
    var errorInfo = String.Format("Button has been clicked {0} times.", count);
    Insights.Report(ae, "This is a key", errorInfo, Insights.Severity.Error);
  }
};

Once this code is running, a message is sent to the Xamarin Insights portal.

Xamarin Insights Portal
The Xamarin Insights portal is the place where developers can go to start working with Insights. From there, a developer can set up an application, obtain an app key and view application data. In this example, I've created an application called WallymExampleapplication.

Figure 1 shows information for setting up the application. The portal provides the app key for your application to track, as well as some example code.

Now that your application is running, let's look at the high-level reporting screen shown in Figure 2 This screen displays items such as the most recent error reporting time, a list of recent errors grouped together and other information.

Figure 3 provides more detailed information about a grouped error. Some of the information includes Android version, number of occurrences, device information and specifics on an error instance.

The first example with Insights merely sent some simple text to the portal. It's possible to send additional information. Here's some sample code that will do just that -- send a set of information to Insights:

catch(ApplicationException ae)
{
  var errorInfo = new Dictionary<string, string>();
  errorInfo.Add("count", count.ToString());
  errorInfo.Add("message", String.Format("Button has been clicked {0} times", count));
  Insights.Report(ae, errorInfo, Insights.Severity.Error);
}

What this code does is allows for some more detailed information to be easily discovered and easier debugging.

Identifying Users
Do you ever have troublesome users? Of course you do. Everyone has that one user who complains about things, reports errors, has issues with an application or has some other issue that takes up support time. The user could be the only one who reported a problem, could have a unique version of Android that's causing a problem, or could have any number of other issues. It would be helpful to have this information handy so the app can be debugged. If you're using the Business or Enterprise version of Insights, this is possible. Let's look at the information that can be used to identify a user.

The basics on identifying the user with the method call:

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

In this code, the values stand for:

• Unique User ID: This is an identifier for a user in the application. It can be anything, but it should be able to uniquely identify the user.
• Key: This is the type of the value that's provided. It's suggested that this be one of the given traits, but it can be anything, as well.
• Value: This is the user-specific value for the key.

Advanced Identification
The user has additional information that can be provided when identifying a user, and you can get that from within Insights. Here is an example:

var moreInfo = new Dictionary<string, string>();
moreinfo.Add("Email", "[email protected]"); moreinfo.Add("Name", "Wally McClure"); Insights.Identify("Unique User Id", moreinfo);

Insights provides some predefined keys that can be used. A current set of enum values in Insights.Traits includes Address, Age, Avatar, account creation date (CreatedAt), date of birth (DateOfBirth), description of user (Description), e-mail address (Email), first name (FirstName), Gender, last name (LastName), full name (Name), phone number (Phone), and Web site address (Website). In addition, there's a GuestIdentifier that's used to revert the identity back to a guest user. An example usage is:

var moreInfo = new Dictionary<string, string>();
moreinfo.Add(Insights.Traits.Email, "[email protected]"); moreinfo.Add(Insights.Traits.Name, "Wally McClure");
moreinfo.Add("Degree of loserness", "High"); Insights.Identify("Unique User Id", moreinfo);

Tracking Events
Beyond just reporting exceptions, Insights can allow you to track events and time. An example of event tracking is to track when a user starts to use a given feature. Time tracking is reporting the amount of time that a given task takes to be completed.

For event tracking, there is a Track method that can be used. An example of tracking an application playing music is:

var musicInfo = new Dictionary<string, string>();
musicInfo.Add("Take It Easy", "211"); 
Insights.Track("MusicTrackPlayed", musicInfo);

Tracking the amount of time that a given task takes is important. Users don't like tasks that take a long amount of time, especially while they're on the go. There are two ways to track time. The first way is:

using(var handle = Insights.TrackTime("TimeToLogin"))
{
  await Login(userinfo, password); 
}

A second way to track time is:

var handle = Insights.TrackTime("TimeToLogin"); handle.Start(); await Login(userinfo, password); handle.Stop();

Note: There is a difference between Track and TrackTime on the server. Track is for a single event and can be used for analytical purposes. TrackTime allows for Xamarin to graph when viewing data in the Insights portal.

Wrapping Up
Insights is a good tool for finding out how users are using your application. It has various versions for different classes of developers. It can allow developers to find exceptions and track additional issues within their applications and improve them in other ways. Good luck on your future mobile apps!

• Get Code Download