Visual Studio App Center Analytics is the next generation of Xamarin Insights! Read the blog post.

Getting Started

Adding intelligent analytics and crash reporting to your Xamarin applications

PDF for offline use
Sample Code:
Related Links:

Let us know how you feel about this

Translation Quality


0/250

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

Supported Platforms

Xamarin Insights is available for use with applications on any of the following platforms:

  • Xamarin.iOS (iOS 7+)
  • Xamarin.Android (API 14)
  • Xamarin.Forms
  • Windows 8.0
  • Windows Phone & Windows 8.1 (winRT)

Application Registration and Setup

1. Register in the Dashboard

To start collecting analytics and crash reports from mobile apps, first register for an API Key from the Xamarin Insights Dashboard by following the instructions below.

To register an application, let's do the following:

  1. In your web browser, navigate to the Xamarin Insights dashboard at insights.xamarin.com
  2. Login to the Dashboard using your Xamarin Developer credentials. Only developers with a current Xamarin license are eligible to use Xamarin Insights.
  3. Click the Add New App button at the top of the screen to display the new application window:
  4. Enter the name of your application in the App Name field and click the Create new app button:
  5. Copy the key from the Copy the API Key field to your clipboard. This will be needed later to initialize the Xamarin Insights NuGet in your application:
  6. Return to the projects dashboard and the new application will be displayed:

With the application registered with the Xamarin Insights Dashboard, we are ready to open our Xamarin project and include the Xamarin Insights NuGet.

2. Installing the Xamarin Insights NuGet

Xamarin Insights is provided as a NuGet package and can be included in any supported application.

With the application registered with the Xamarin Insights Dashboard, we need to install the Xamarin Insights NuGet so that we can include analytics and crash reporting.

To include it in your application's project, do the following:

  1. Start Visual and open the solution for the application that we want to include Xamarin Insights into.
  2. In the Solution Explorer, right-click on your project and select Manage NuGet Packages...
  3. The NuGet Package Manager will be displayed. In the Search Box enter Xamarin.Insights and press Enter:
  4. Select the Xamarin.Insights entry and click the Install button at the bottom of the dialog to insert the library and close the dialog.

For more information on including a NuGet package, please see the NuGet Package Installation walkthrough.

With the Xamarin Insights NuGet added to the application, we're ready to implement Xamarin Insights and start collecting analytics and crash reports.

3. Configure Xamarin Insights in your app

Once the app has been configured in the dashboard, follow the instructions below to configure your app for each platform:

Android

Minimum requirements

Note that the minimum API level currently supported for Xamarin.Android is 14.

Initialization

When including Xamarin Insights in a Xamarin.Android mobile application, initialization should be performed in the Launch Activity (this is the Activity with MainLauncher = true in it's definition code). Alternatively, if a singleton model is being employed, the registration can be called from there.

Open the Launch Activity and add the following lines of code to the OnCreate method:

using Xamarin;

        ...

        protected override void OnCreate (Bundle bundle)
        {
            base.OnCreate (bundle);

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

            ...
        }

Your API Key is the API Key that we copied from the Xamarin Insights Dashboard.

Note that the minimum API level currently supported for Xamarin.Android is 14.

Android Required Permissions

In addition to registering your API Key with the Xamarin Insights NuGet, there are several Android Permissions that need be set for Xamarin Insights to work correctly.

Xamarin Insights for Android requires the INTERNET permission to be enabled, allowing the device to send logging data to the service.

Permission Reason
INTERNET To communicate with Insights cloud service

Android Optional Permissions

The following optional permissions can also be included to enhance Xamarin Insights performance and functionality on Android:

Permission Reason
ACCESS_NETWORK_STATE To check the state of the network before communication
ACCESS_WIFI_STATE To check the state of the network before communication
BATTERY_STATS To check the state of the battery when submitting reports
BIND_NOTIFICATION_LISTENER_SERVICE To enable Android native crash reports
READ_EXTERNAL_STORAGE To check the size and free space of any external storage
READ_PHONE_STATE To allow access to the `deviceid`. The `deviceid` is used as part of the Google Advertising system. It is a unique id on all devices that can be used for targeting.
READ_LOGS To enable android native crash reports. This is useful while debugging the application because the Android runtime exception will be sent to the Insights Service in addition to the .NET exception. The Android runtime exception will show if there is a problem within the Java runtime rather than with Xamarin.Android.

Enabling Permissions

For instructions on enabling permissions on Android, follow the steps listed in the Add Permissions to Android Manifest guide.

Note: By adding additional permissions to your Xamarin.Android application the user will be prompted to agree to these when they download and install your app. Be aware that some users may choose not to download apps if they feel the permission level exceeds their level of comfort or they can opt out of the permissions that you have selected.

iOS

Minimum Requirements

Insights is only supported on applications targeting iOS 7 and above.

Initialization

When including Xamarin Insights in a Xamarin.iOS mobile application, registration should occur within the static Main() method in the Application class.

Copy Your API Key from the Xamarin Insights dashboard

Open Main.cs in your Xamarin.iOS project and add Initialize("Your API Key") to the static Main() method as shown below:

public class Application
    {
        // This is the main entry point of the application.
        static void Main (string[] args)
        {
            // Initialize Insights
            Xamarin.Insights.Initialize("Your API Key");

            // if you want to use a different Application Delegate class from "AppDelegate"
            // you can specify it here.
            UIApplication.Main (args, null, "AppDelegate");
        }
    }

Windows Phone

When including Xamarin Insights in a Windows Phone application, registration should occur when the application first launches.

Edit the Windows Phone application and add the following lines:

using Xamarin;
    ...

    public OnLaunched()
    {
      Insights.Initialize("Your API Key");

      ...

    }

Where Your API Key is the API Key displayed in the Xamarin Insights Dashboard.

Windows Phone 8 Capabilities

Windows Phone 8 requires the IDCAPIDENTIFY_DEVICE capability to function.

Xamarin.Forms

Because the Insights.Initialize method is platform specific, you'll need to install the Xamarin Insights NuGet into all projects in a Xamarin.Forms solution. Use the Initialize instructions from the Android, iOS, and Windows Phone sections to perform the registration in the platform-specific projects of a Xamarin.Forms solution:

After the registration has occurred, calling the remaining Xamarin Insights methods can be handled from within the Xamarin.Forms PCL or Shared Project code.

Refer to the Using Xamarin Insights sample for Xamarin.Forms to see how Xamarin Insights can be implemented.

View Reports

To view the data collected from your apps, visit insights.xamarin.com to view the data collected from your apps.

The types of reports available are discussed in the Insights Dashboard section.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.