Crash Reporting on QuincyKit for iOS 3 (Old)

Important Note

This is a legacy SDK and should only be used if you require compatibility with iOS 3.x! Otherwise please use our current SDK, which you can find here: HockeyApp for iOS (HockeySDK)

Introduction

This how-to describes how to integrate the QuincyKit client into your app. The client allows testers to send crash reports right from within the application. It will ask the tester on the next startup if he wants to send the crash report and then submit the crash report to HockeyApp. If you have uploaded the .dSYM file, HockeyApp will automatically symbolicate the crash report so that you can analyze the stack trace including class, method and line number at which the crash happened.

QuincyKit can be integrated in apps for both AdHoc distribution and the App Store.

Screencast

Our friend Andreas Zeitler from zCasting 3000 has produced a nice screencast about integrating HockeyKit and QuincyKit into iOS apps. Watch it here.

Prerequisites

Before you integrate QuincyKit into your own app, you should create the app on HockeyApp if you haven't already. Read this how-to on how to do it.

We assume that you already have a project in Xcode and that this project is opened in Xcode 4. We will use our Pomodoro App as an example.

Versioning

We suggest to handle beta and release versions in two separate apps on HockeyApp with their own bundle identifier (e.g. by adding "beta" to the bundle identifier), so

  • both apps can run on the same device or computer at the same time without interfering,

  • release versions do not appear on the beta download pages, and

  • easier analysis of crash reports and user feedback.

We propose the following method to set version numbers in your beta versions:

  • Use both "Bundle Version" and "Bundle Version String, short" in your Info.plist.

  • "Bundle Version" should contain a sequential build number, e.g. 1, 2, 3.

  • "Bundle Version String, short" should contain the target official version number, e.g. 1.0.

HockeyKit Client

If you have already finished the integration of the HockeyKit client, you can skip the following steps until section "Modify Source Code".

Download & Extract

  1. Download the latest QuincyKit client files.

  2. Unzip the file. A new folder QuincyKit is created.

  3. Move the folder into your project directory. We usually put 3rd-party code into a subdirectory named "Vendor", so we move the directory into it.

Integrate into Xcode

Drag & drop the QuincyKit folder from your project directory to your Xcode project. Similar to above, our projects have a group "Vendor", so we drop it there. Select "Create groups for any added folders" and set the checkmark for your target. Then click "Finish".

Define Preprocessor Macros

As said above, we recommend to handle beta and release versions in separate apps on HockeyApp. We therefore define a preprocessor macro for all configurations and configure the client with different app identifiers depending on the build configuration.

  1. Select your project in the Project Navigator.

  2. Select your target.

  3. Select the tab "Build Settings".

  4. Enter "preprocessor macros" into the search field.

    XcodeMacros1.png

  5. As you can see in the screenshot, the Pomodoro project has 3 configurations: "Debug", "Beta" and "Distribution". For convenience, we want to define a preprocessor macro for all configurations. To do this, select the top-most line and double-click the value field.

  6. Click the + button.

  7. Enter the following string into the input field and finish with "Done".

    CONFIGURATION_$(CONFIGURATION)
    

    XcodeMacros2.png

Add Frameworks

  1. Select your project in the Project Navigator.

  2. Select your target.

  3. Select the tab "Build Phases".

  4. Expand "Link Binary With Libraries".

  5. You need all of the following frameworks:

* CoreGraphics.framework
* CrashReporter.framework
* Foundation.framework
* QuartzCore.framework
* SystemConfiguration.framework
* UIKit.framework
  1. If one of the frameworks is missing, then click the + button, search the framework and confirm with the "Add" button. The CrashReport.framework is included in the QuincyKit folder and should already be present if it was integrated as described above.

Modify Source Code

  1. Open your AppDelegate.m file.

  2. Add the following line at the top of the file below your own #import statements:

    #import "BWQuincyManager.h"
    
  3. Search for the method application:didFinishLaunchingWithOptions:

  4. Add the following lines:

    #if defined (CONFIGURATION_Beta) [[BWQuincyManager sharedQuincyManager] setAppIdentifier:@"BETA_APP_IDENTIFIER"]; #endif

    #if defined (CONFIGURATION_Distribution) [[BWQuincyManager sharedQuincyManager] setAppIdentifier:@"RELEASE_APP_IDENTIFIER"]; #endif

  5. For Pomodoro App, our configuration for AdHoc builds is called "Beta", the one for App Store builds is called "Distribution"; the resulting preprocessor macros are "CONFIGURATION_Beta" and "CONFIGURATION_Distribution". If your configurations have different names, you have to change the macros' names accordingly.

  6. Replace BETA_APP_IDENTIFIER with the app identifier of your beta app. If you don't know what the app identifier is or how to find it, please read this how-to.

  7. Replace RELEASE_APP_IDENTIFIER with the app identifier of your release app. For Pomodoro App, the final integration is shown in the following screenshot (including both HockeyKit and QuincyKit). Note how the app identifier is the same for HockeyKit and QuincyKit for our beta builds, but we use a different app and hence app identifier for release builds.

    XcodeAppDelegate2.png

  8. If you have added the lines to the method application:didFinishLaunchingWithOptions:, you should be ready to go. If you do some GCD magic or added the lines at a different place, please make sure to invoke the above code on the main thread.

Optional Delegate Methods

Besides the crash log, HockeyApp can show you fields with information about the user and an optional description. You can fill out these fields by implementing the following methods of BWQuincyManagerDelegate:

  • crashReportUserID should be a user ID or email, e.g. if your app requires to sign in into your server, you could specify the login here. The string should be no longer than 255 chars. You can also set autoSubmitDeviceUDID to YES, then crashReportUserID will be automatically set to the device's UDID.

  • crashReportContact should be the user's name or similar. The string should be no longer than 255 chars.

  • crashReportDescription can be as long as you want it to be and contain additional information about the crash. For example, you can return a custom log or the last XML or JSON response from your server here.

If you implement these delegate methods and keep them in your live app too, please consider the privacy implications. We recommend to adjust the return values by using the above preprocessor statements.

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 alternative for step 5 and 6, you can use our HockeyMac app to upload the complete archive in one step.

Checklist if Crashes Do Not Appear in HockeyApp

  1. Check if the BETA_APP_IDENTIFIER or RELEASE_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. Check if the code inside the #ifdef statements is actually reached. You can do this at run time by adding a NSLog statement or at compile time by adding a #warning statement, e.g.

    #if defined (CONFIGURATION_Beta) #warning QuincyKit is configured for this build [[BWQuincyManager sharedQuincyManager] setAppIdentifier:@"BETA_APP_IDENTIFIER"]; #endif

    You should then see the string "QuincyKit is configured for this build" as a warning in Xcode.

  4. Make sure that "Build & Archive" uses the correct build configuration: Choose Product > Edit Scheme… in Xcode, then select "Archive" in the sidebar and check the build configuration in the right panel.

  5. Unless you have set autoSubmitCrashReport to YES: If your app crashes and you start it again, is the alert shown which asks the user to send the crash report? If not, please crash your app again, then connect the debugger and set a break point in BWQuincyManager.m, method startManager to see why the alert is not shown.

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