CSharpAnalytics is a C# library for tracking your application metrics via Google Analytics.
Why add metrics to your app?
Metrics let you see what's actually happening with your app in the real world. Crash rates, performance data, feature usage content popularity let you find out what is important to your users and where to spend your effort.
Why use Google Analytics?
Google Analytics is capable, well-supported, easy to use and free. While originally designed for web analytics it is gaining more and more app-specific metrics. The forthcoming Measurement Protocol adds even more with screen views, device breakout and crash data.
Why the CSharpAnalytics project?
This is the best solution for C# apps wanting to talk to Google Analytics. Why?
- Ease of use - add two lines to your Windows 8 Store app
- Pure C# - easy to debug, extend or port (no JavaScript, web views or DLLs)
- Feature rich - offline, configurable, OS stats
Our goal is to support all major C# platforms. Right now we have project files for:
- Windows 8 Store applications (Visual Studio 2012)
- .NET 4.5 applications (Visual Studio 2012)
Windows 8 Store support also includes a sample app and AutoAnalytics to add basic analytics to your app with just two lines of code.
- Offline and online support
- Configurable upload interval, over HTTPS/SSL if required
- Support for page views, events, timed events, social events, custom variables
- Manages visitor and session state
- Can auto-hook into a number of interesting events
- Built-in debug output window support (ga_debug.js style)
- Tracks operating system and version
- Helpers for device model, processor architecture
You will need:
- Google Analytics account - Head to http://analytics.google.com and sign-up if you don't have one
- Analytics property set-up as a web site
If you want to set-up your Analytisc property as an App then try out our experimental AutoMeasurement and MeasurementAnalyticsClient classes.
Download or clone the source and add a reference to CSharpAnalytics.WindowsStore from your application.
The easiest way to start is to use the AutoAnalytics class. It hooks into a few events and will automatically give you:
- Application launch/suspend events
- Visitor, session counts, time-spent
- Social sharing events
- Basic page navigation activity
- Unhandled exception details
To use it simply add two lines to your App.xaml.cs:
Start analytics with this line in App.OnLaunched directly before Window.Current.Activate() - replace the configuration values with your own.
await AutoAnalytics.StartAsync(new UrchinConfiguration("UA-319000-10", "sample.csharpanalytics.com"));
Stop analytics with this line in App.OnSuspending directly before deferral.Complete()
await AutoAnalytics.StopAsync();
Check out the CSharpAnalytics.Sample.WindowsStore application if still unsure of usage.
AutoAnalytics is a start but you'll certainly want to go further.
For pages that display content from a data source
Add ITrackPageView to your page to stop AutoAnalytics from tracking it and instead track it yourself once the content is loaded - we recommend the end of the LoadState method with something like:
AutoAnalytics.Client.TrackPageView(item.Title, "/news/" + item.Id);
For additional user events
Say you want to track when the video "Today's News" is played back:
AutoAnalytics.Client.TrackEvent("Play", "Video", "Today's News");
For timing
If you want to track how long something takes:
var timedActivity = new AutoTimedEventActivity("Loading", "Pictures");
// do something that takes time
AutoAnalytics.Client.Track(timedActivity);
Privacy is very important to Google and Microsoft and it should be to you too. Here's a few things you should know:
- Google's Measurement Protocol / SDK Policy (do not track personally identifyable information)
- Microsoft's Windows 8 app certification requirements (include a privacy policy with your app)
- AnonymizeIp is set to true by default. We recommend you leave this on as it scrubs the last IP octet at Google's end.
- Do not track the names of user-generated content. e.g. Page titles for mail apps or photo album apps.
In summary: Do not share personally identifyable information
- E-commerce tracking (Windows Store already has its own)
- Campaign tracking (limited use as Windows Store doesn't pass through parameters)
- Custom dimensions/parameters for Measurement Protocol
- Additional platforms (Windows Phone 7/8, Silverlight, Mono)
- Opt-out support via session state switch and null receiver
- Throttling of hits as per official SDKs
- Persist and restore session and visitor custom variables
If you want to contribute please consider the CSharpAnalytics.sln which will load all platforms and unit tests.
Copyright 2012-2013 Attack Pattern LLC
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.