Getting Started with Custom Events (Public Preview)

Introduction

By tracking custom events, you can now get insights about how your customers use your app, understand their behavior and answer important business or experience questions while improving your app. To do that, you can utilize your domain knowledge to track exactly the telemetry you need exactly the way you want it. For instance, you might want to track how many purchases occur in your app, how many users start (or end) a level in a game, or how many times a request to the server has timed out. HockeyApp will provide aggregates for the tracked events, but you will not be able to drill down and see the details of a specific event that occurred.

Prerequisites

This guide assumes you 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 and get the latest stable SDK integrated into your preseason.

Limits

  • 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 350 unique event names per app per week.
  • There is NO limit on the number of times an event can happen.

Best Practices

  • Before starting to track events, ask yourself the questions that you want to get answers to. For instance, you might be interested in business, performance/quality or user experience aspects.
  • Name your events in a meaningful way and keep in mind that you will use these names when searching for events in the HockeyApp web portal. It is your reponsibility to not collect personal information as part of the events tracking.

iOS, OS X and tvOS

To track an event when an action is triggered, use the following method:

  • Swift
    let metricsManager = BITHockeyManager.sharedHockeyManager().metricsManager
    metricsManager.trackEventWithName(eventName)
    
  • Objective-C
    BITMetricsManager *metricsManager = [BITHockeyManager sharedHockeyManager].metricsManager;
    [metricsManager trackEventWithName:eventName]
    

Android

Please note that the User Metrics feature requires a minimum API level of 14.
If you haven't already done so, make sure to configure the MetricsManager first, by adding the following line of code to your main activity's onCreate callback.
MetricsManager.register(this, getApplication());

To track an event when an action is triggered, use the following method:
MetricsManager.trackEvent(eventName);

Universal Windows 10

To track an event when an action is triggered, use the following method:
Microsoft.HockeyApp.HockeyClient.Current.TrackEvent(eventName);

Xamarin

To track an event when an action is triggered, use the following method in your platform project:

  • iOS

    var manager = BITHockeyManager.SharedHockeyManager;
    manager.MetricsManager.TrackEvent (eventName);
    
  • Android

    HockeyApp.Metrics.MetricsManager.TrackEvent (eventName);
    

Cordova

To track an event when an action is triggered, use the following method:
hockeyapp.trackEvent(successCallback, errorCallback, eventName);

Test the event integration

Once you started tracking events, wait a few minutes until the results show up in the HockeyApp portal, under the Events tab in your app. You can get more information about a specific event by clicking on its name.