Insights is joining HockeyApp! Read the blog post. FAQ

Welcome to

Xamarin Insights

Quick Start


Platform Support

Xamarin.iOS Xamarin.Android Windows Phone & Windows 8.1 (winRT)

Installing the Package

Xamarin Studio

Xamarin Studio will automatically install the package for you when you setup Insights in your application through the Project Options.

Visual Studio

Install the Package by right-clicking on the Project name in the Solution Explorer and selecting Manage NuGet Packages.... Search for Xamarin.Insights and click Install.

An example of how to integrate package installation into an automated build process is available here (courtesy of Oren Novotny).

See more detailed documentation in the Getting Startedguide

Initialize

You'll want to start Initialize your application as soona s possible after the app starts

iOS, WP8 & WP81

For iOS initialize in the static Main method.

For WP initialize in the OnLaunched method

using Xamarin;
Insights.Initialize("Your API key");

Android

Add this to the OnCreate method.

using Xamarin;
Insights.Initialize("Your API key", yourAppContext);

Reporting

This API should be used to report exceptions that you have caught in a try/catch statement that you feel is worth sending to Insights.

using Xamarin;
...
try {
  ExceptionThrowingFunction();
}
catch (Exception exception) {
  Insights.Report(exception);
}


You can add extra data to exceptions which will be reported back to Insights

using Xamarin;
Insights.Report(exception, new Dictionary <string, string> {
  {"Some additional info", "foobar"}
});


You can set the severity of the exception to either Error, Warning, or Critical (default is Warning).

Use the Error severity if you need to manually report a "crash"

using Xamarin;
...
Insights.Report(exception, new Dictionary <string, string> {
  {"Some additional info", "foobar"}
}, Severity.Error);


If you just wish to add additional information to an exception but still throw the exception, you can use the Exception.Data property

try {
  ExceptionThrowingFunction();
}
catch (Exception exception) {
  exception.Data["AccountType"] = "standard";
  throw;
}

See more detailed documentation in the Reporting Exceptions guide, and the Advanced Topics guide.

Identify

Identify is used to identify information about your users.

using Xamarin;
...
Insights.Identify("a.unique.id@for.this.user", Insights.Traits.Name, "Gordon Strachen");

var traits = new Dictionary<string, string> {
  {Insights.Traits.Email, "gordon.strachen@celtic.com"},
  {Insights.Traits.Name, "Gordon Strachen"}
};
Insights.Identify("YourUsersUniqueId", traits);

Please note that Insights will limit the number of traits you can send to 25 unique traits.

Guest Identities

Insights will by default identify a user as a guest until you identify them yourself. If you wish to revert back to a guest user after previously identifying a user you can use the following api call.

using Xamarin;
Insights.Identify(Insights.Traits.GuestIdentifier, null);

This will revert the identified user back to a guest user, any track events sent after this call will be associated with a guest user.

See more detailed documentation here

Track Events

Track events are used to track the various comings and goings of your app, you can track whatever you like. Track comes in two variations, first of all the event style track.

using Xamarin;
Insights.Track("MusicTrackPlayed", new Dictionary<string, string> {
  {"SongName", "Shake It Off"},
  {"Length", "219"}
});


You can also use Track to track timed events, for example

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

// or if you do not wish to use the using syntax
var handle = Insights.TrackTime("TimeToLogin");
handle.Start();
await SubmitLoginInformation("myuserid", "mypassword");
// ... more code goes here ...
handle.Stop();

See more detailed documentation here

LIMITATIONS

  • you are limited to 1,000 unique track event names.
  • you can send up to 20 unique properties per track event name.
  • track event names are limited to 100 characters
  • property key names are limited to 100 characters
  • property values are limited to 125 characters

Communication Preferences

We realize not every application is the same, so we've given you the ability to disable the collection of certain types of data.

Insights.DisableCollection = true;         // Disables Insights automated behaviours
Insights.DisableDataTransmission = true;   // Disables data communication with the webapi
Insights.DisableExceptionCatching = true;  // Disables automatic unhandled exception catching

Insights.DisableCollectionTypes = Insights.CollectionTypes.HardwareInfo;     // Stops Insights from tracking HardwareInfo
Insights.DisableCollectionTypes = Insights.CollectionTypes.Jailbroken;       // Stops Insights from tracking Jailbroken
Insights.DisableCollectionTypes = Insights.CollectionTypes.Locale;           // Stops Insights from tracking Locale
Insights.DisableCollectionTypes = Insights.CollectionTypes.NetworkInfo;      // Stops Insights from tracking NetworkInfo
Insights.DisableCollectionTypes = Insights.CollectionTypes.OSInfo;           // Stops Insights from tracking OSInfo

//// Can be combined
// Stops Insights from tracking OSInfo and NetworkInfo
Insights.DisableCollectionTypes = Insights.CollectionTypes.OSInfo | Insights.CollectionTypes.NetworkInfo;

Debug Mode

You may find when debugging your application that Insights can get in the way, it will capture crash reports, both native and managed that you may want access to. You may also not want to pollute your applications data in Insights with events from your debug session.

The solution for this is to use Insights debug mode, replacing your Initialize call with the following will enter debug mode.

using Xamarin;
Insights.Initialize(Insights.DebugModeKey);

In Debug mode Insights will not collect any unhandled crash reports, it will not pick up native crash reports and any Insights.Track() or Insights.Identify() calls will be ignored.

Dealing with startup crashes

Crashes on startup are rather tricky to handle, you may find that your application crashes at startup in a way that does not give Insights enough time to transmit the crash report. With Insights you have a specific mechanism to deal with this problem.

Insights.HasPendingCrashReport += (sender, isStartupCrash) =>
{
  if (isStartupCrash) {
    Insights.PurgePendingCrashReports().Wait();
  }
};
Insights.Initialize("Your API Key");

This API allows you to get a notification when Insights detects a pending crash report, Calling Insights.PurgePendingCrashReports(); will allow you to block whilst those crash reports are sent out. This may delay your app startup time, which is why this is optional API instead of automatic.

The isStartupCrash value in your event handler will inform you whether the crash occurred within 5 seconds of app startup, which generally indicates that the app crashed during startup.