Getting Started with User Metrics

Introduction

With the HockeySDKs 4.0.0 and later, metrics data can get be sent to the HockeyApp backend and you can track adoption and usage for your app. For the iOS and UWP SDKs, user metrics are enabled by default upon updating to a new SDK. For Android, you need to manually add one line of code to enable metrics collection.

HockeyApp does not collect any PII (Personable Identifiable Information) and the user tracking is done anonymously, as described in this article.

Keep in mind that whenever the HockeySDK sends metric data to our backend, a corresponding app version gets automatically added to the app. Depending on your development process, this might result in a multitude of empty builds in HockeyApp. You can disable metrics collection for debug build as described in the platform-specific sections below.

Prerequisites

This getting started guide assumes you are an already existing HockeyApp customer and have already onboarded your application to use HockeyApp. If you are looking to onboard with a brand new app we suggest starting with our production getting started experience.

Limitations

  • Accepted characters for tracking events are: [a-zA-Z0-9_. -]. If you use other than the accepted characters, your events will not show up in the HockeyApp web portal.
  • There is currently a limit of 300 unique event names per app per week.
  • There is no limit on the number of times an event can happen.

If you are using custom properties and measurements

  • They require that you have bridged your app on HockeyApp to Application Insights.
  • Properties have to be a string.
  • Measurements have to be of a numeric type.
  • A key/name for a custom property or measurement can be up to 150 characters.
  • A property’s value can be up to 8192 characters.
  • There is no limit on the number of properties.

iOS, OS X and tvOS

Simply update the HockeySDK used in your app to a HockeySDK version later than 4.0.0. No code changes are needed. User Metrics will flow from your application automatically.

Binary

  • Download a HockeySDK version later than 4.0.0., which is provided as a zip-File.
  • Replace your HockeySDK.embeddedframework with the one from the zip file.
  • Make sure to do a clean build.

CocoaPods

  • Change your Podfile to point to our podspec:
  • for iOS: pod 'HockeySDK'
  • for OS X: pod 'HockeySDK-Mac'
  • for tvOS: pod 'HockeySDK-tvOS'
  • Run pod install for your project

Opting out of User Metrics

Just in case you want to opt-out of the automatic collection of anonymous users and sessions statistics, there is a way to turn this functionality off at any time:
[BITHockeyManager sharedHockeyManager].disableMetricsManager = YES;

Disabling User Metrics during development

Whenever our SDK sends metric data to our backend, we automatically add a corresponding app version to the app. During development, you might want to disable User Metrics. To disable data collection for debug builds, wrap the line above in a #ifdef block as follows:

#ifdef DEBUG 
  [BITHockeyManager sharedHockeyManager].disableMetricsManager = YES;
#endif

Android

Gradle

  • Update your HockeyApp dependency. The User Metrics feature is supported starting with 4.0.0:

    compile 'net.hockeyapp.android:HockeySDK:5.0.4'

  • Add the following line of code to your main activity's onCreate callback.

    MetricsManager.register(this, getApplication());

  • NOTE: if you haven't set your App-Identifier in your AndroidManifest.xml – either using the "manifest placeholder"-approach or having set it in the AndroidManifest.xml directly, use the overloaded register method that takes the app-id as a 3rd parameter.

Binary

  • If you have already integrated HockeyApp using Android Studio, we recommend removing it first before replacing it with the new binary.
  • Follow the instructions on integrating the Android SDK binary and use a HockeySDK version later than 4.0.0.
  • Add the following line of code to your main activity's onCreate callback.

    MetricsManager.register(this, getApplication());

  • NOTE: If you haven't set your App-Identifier in your AndroidManifest.xml – either using the "manifest placeholder"-approach or having set it in the AndroidManifest.xml directly, use the overloaded register method that takes the App-Identifier as a 3rd parameter.

Opting out of User Metrics

On Android, User Metrics are opt-in, so you only activate them if you want to make use of the feature.

Disabling User Metrics during development

Whenever our SDK sends metric data to our backend, we automatically add a corresponding app version to the app. If you're working on a new version, you might not want to send User Metrics. You can disable data collection for debug builds as follows:

if (!BuildConfig.DEBUG) {
        MetricsManager.register(this, getApplication());
}

Universal Windows 10

All HockeySDK.UWP support User Metrics. Once you integrate the SDK in your app, User Metrics will start flowing automatically. The HockeySDK.UWP is a .Net SDK for Universal Windows 10 Applications (UWP). This is a new SDK and you have to integrate it from scratch. Make sure to uninstall previous HockeySDKs from your app.

  • Add HockeySDK.UWP nuget package: Install-Package HockeySDK.UWP

  • In the App class constructor add the following line: Microsoft.HockeyApp.HockeyClient.Current.Configure(“Your_App_ID”);

  • Enable Internet(Client) Capability in package manifest

Opting out of User Metrics

Just in case you want to opt-out of the automatic collection of anonymous users and sessions statistics, there is a way to turn this functionality off at any time by setting the Collectors property on the TelemetryConfiguration object when you initialize the SDK as follows:

Microsoft.HockeyApp.HockeyClient.Current.Configure("Your_App_ID",
       new Microsoft.HockeyApp.TelemetryConfiguration()
        {
            Collectors = WindowsCollectors.Metadata | WindowsCollectors.UnhandledException
        });

Disabling User Metrics during development

Whenever our SDK sends metric data to our backend, we automatically add a corresponding app version to the app. If you're working on a new version, you might not want to send User Metrics. You can disable data collection for debug builds as follows:

#if DEBUG
Microsoft.HockeyApp.HockeyClient.Current.Configure("Your_App_ID",
       new Microsoft.HockeyApp.TelemetryConfiguration()
        {
            Collectors = WindowsCollectors.Metadata | WindowsCollectors.UnhandledException
        });
#endif