HockeyApp for macOS

This document contains the following sections:

  1. Requirements
  2. Setup
  3. Advanced Setup
    1. Setup with CocoaPods
    2. OS X Extensions
    3. Crash Reporting
    4. Feedback
    5. Metrics
    6. Sparkle
    7. Debug information
  4. Documentation
  5. Upload the .dSYM File
  6. Troubleshooting

1. Requirements

  1. We assume that you already have a project in Xcode and that this project is opened in Xcode 6 or later.
  2. The SDK supports OS X 10.7 and later.

2. Setup

We recommend integration of our binary into your Xcode project to setup HockeySDK for your OS X app. You can also use our interactive SDK integration wizard in HockeyApp for Mac which covers all the steps from below. For other ways to setup the SDK, see Advanced Setup.

2.1 Obtain an App Identifier

Please see the "How to create a new app" tutorial. This will provide you with an HockeyApp specific App Identifier to be used to initialize the SDK.

2.2 Download the SDK

  1. Download the latest HockeySDK-Mac framework which is provided as a zip-File.
  2. Unzip the file and you will see a folder called HockeySDK-Mac. (Make sure not to use 3rd party unzip tools!)

2.3 Copy the SDK into your projects directory in Finder

From our experience, 3rd-party libraries usually reside inside a subdirectory (let's call our subdirectory Vendor), so if you don't have your project organized with a subdirectory for libraries, now would be a great start for it. To continue our example, create a folder called Vendor inside your project directory and move the unzipped HockeySDK-Mac-folder into it.

2.4 Set up the SDK in Xcode

  1. We recommend to use Xcode's group-feature to create a group for 3rd-party-libraries similar to the structure of our files on disk. For example, similar to the file structure in 2.3 above, our projects have a group called Vendor.
  2. Make sure the Project Navigator is visible (⌘+1)
  3. Drag & drop HockeySDK.framework from your window in the Finder into your project in Xcode and move it to the desired location in the Project Navigator (e.g. into the group called Vendor)
  4. A popup will appear. Select Create groups for any added folders and set the checkmark for your target. Then click Finish.
  5. Now we’ll make sure the framework is copied into your app bundle:

    • Click on your project in the Project Navigator (⌘+1).
    • Click your target in the project editor.
    • Click on the Build Phases tab.
    • Click the Add Build Phase button at the bottom and choose Add Copy Files.
    • Click the disclosure triangle next to the new build phase.
    • Choose Frameworks from the Destination list.
    • Drag HockeySDK-Mac from the Project Navigator left sidebar to the list in the new Copy Files phase.
  6. Make sure to sign the app, since the SDK will store user related input in the keychain for privacy reasons

2.5 Modify Code

Objective-C

  1. Open your AppDelegate.m file.
  2. Add the following line at the top of the file below your own import statements:

    @import HockeySDK;
    
  3. Search for the method applicationDidFinishLaunching:

  4. Add the following lines to setup and start the HockeySDK:

    [[BITHockeyManager sharedHockeyManager] configureWithIdentifier:@"APP_IDENTIFIER"];
    // Do some additional configuration if needed here
    [[BITHockeyManager sharedHockeyManager] startManager];
    

Swift

  1. Open your AppDelegate.swift file.
  2. Add the following line at the top of the file below your own import statements:

    import HockeySDK
    
  3. Search for the method applicationWillFinishLaunching

  4. Add the following lines to setup and start the HockeySDK:

    BITHockeyManager.sharedHockeyManager().configureWithIdentifier("APP_IDENTIFIER");
    // Do some additional configuration if needed here
    BITHockeyManager.sharedHockeyManager().startManager();
    

Note: In case of document based apps, invoke startManager at the end of applicationDidFinishLaunching, since otherwise you may lose the Apple events to restore, open untitled document etc.

If any crash report has been saved from the last time your application ran, startManager will present a dialog to allow the user to submit it. Once done, or if there are no crash logs, it will then call back to your appDelegate with showMainApplicationWindowForCrashManager: (if implemented, see Improved startup crashes handling).

Congratulation, now you're all set to use HockeySDK!

3. Advanced Setup

3.1 Setup with CocoaPods

CocoaPods is a dependency manager for Objective-C, which automates and simplifies the process of using 3rd-party libraries like HockeySDK in your projects. To learn how to setup CocoaPods for your project, visit the official CocoaPods website.

Podfile

platform :osx, '10.7'
pod "HockeySDK-Mac"

3.2 OS X Extensions

The following points need to be considered to use HockeySDK with OS X 10.10 Extensions:

  1. Make sure the framework is copied into the extension bundle, see step 4 above under Set up Xcode
  2. Each extension is required to use the same values for version (CFBundleShortVersionString) and build number (CFBundleVersion) as the main app uses. (This is required only if you are using the same APP_IDENTIFIER for your app and extensions).
  3. Enable Incoming Connections (Server) and Outgoing Connections (Client) in the Capabilities tab of the extension target under App Sandbox.
  4. You need to make sure the SDK setup code is only invoked once and automatic submission of crash reports is enabled. Since there is no application:didFinishLaunchingWithOptions: equivalent and viewDidLoad can run multiple times, you need to use a setup like the following example:

    @interface TodayViewController () <NCWidgetProviding>
    
    @property (nonatomic, assign) BOOL didSetupHockeySDK;
    
    @end
    
    @implementation TodayViewController
    
    - (void)viewDidLoad {
      [super viewDidLoad];
      if (!self.didSetupHockeySDK) {
        [[BITHockeyManager sharedHockeyManager] configureWithIdentifier:@"APP_IDENTIFIER"];
        [[BITHockeyManager sharedHockeyManager].crashManager setAutoSubmitCrashReport:YES];
        [[BITHockeyManager sharedHockeyManager] startManager];
        self.didSetupHockeySDK = YES;
      }
    }
    

3.3 Crash Reporting

The following options only show some of possibilities to interact and fine-tune the crash reporting feature. For more please check the full documentation of the BITCrashManager class in our documentation.

3.3.1 Disable Crash Reporting

The HockeySDK enables crash reporting per default. Crashes will be immediately sent to the server the next time the app is launched.

To provide you with the best crash reporting, we are using PLCrashReporter in Version 1.2 / Commit 273a7e7cd4b77485a584ac82e77b7c857558e2f9.

This feature can be disabled as follows:

[[BITHockeyManager sharedHockeyManager] configureWithIdentifier:@"APP_IDENTIFIER"];

[[BITHockeyManager sharedHockeyManager] setDisableCrashManager: YES]; //disable crash reporting

[[BITHockeyManager sharedHockeyManager] startManager];

3.3.2 Autosend crash reports

Crashes are send the next time the app starts. If crashManagerStatus is set to BITCrashManagerStatusAutoSend, crashes will be send without any user interaction, otherwise an alert will appear allowing the users to decide whether they want to send the report or not.

[[BITHockeyManager sharedHockeyManager] configureWithIdentifier:@"APP_IDENTIFIER"];

[[BITHockeyManager sharedHockeyManager].crashManager setAutoSubmitCrashReport: YES];

[[BITHockeyManager sharedHockeyManager] startManager];

The SDK is not sending the reports right when the crash happens deliberately, because if is not safe to implement such a mechanism while being async-safe (any Objective-C code is NOT async-safe!) and not causing more danger like a deadlock of the device, than helping. We found that users do start the app again because most don't know what happened, and you will get by far most of the reports.

Sending the reports on startup is done asynchronously (non-blocking). This is the only safe way to ensure that the app won't be possibly killed by the iOS watchdog process, because startup could take too long and the app could not react to any user input when network conditions are bad or connectivity might be very slow.

3.3.3 Catch additional exceptions

On Mac OS X there are three types of crashes that are not reported to a registered NSUncaughtExceptionHandler:

  1. Custom NSUncaughtExceptionHandler don't start working until after NSApplication has finished calling all of its delegate methods!

    - (void)applicationDidFinishLaunching:(NSNotification *)note {
      ...
      [NSException raise:@"ExceptionAtStartup" format:@"This will not be recognized!"];
      ...
    }
    
  2. The default NSUncaughtExceptionHandler in NSApplication only logs exceptions to the console and ends their processing. Resulting in exceptions that occur in the NSApplication "scope" not occurring in a registered custom NSUncaughtExceptionHandler.

    - (void)applicationDidFinishLaunching:(NSNotification *)note {
      ...
      [self performSelector:@selector(delayedException) withObject:nil afterDelay:5];
      ...
    }
    
    - (void)delayedException {
      NSArray *array = [NSArray array];
      [array objectAtIndex:23];
    }
    
  3. Any exceptions occurring in IBAction or other GUI does not even reach the NSApplication default UncaughtExceptionHandler.

    - (IBAction)doExceptionCrash:(id)sender {
      NSArray *array = [NSArray array];
      [array objectAtIndex:23];
    }
    

In general there are two solutions. The first one is to use an NSExceptionHandler class instead of an NSUncaughtExceptionHandler. But this has a few drawbacks which are detailed in BITCrashReportExceptionApplication.h.

Instead we provide the optional NSApplication subclass BITCrashExceptionApplication which handles cases 2 and 3.

Installation:

  • Open the applications Info.plist
  • Search for the field Principal class
  • Replace NSApplication with BITCrashExceptionApplication

Alternatively, if you have your own NSApplication subclass, change it to be a subclass of BITCrashExceptionApplication instead.

3.3.4 Attach additional data

The BITHockeyManagerDelegate protocol provides methods to add additional data to a crash report:

  1. UserID: - (NSString *)userIDForHockeyManager:(BITHockeyManager *)hockeyManager componentManager:(BITHockeyBaseManager *)componentManager;
  2. UserName: - (NSString *)userNameForHockeyManager:(BITHockeyManager *)hockeyManager componentManager:(BITHockeyBaseManager *)componentManager;
  3. UserEmail: - (NSString *)userEmailForHockeyManager:(BITHockeyManager *)hockeyManager componentManager:(BITHockeyBaseManager *)componentManager;

The BITCrashManagerDelegate protocol (which is automatically included in BITHockeyManagerDelegate) provides methods to add more crash specific data to a crash report:

  1. Text attachments: -(NSString *)applicationLogForCrashManager:(BITCrashManager *)crashManager

Check the following tutorial for an example on how to add CocoaLumberjack log data: How to Add Application Specific Log Data on iOS or OS X 2. Binary attachments: -(BITHockeyAttachment *)attachmentForCrashManager:(BITCrashManager *)crashManager

Make sure to implement the protocol

@interface YourAppDelegate () <BITHockeyManagerDelegate> {}

@end

and set the delegate:

[[BITHockeyManager sharedHockeyManager] configureWithIdentifier:@"APP_IDENTIFIER"];

[[BITHockeyManager sharedHockeyManager] setDelegate: self];

[[BITHockeyManager sharedHockeyManager] startManager];

3.4 Feedback

BITFeedbackManager lets your users communicate directly with you via the app and an integrated user interface. It provides a single threaded discussion with a user running your app. This feature is only enabled, if you integrate the actual view controllers into your app.

You should never create your own instance of BITFeedbackManager but use the one provided by the [BITHockeyManager sharedHockeyManager]:

[BITHockeyManager sharedHockeyManager].feedbackManager

Please check the documentation of the BITFeedbackManager class on more information on how to leverage this feature.

3.5 User Metrics

HockeyApp automatically provides you with nice, intelligible, and informative metrics about how your app is used and by whom.

  • Sessions: A new session is tracked by the SDK whenever the containing app is restarted (this refers to a 'cold start', i.e. when the app has not already been in memory prior to being launched) or whenever it becomes active again after having been in the background for 20 seconds or more.
  • Users: The SDK anonymously tracks the users of your app by creating a random UUID that is then securely stored in the iOS keychain. Because this anonymous ID is stored in the keychain it persists across reinstallations.
  • Custom Events: You can now track Custom Events in your app, understand user actions and see the aggregates on the HockeyApp portal.

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;

3.5.1 Custom Events

By tracking custom events, you can now get insight into how your customers use your app, understand their behavior and answer important business or user experience questions while improving your app.

  • 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.

Objective-C

BITMetricsManager *metricsManager = [BITHockeyManager sharedHockeyManager].metricsManager;

[metricsManager trackEventWithName:eventName]

Swift

let metricsManager = BITHockeyManager.sharedHockeyManager().metricsManager

metricsManager.trackEventWithName(eventName)

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.

3.5.2 Attaching custom properties and measurements to a custom event

It's possible to attach properties and/or measurements to a custom event.

  • Properties have to be a string.
  • Measurements have to be of a numeric type.

Objective-C

BITMetricsManager *metricsManager = [BITHockeyManager sharedHockeyManager].metricsManager;

NSDictionary *myProperties = @{@"Property 1" : @"Something",
                               @"Property 2" : @"Other thing",
                               @"Property 3" : @"Totally different thing"};
NSDictionary *myMeasurements = @{@"Measurement 1" : @1,
                                 @"Measurement 2" : @2.34,
                                 @"Measurement 3" : @2000000};

[metricsManager trackEventWithName:eventName properties:myProperties measurements:myMeasurements]

Swift

let myProperties = ["Property 1": "Something", "Property 2": "Other thing", "Property 3" : "Totally different thing."]
let myMeasurements = ["Measurement 1": 1, "Measurement 2": 2.3, "Measurement 3" : 30000]
      
let metricsManager = BITHockeyManager.sharedHockeyManager().metricsManager
metricsManager.trackEventWithName(eventName, properties: myProperties, myMeasurements: measurements)

3.6 Sparkle

3.6.1 Setup for beta distribution

  1. Install the Sparkle SDK: http://sparkle-project.org

As of today (03/2013), Sparkle doesn't support Mac sandboxes. If you require this, check out the following fork https://github.com/tumult/Sparkle and this discussion https://github.com/andymatuschak/Sparkle/pull/165

  1. Set SUFeedURL to https://rink.hockeyapp.net/api/2/apps/<APP_IDENTIFIER> and replace <APP_IDENTIFIER> with the same value used to initialize the HockeySDK

  2. Create a .zip file of your app bundle and upload that to HockeyApp.

3.6.2 Add analytics data to Sparkle setup

  1. Set the following additional Sparkle property:

    sparkleUpdater.sendsSystemProfile = YES;
    
  2. Add the following Sparkle delegate method (don't forget to bind SUUpdater to your appDelegate!):

    - (NSArray *)feedParametersForUpdater:(SUUpdater *)updater
                    sendingSystemProfile:(BOOL)sendingProfile {
        return [[BITSystemProfile sharedSystemProfile] systemUsageData];
    }
    
  3. Initialize usage tracking depending on your needs.

    On example scenario is when the app is started or comes to foreground and when it goes to background or is terminated:

    - (void)applicationWillFinishLaunching:(NSNotification *)aNotification
        …      
        NSNotificationCenter *dnc = [NSNotificationCenter defaultCenter];
        BITSystemProfile *bsp = [BITSystemProfile sharedSystemProfile];
        [dnc addObserver:bsp selector:@selector(startUsage) name:NSApplicationDidBecomeActiveNotification object:nil];
        [dnc addObserver:bsp selector:@selector(stopUsage) name:NSApplicationWillTerminateNotification object:nil];
        [dnc addObserver:bsp selector:@selector(stopUsage) name:NSApplicationWillResignActiveNotification object:nil];
        …
    };
    

3.7 Debug information

To check if data is send properly to HockeyApp and also see some additional SDK debug log data in the console, add the following line before startManager:

[[BITHockeyManager sharedHockeyManager] configureWithIdentifier:@"APP_IDENTIFIER"];

[BITHockeyManager sharedHockeyManager].logLevel = BITLogLevelDebug; // Add this before startManager

[[BITHockeyManager sharedHockeyManager] startManager];

4. Documentation

Additional HockeyApp Mac OS X SDK documentation can be found at:

5. Upload the .dSYM File

Once you have your app ready for beta testing or even to submit it to the App Store, you need to upload the .dSYM bundle to HockeyApp to enable symbolication. If you have built your app with Xcode4, menu Product > Archive, you can find the .dSYM as follows:

  1. Chose Window > Organizer in Xcode.

  2. Select the tab Archives.

  3. Select your app in the left sidebar.

  4. Right-click on the latest archive and select Show in Finder.

  5. Right-click the .xcarchive in Finder and select Show Package Contents.

  6. You should see a folder named dSYMs which contains your dSYM bundle. If you use Safari, just drag this file from Finder and drop it on to the corresponding drop zone in HockeyApp. If you use another browser, copy the file to a different location, then right-click it and choose Compress "YourApp.dSYM". The file will be compressed as a .zip file. Drag & drop this file to HockeyApp.

As an easier alternative for step 5 and 6, you can use our HockeyMac app to upload the complete archive in one step.

Multiple dSYMs

If your app is using multiple frameworks that are not statically linked, you can upload all dSYM packages to HockeyApp by creating a single .zip file with all the dSYM packages included and make sure the zip file has the extension .dSYM.zip.

Mac Desktop Uploader

The Mac Desktop Uploader can provide easy uploading of your app versions to HockeyApp. Check out the installation tutorial.

6. Troubleshooting

Checklist if Crashes Do Not Appear in HockeyApp

  1. Check if the APP_IDENTIFIER matches the App ID in HockeyApp.

  2. Check if CFBundleIdentifier in your Info.plist matches the Bundle Identifier of the app in HockeyApp. HockeyApp accepts crashes only if both the App ID and the Bundle Identifier equal their corresponding values in your plist and source code.

  3. If it still does not work, please contact us.