Edit

Migrate from the HockeySDK to App Center SDK for iOS

  • Article

Important

Visual Studio App Center is scheduled for retirement on March 31, 2025. While you can continue to use Visual Studio App Center until it is fully retired, there are several recommended alternatives that you may consider migrating to.

Learn more about support timelines and alternatives.

Follow this documentation if you're looking to update your application to use App Center SDK instead of HockeySDK.

1. Update the libraries

1.1 Remove old HockeySDK

Manual

If you've added the SDK manually, follow these steps:

  1. Remove HockeySDK.embeddedframework reference from the XCode project. Click the Remove reference button, don't click Move to Trash button.

  2. Open your project settings and under Build Settings tab in the Header Search Paths / Framework Search Paths sections, remove the locations for header files related to HockeySDK.

  3. Open your project settings and under Build Phases tab in the Link Binary with Libraries section, remove the dependency entries related to HockeySDK.

  4. Delete HockeySDK.embeddedframework from the file system.

Podfile

If you've added the SDK using CocoaPods, remove the pod "HockeySDK" line from the Podfile, then run pod install.

Carthage

  1. Remove HockeySDK references from the Cartfile. Delete Cartfile.Resolved from the file system.

  2. Delete HockeySDK.framework and HockeySDK.framework.dSYM from the XCode project and click the Move to Trash button.

  3. Open the Build Phases tab and locate the Run Script section. Remove HockeyApp from the input.xcfilelist and output.xcfilelist.

1.2 Add the new App Center SDK

The App Center SDK supports integration via Cocoapods, Carthage, Swift Package Manager and by using the Frameworks in your Xcode project. Read detailed instructions how to how to integrate the App Center SDK in the App Center SDK documentation.

Note

The App Center SDK is designed with a modular approach so you can use any or all of the services. See the equivalences in the next table:

HockeyApp class App Center module
MetricsManager Analytics
CrashManager Crashes
UpdateManager Distribute

2. Update the SDK setup code

2.1 Convert the application identifier

The App Center SDK uses application identifiers in the globally unique identifier (GUID) format. Your HockeyApp App ID can be used by App Center but you need to convert it to a different format. To convert the identifier you must add four hyphens to get an 8-4-4-4-12 representation.

Before (HockeyApp): 00112233445566778899aabbccddeeff

After (App Center): 00112233-4455-6677-8899-aabbccddeeff

2.2 Replace SDK initialization in the application code

  1. Replace the following imports in your AppDelegate class.

    Before:

    @import HockeySDK;

    import HockeySDK

    After:

    @import AppCenter;
@import AppCenterAnalytics;
@import AppCenterCrashes;
@import AppCenterDistribute;

    import AppCenter
import AppCenterAnalytics
import AppCenterCrashes
import AppCenterDistribute

  2. Replace registration code

    Find the didFinishLaunchingWithOptions method and replace HockeyApp code occurrences.

    Before:

    [[BITHockeyManager sharedHockeyManager] configureWithIdentifier:@"APP_IDENTIFIER"];
[[BITHockeyManager sharedHockeyManager] startManager];
[[BITHockeyManager sharedHockeyManager].authenticator authenticateInstallation];

    BITHockeyManager.shared().configure(withIdentifier: "APP_IDENTIFIER")
BITHockeyManager.shared().start()
BITHockeyManager.shared().authenticator.authenticateInstallation()

    After:

    [MSACAppCenter start:@"{Your app secret}" withServices:@[[MSACAnalytics class], [MSACCrashes class], [MSACDistribute class]]];

    AppCenter.start(withAppSecret: "{Your App Secret}", services: [Analytics.self, Crashes.self, Distribute.self])

    Note

    App Center SDK doesn't have equivalents for [[BITHockeyManager sharedHockeyManager] configureWithBetaIdentifier:liveIdentifier:delegate].

  3. [Optional] Modify the project's Info.plist

    If you intend to use Distribute, follow the steps above:

    • Add a new key for URL types or CFBundleURLTypes in your Info.plist file (in case XCode displays your Info.plist as source code).
    • Change the key of the first child item to URL Schemes or CFBundleURLSchemes.
    • Enter appcenter-${APP_SECRET} as the URL scheme and replace ${APP_SECRET} with the App Secret of your app.

    For more information on this, refer to App Center Distribute documentation.

  4. Replace HockeyApp API calls throughout the application. The detailed API mapping tables are given below.

3. Services and feature comparison

Core

Feature HockeyApp App Center
Adjust log level [BITHockeyManager sharedHockeyManager].logLevel = BITLogLevelVerbose [MSACAppCenter setLogLevel:MSACLogLevelVerbose]
Identify installations [BITHockeyManager sharedHockeyManager].installString [MSACAppCenter installId]
Identify users [BITHockeyManager sharedHockeyManager].userID [MSACAppCenter setUserId:@"your-user-id"]

Analytics

The HockeySDK enables metrics collecting per default. App Center SDK registers Analytics service only if you pass Analytics class to the start method.

Feature HockeyApp App Center
Automatically track sessions Can't be disabled Documentation (can't be disabled)
Custom events with properties Yes [MSACAnalytics trackEvent:withProperties:]
Disable service at runtime [BITHockeyManager sharedHockeyManager].disableMetricsManager = YES [MSACAnalytics setEnabled:NO]

Crashes

The HockeySDK enables crash reporting per default. Crashes will be immediately sent to the server the next time the app is launched. App Center SDK registers Crashes service only if you pass Crashes class to the start method.

Feature HockeyApp App Center
Automatically send crashes [[BITHockeyManager sharedHockeyManager].crashManager setCrashManagerStatus: BITCrashManagerStatusAutoSend] Documentation (enabled by default)
Generate a test crash [[BITHockeyManager sharedHockeyManager].crashManager generateTestCrash] [MSACCrashes generateTestCrash]
Info about the previous crash [[BITHockeyManager sharedHockeyManager].crashManager lastSessionCrashDetails] [MSACCrashes lastSessionCrashReport]
Mach exception handling Disabled by default Documentation (enabled by default)
Attach additional meta data Yes Documentation (can be attached from delegate)
Customize user dialog setAlertViewHandler Documentation (not provided by default)
Disable service at runtime [[BITHockeyManager sharedHockeyManager] setDisableCrashManager: YES] [MSACCrashes setEnabled:NO]

Distribute

Note

Unlike in HockeyApp, App Center in-app updates feature will ONLY work with builds that are distributed using the App Center Distribute service. Distribute won't work when the debugger is attached. If the app is using a private distribution group, once the app is installed and opened for the first time after the App Center Distribute SDK has been added, a browser will open to authenticate the user and enable in-app updates. This browser will also open if you set the private in-app update track at runtime. This is a one-time step that won't occur for subsequent releases of your app. Refer to the App Center Distribute Documentation for more details.

The HockeySDK doesn't enable in-app updates by default. App Center SDK registers in-app updates service only if you pass Distribute class to the start method. This module is enabled by default, unlike in the HockeySDK.

Feature HockeyApp App Center
Restricted in-app updates [[BITHockeyManager sharedHockeyManager].authenticator authenticateInstallation] MSACDistribute.updateTrack
Disable service at runtime [[BITHockeyManager sharedHockeyManager] setDisableUpdateManager: YES] [MSACDistribute setEnabled:NO]
Customize the update dialog shouldDisplayUpdateAlertForUpdateManager Documentation