Xamarin.Forms

Installation

Step 1 - Install Raygun

The provider targets .NET Standard 2.0 and is available as a NuGet package.

The currently supported platforms are Android and iOS with the following versions or newer:

• Xamarin.Android 8.0
• Xamarin.iOS 10.0

The best way to install Raygun4Xamarin.Forms is to use use the dotnet cli tool. In your project folder run dotnet add package Raygun4Xamarin.Forms to install it.

Alternatively, visit https://www.nuget.org/packages/Raygun4Xamarin.Forms/ for instructions on installation.

Step 2 - Configure and enable Raygun

The initialisation of Raygun and the enabling of Real User Monitoring (RUM) must occur early in the app's initial startup phase. We recommend doing this in the constructor of your Application class. Using the static Init method will also ensure a shared RaygunClient instance is available through the static property Current.

public partial class App : Application
{
  public App()
  {
    InitializeComponent();

    // Initialising the Raygun client 
    RaygunClient.Init("paste_your_api_key_here");
    RaygunClient.Current.EnableRealUserMonitoring();

    // Remaining application setup logic
    MainPage = new MainPage();
  }
}

Each platform being targeted requires an additional configuration step using the RaygunPlatform class in the following places.

For Android:

public class MainActivity : global::Xamarin.Forms.Platform.Android.FormsAppCompatActivity
{
  protected override void OnCreate(Bundle savedInstanceState)
  {
    // MainActivity startup logic
    base.OnCreate(savedInstanceState);
    global::Xamarin.Forms.Forms.Init(this, savedInstanceState);
    LoadApplication(new App());

    // Configure Raygun for the current platform
    RaygunPlatform.Configure(this);
  }
}

For iOS:

public partial class AppDelegate : global::Xamarin.Forms.Platform.iOS.FormsApplicationDelegate
{
  public override bool FinishedLaunching(UIApplication app, NSDictionary options)
  {
    // AppDelegate startup logic
    global::Xamarin.Forms.Forms.Init();
    LoadApplication(new App());

    // Configure Raygun for the current platform
    RaygunPlatform.Configure();

    return base.FinishedLaunching(app, options);
  }
}

Once RUM is enabled, you are able to:

• Automatically report user sessions
• Automatically report view timing events
• Manually report timing events

Unique User Tracking

By default, the Raygun client will give a GUID (Globally Unique Identifier) to each user for distinguishing between them. If possible, we highly recommend providing your own unique identifiers for your users which can be done with the code below. The string you pass into the constructor can be whatever unique user id that works best for you - email address is a recommended example. Providing the first name and full name is optional.

RaygunClient.Current.User = new RaygunUserInfo("_UNIQUE_ID_")
{
  FirstName   = "Ronald",
  FullName    = "Ronald Raygun",
  Email       = "ronald@raygun.com",
  IsAnonymous = false
};

The string properties on a User have a maximum length of 255 characters. Users who have fields that exceed this amount will not be processed.

Automatic timing events

RUM will automatically track page navigations and page load times in your app. A page's load time is measured as the time between the previous page's PageDisappearing event being fired and the current page's PageAppearing event being fired. In the situation where a page is the first page to load, the load time is calculated as the time between the OnResumed event (for Android) or the viewDidAppear (for iOS) and the PageAppearing event of the first page.

Automatic timing events are enabled by default. If you wish to implement your own page tracking, you can disable this feature by setting TrackPageNavigation to false.

var settings = new RaygunSettings("_API_KEY_") 
{ 
  TrackPageNavigations = false,
};

// Initialise a client instance.
var client = RaygunClient.Init(settings);

Manually report timing events

RUM will automatically record information about mobile views when enabled, however timing events can also be manually reported using the client. The following snippet demonstrates how to record a custom timing event for a view. Manually recorded events will also appear within a users session that is displayed within the Raygun web application.

RaygunClient.Current.SendTimingEvent(RaygunRUMEventTimingType.ViewLoaded, "TestView", 123);

Automatic network monitoring

The client has the ability to automatically record the time it takes for native network requests to complete. The performance of HTTP/S network requests made with the following classes will be recorded:

iOS: NSURLSession
Android: java.net.URLConnection

This functionality can be enabled through the client and should be done right after enabling RUM.

public partial class App : Application
{
  public App()
  {
    InitializeComponent();

    // Initialising the Raygun client 
    RaygunClient.Init("_API_KEY_");
    RaygunClient.Current.EnableRealUserMonitoring();
    RaygunClient.Current.EnableNetworkPerformanceMonitoring();

    // Remaining application setup logic
    MainPage = new MainPage();
  }
}

Version tracking

The Raygun client supports tracking a version of your application that is in use. This is helpful to determine just how many users are adopting the newer versions of your application and how many users are staying on legacy versions.

var settings = new RaygunSettings("_API_KEY_") 
{ 
  ApplicationVersion = "1.0.0",
};

// Initialise a client instance.
var client = RaygunClient.Init(settings);

Internal logging

For debugging purposes, you can set the level of logging that the provider will print to your debug console. This can be helpful to determine what information is or is not being sent to the Raygun API. The logging level can be set before initialising the Raygun client.

var settings = new RaygunSettings("_API_KEY_") 
{ 
  LogLevel = LogLevel.Verbose
};

// Initialise a client instance.
var client = RaygunClient.Init(settings);