Edit

Share via

Migrate from the HockeySDK to App Center SDK for macOS

  • 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.framework 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.framework from the file system.

Podfile

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

Carthage

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

  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.

1.2 Add the new App Center SDK

The App Center SDK supports to be integrated via Cocoapods, Carthage, Swift Package Manager and 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

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 AppCenter
import AppCenterAnalytics
import AppCenterCrashes

  2. Replace registration code

    Find the didFinishLaunchingWithOptions method and replace HockeyApp code occurrences.

    Before:

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

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

    After:

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

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

  3. 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]

Analytics

The HockeySDK collects metrics per default. The App Center SDK doesn't collect any (analytics) metrics per default. To collect metrics using the App Center SDK, pass MSACAnalytics to the start: method.

Feature HockeyApp App Center
Automatically track sessions Enabled by default Documentation (enabled by default)
Custom events with properties Yes [MSACAnalytics trackEvent:withProperties:]
Disable service at runtime [BITHockeyManager sharedHockeyManager].disableMetricsManager = YES [MSACAnalytics setEnabled:NO]

Crashes

The HockeySDK reports crashes per default. Crashes will be immediately sent to the server the next time the app is launched. The App Center SDK doesn't report any crashes per default. To collect crashes using the App Center SDK, pass MSACCrashes to the start: method.

Feature HockeyApp App Center
Automatically send crashes [[BITHockeyManager sharedHockeyManager].crashManager setAutoSubmitCrashReport: YES] 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 [[BITHockeyManager sharedHockeyManager].disableMachExceptionHandler = YES] Documentation (enabled by default)
Attach additional meta data Yes Documentation (can be attached from delegate)
Customize user dialog setCrashReportUIHandler Documentation (not provided by default)
Disable service at runtime [[BITHockeyManager sharedHockeyManager] setDisableCrashManager: YES] [MSACCrashes setEnabled:NO]