Step 1 - Install the NuGet package
Raygun4UWP is available as a NuGet package. Using your IDE of choice, or the package manager console, install the Raygun4UWP NuGet package into your project. More information about the NuGet package can be found here.
Step 2 - Configure Raygun
The most basic setup of Raygun4UWP can be achieved with a single line of code. Place the following code within the App.xaml.cs constructor. Your app API key is displayed on the instructions page, whenever you create a new application in Raygun. You can also find the API key by clicking the "Application Settings" button in the side menu of the Raygun app.
Here is a break down of what this does:
Initialize creates a new RaygunClient and sets it on the static RaygunClient.Current property. This is so you can access the RaygunClient instance anywhere in your code to adjust settings, or manually send data to Raygun.
EnableRealUserMonitoring will cause the RaygunClient to listen to the app suspending and resuming events to automatically send session start and end events to Raygun. A session start event will also be sent at this stage to indicate that your application has just started up.
Step 3 - Wire up navigation events
Navigation in a UWP application can be implemented in many different ways and there are no global navigation events to hook in to. Because of this, Raygun4UWP won't be able to automatically send page-view events to Raygun with the above setup alone. Instead, Raygun4UWP provides two mechanisms for sending navigation events to Raygun - the ListenToNavigation attached property and the ability to manually send events which are both explained directly below.
The ListenToNavigation attached property
The RaygunClient includes an attached property called
ListenToNavigation which currently supports the
Frame element. This will attach event handlers
to the loading/loaded and navigating/navigated events, allowing Raygun4UWP to measure the time it takes to perform a Frame navigation and send an event to Raygun.
The name of the event will be the name of the page class type that was navigated to.
To do this in XAML, first add the Raygun4UWP namespace to the top level tag of a page that contains a Frame that you want to track:
<MainPage xmlns:raygun="using:Raygun4UWP"> ... </MainPage>
And then set the attached property to true on the Frame element:
<Frame raygun:RaygunClient.ListenToNavigation="True" />
Alternatively, here's an example of setting this up in C#:
Manually sending RUM events
RaygunClient includes methods for sending the three different types of RUM events:
Sends a session start event to Raygun. All subsequent events will fall under this session. If there is currently an active session, then it will first be ended before a new one is started.
A timing event is made up of a type, a name and a duration in milliseconds. The type is an enum value which can either be
The name can be whatever you want - pick something that helps you identify the event when viewing the data in Raygun.
Where possible, time how long the event takes so that you can collect performence metrics.
If it's not possible, or it doesn't make sense for an event to have a duration, then you can leave it as zero.
If this method is called when there isn't currently an active session, then a new session will be started first.
Ends any currently open session and sends a session end event to Raygun. Any subsequent event will cause a new session to be started. If there currently isn't an active session, then calling this method does nothing.
Unique user tracking
By default, a random GUID will be stored in the roaming data of your application. This will be included as a unique user identifier on all session events sent to Raygun. This is a non-identifiable way to get statistics about how many unique users are affected by exceptions.
If you want to include more information about the user of each session, there are two different ways that you can do this as described below. Please be aware of any company privacy policies you have when choosing what type of user information you send to Raygun.
The User property
If all you need to identify a user is a single string, then you can set the
Note that setting this to null or whitespace will cause the default random GUID descibed above to be used.
This string can be whatever you like. Below are some common suggestions.
- Identifying information such as name or email address.
- An id that doesn't reveal any information about the user, but can be looked up in your own systems to find out who the user is.
- Your own random string if you don't want to use the one Raygun stores in roaming app data. This may however result in unreliable user statistics in Raygun.
The UserInfo property
If a single string is not enough to describe the information that you want to log about a user, then you can set the
Below are the various properties that you can use to describe the user. The Identifier is the only required field, which can be provided through the constructor.
- Identifier The unique identifier you want to use to identify this user. Suggestions for what you could set this to are listed in the User property section above.
- IsAnonymous A flag indicating whether the user is logged in (or identifiable) or if they are anonymous. An anonymous user still requires an identifier.
- UUID A device identifier. Could be used to identify users across devices, or machines that are breaking for many users.
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.
By default, each session will include the version of your application package. If you need to provide your own custom version value, you can do so by setting the ApplicationVersion property of the RaygunClient (in the format x.x.x.x where x is a positive integer).
RaygunClient.Current.ApplicationVersion = "18.104.22.168";
The provider is open source and available at the Raygun4UWP repository.