Beta Distribution on HockeyKit 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 HockeyKit client into your app. The client allows testers to update your app to another beta version right from within the application. It will notify the tester about available updates. The client has various options that can be used to adjust it's behavior and contains an App Store like screen to present the update information and release notes.

In addition, the client collects statistics for each version. So you can see which device, iOS version, language, app version is tested from whom and for how long.

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

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

  2. We also 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.

Download & Extract

  1. Download the latest HockeyKit client files.

  2. Unzip the file. A new folder HockeyKit 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.

    FinderHockeyKit.png

Integrate into Xcode

  1. Drag & drop the HockeyKit 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".

    XcodeHockeyKit.png

  2. Optional: If your project already includes the SBJson library or JSONKit, remove the group "JSON" from "HockeyKit" and choose "Remove Reference Only" in the following dialog.

    XcodeRemoveJSON.png

Define Preprocessor Macros

The HockeyKit client should check for updates in AdHoc builds, but not in builds for the App Store (and usually not during development). We therefore recommend to define a preprocessor macro for all configurations and execute the client only in the one for AdHoc builds.

If your app should not be published in the App Store and you want to use HockeyKit in all configurations, you can skip the following steps and move to the next section.

  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
* Foundation.framework
* QuartzCore.framework
* SystemConfiguration.framework
* UIKit.framework

![XcodeFrameworks.png](/assets/3544d971250acb3675cdbb9f22c2f8ee16c4dc86/XcodeFrameworks_normal.png)
  1. If one of the frameworks is missing, then click the + button, search the framework and confirm with the "Add" button.

Modify Source Code

  1. Open your AppDelegate.h file.

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

    #import "BWHockeyManager.h"
    
  3. Let the AppDelegate implement the protocol BWHockeyManagerDelegate:

    @interface AppDelegate : UIResponder <BWHockeyManagerDelegate, UIApplicationDelegate>
    
  4. Open your AppDelegate.m file.

  5. Search for the method application:didFinishLaunchingWithOptions:

  6. Add the following lines:

    #if defined (CONFIGURATION_Beta) [[BWHockeyManager sharedHockeyManager] setAppIdentifier:@"APP_IDENTIFIER"]; [[BWHockeyManager sharedHockeyManager] setDelegate:self]; #endif

  7. As our configuration for AdHoc builds is called "Beta", the resulting preprocessor macro is "CONFIGURATION_Beta". If your configuration has a different name, you have to change the macro's name accordingly.

  8. Replace APP_IDENTIFIER with your own app identifier. If you don't know what the app identifier is or how to find it, please read this how-to.

  9. Add the following method:

   - (NSString *)customDeviceIdentifier {
     #if defined (CONFIGURATION_Beta)
       if ([[UIDevice currentDevice] respondsToSelector:@selector(uniqueIdentifier)])
         return [[UIDevice currentDevice] performSelector:@selector(uniqueIdentifier)];
     #endif

     return nil;
   }

This ensures that the UDID is only used for beta builds, but excluded from store builds. **Note: You need to implement this method if you want to get statistics for your beta builds!**
  1. If you have added the lines in step 6 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.

Further Options

If you don't want to include a button or menu to let the user open the update screen at any time, we recommend to add the following line inside the above #ifdef statement. This will show the update reminder every time the app gets active, so the user will still be able to update easily when the first appearance of the notification came in at an inappropriate time.

[[BWHockeyManager sharedHockeyManager] setAlwaysShowUpdateReminder:YES];

The full list of properties can be found here.