Track usage events and metrics in your Windows app

Visual Studio 2013

Insert a few lines of code into your app to get the most useful results when you monitor your Windows device apps using Microsoft Application Insights.

Caution note Caution

This is about the older version of Application Insights in Visual Studio Online. There’s a new version in Microsoft Azure. The new version has a significantly different API.

How do I know which I’m using, and how do I choose?

Insert code in your app to log events that you’d like to know about.

For example, suppose your app is a game. You'd like to know how often users complete the game. Insert a line like this in the code that ends the game:

clientAnalyticsChannel.logEvent("Store/EndOfGame");

If you use "/" to separate the event name into elements, the report organizes the events into a hierarchy. Don’t use '/' as the first character. Anything after ‘?’ or ‘#’ will be ignored.

Publish your app in Windows Store. When users try your game, you'll see events appearing under USAGE, Features. The first events might take an hour to appear. In this example, we also logged an event for the start of each game.

Choose USAGE, Features, Events

Why did we prefix our event names with Store/? If your application has several components, such as a Store app, a Phone app and web pages, their events will all appear on the same events page. One way to keep them distinct is to give different prefixes to the events logged by different components.

Add metrics to events

You'd also like to know whether your game is too difficult or too easy. You can report a numeric parameter along with an event:

var properties = new Windows.Foundation.Collections.PropertySet();
properties["Score"] = userScore;
clientAnalyticsChannel.logEvent("Store/EndOfGame", properties);

In the event chart, you'll see the minimum, average, and maximum scores.

You can include no more than one numeric value with each event.

Add dimensions to events

You can send other string values. They will be interpreted as dimensions that can be used to filter and sort events. For example, if your app provides several games, you’ll want to send the name of the game so that you can see how popular each game is:

var properties = new Windows.Foundation.Collections.PropertySet();
properties["Score"] = userScore;
properties["Game"] = currentGame.name;
properties["Difficulty"] = currentGame.diffulty;
clientAnalyticsChannel.logEvent("Store/EndOfGame", properties);

You can report as many string values as you like with each event.

Security noteSecurity Note

Take care not to log personally identifiable information in properties.

Timed events let you find out how long users typically spend in a task, or how long an operation such as a web access takes. Call StartTimedEvent() to get a token at the start of the task. The event is logged when you dispose the token or call End().

In this example, the C# using construct is used to dispose the token:

using (TimedAnalyticsEvent token =
      ClientAnalyticsChannel.Default.StartTimedEvent("EventName"))
{
   // Add dimension data that can be used to filter the reports:
   token.Properties.Add("Key", "Value"); 
   var transactionCanceled = false; 
   // ... perform your transaction here ...
   // ... set transactionCanceled if there's a problem ...
   if (transactionCanceled) { token.Cancel(); }
} // Event is logged here. 

For a longer-lived task, or in other languages, it’s easier to call End() explicitly:

var token = clientAnalyticsChannel.startTimedEvent("EventName");
// ... perform the user task here ...
if (/*problem*/) token.cancel();
// ...
token.end(); // Log the event.

If you call Cancel() before End() or before the token is disposed, no event will be logged.

To log how your users navigate around your app, use LogPageView. Provide a name for your page, which can be separated into elements with “/”. These events are logged in the same way as other events, but the results appear in the Page Views report.

clientAnalyticsChannel.logPageView("Home/Settings"); 

The SDK automatically logs application lifecycle events such as startup and resume. These appear in the Page Views report under the hierarchy “app lifecycle/…”

Usually you set these properties in ApplicationInsights.config, in the root folder of your app project. The properties are defined inside the <ClientAnalytics> node. In the default config file, the Development and Production profiles have different property values.

You can also read and set them at runtime.

ClientAnalyticsSession Enabled

To disable data collection and transfer:

<ClientAnalytics enabled="false">...</ClientAnalytics>
ClientAnalyticsSession.Default.Enabled = false;
clientAnalyticsSession.enabled = false;

We recommend that you bind this property to a UI element to allow users to prevent data collection if they want.

[Windows Store apps] Users can also disable upload by clearing the Advertising setting in PC Settings.

ResumeAppRestartTimeout

This affects the count of sessions that appears in the USAGE pages. If a user suspends your app for more than this period, Application Insights will consider that a session has ended, and count the next period of use as a new session. In the default Development profile, this is set to 5 seconds so that you can test session counts. In the Production profile, it’s set to 300 seconds.

<ResumeAppRestartTimeoutSeconds>60</ResumeAppRestartTimeout>
ClientAnalyticsSession.Default.ResumeAppRestartTimeout = TimeSpan.FromSeconds(60);
//60 seconds in millisecond units: 
clientAnalyticsSession.resumeAppRestartTimeout = 60000; 
SendToRawStream

Send data to the Raw Event tile and Diagnostics/Streaming page. In the default config file, this is true in the Development profile and false in the Production profile.

<SendToRawStream>true</SendToRawStream>
CollectMachineName

Send the phone or emulator name with events to report in the raw stream data, so that you can distinguish events sent by different members of the development team. In the default config file, this is true in the Development profile.

<CollectMachineName>true</CollectMachineName>
ApplicationInsightsId

The ID that determines the application component under which your data appears in Application Insights.

string applicationInsightsId = ClientAnalyticsSession.Default.ApplicationInsightsId;
var applicationInsightsId = clientAnalyticsSession.applicationInsightsId;
AppUserId

Set this to allow app sessions to be tracked by user instead of by device.

AnonymousId

A unique ID generated at the time of app installation by Application Insights to identify the device. You can send this ID to your web service, which in turn can use it in the server SDK for data correlation.

SessionId

A unique ID generated every time a new ClientAnalyticsSession is started. You can send this ID to your service, which can use it in the server SDK for data correlation.

  • If you see configuration instructions on the USAGE pages, wait a few minutes and refresh the page.

  • To see data on the USAGE/Features pages, you have to insert some code to log events.

  • Make sure the time range selector at the top right of the graph includes today. If you’re on one of the pages with a small selector chart, drag across the chart to make sure the selected time range goes right up to the present time.

  • It can take an hour or so for the first data points to appear. Remember that the analysis pipeline is designed to aggregate data from many user sessions.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft