Edit

Get Started with macOS extensions

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

Extensions only support crash reporting.

To learn how to add App Center SDK to your container app, refer to the documentation for App Center macOS Getting Started.

Let's get started with setting up App Center macOS SDK in your app extension to use App Center Crashes.

1. Prerequisites

The following requirements must be met to use App Center SDK:

  • Your macOS project is set up in Xcode 13 or later on macOS version 10.14.4 or later.
  • You're targeting devices running on macOS 10.13 or later.
  • You're not using any other library that provides Crash Reporting functionality.

2. Create your app in the App Center Portal to obtain the App Secret

If you've already created your app in the App Center portal, you can skip this step.

  1. Head over to appcenter.ms.
  2. Sign up or log in and hit the blue button on the top right corner of the portal that says Add new and select Add new app from the dropdown menu.
  3. Enter a name and an optional description for your app.
  4. Select macOS as the OS and Objective-C/Swift as a platform.
  5. Hit the button at the bottom right that says Add new app.

Once you've created an app, you can obtain its App Secret on the Settings page on the App Center Portal. At the top right hand corner of the Settings page, click on the triple vertical dots and select Copy app secret to get your App Secret.

Note

Using an existing App Secret from another macOS project has side effects. App Center doesn't support filtering by project on the same App Center application. For instance listing crashes for a particular version will list all the crashes from both projects for this version without distinction. It can be confusing.

Note

In the 4.0.0 version of App Center breaking changes were introduced. Follow the Migrate to App Center SDK 4.0.0 and higher section to migrate App Center from previous versions.

3. Add the App Center SDK modules

The App Center SDK can be integrated into your app via Cocoapods, Carthage or by manually adding the binaries to your project.

3.1 Integration via Cocoapods

  1. Add the following dependencies to your podfile to include App Center Crashes into your app. This pulls in the following frameworks: AppCenter and AppCenterCrashes.

     pod 'AppCenter/Crashes'

  2. Run pod install to install your newly defined pod and open the project's .xcworkspace.

Note

If you see an error like [!] Unable to find a specification for `AppCenter` while running pod install, run pod repo update to get the latest pods from the Cocoapods repository and then run pod install.

Now that you've integrated the frameworks in your application, it's time to start the SDK and make use of the App Center services.

3.2 Integration via Carthage

Below are the steps on how to integrate the App Center SDK in your Xcode project using Carthage version 0.30 or higher, a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.

  1. Add the following dependencies to your Cartfile to include App Center into your app. This pulls in all the frameworks. Then you can link only those frameworks to use in your app.

    # Use the following line to get the latest version of App Center
github "microsoft/appcenter-sdk-apple"

    # Use the following line to get the specific version of App Center
github "microsoft/appcenter-sdk-apple" ~> X.X.X

  2. Run carthage update. This fetches dependencies into a Carthage/Checkouts folder, and then builds each framework.

  3. Open your application target's General settings tab. Drag and drop AppCenter.framework and AppCenterCrashes.framework files from the Carthage/Build/ folder into Xcode's Project Navigator. The AppCenter.framework is required to start the SDK. If it isn't added to the project, the other modules won't work and your app won't compile.

  4. A dialog will appear, make sure your app target is checked. Then click Finish.

    Note

    If you use carthage copy-frameworks in your Build Phase you shouldn't add the App Center SDKs there, as they're shipped as static frameworks.

Now that you've integrated the frameworks in your application, it's time to start the SDK and make use of the App Center services.

3.3 Integration via Swift Package Manager

  1. From the Xcode menu click File > Swift Packages > Add Package Dependency.
  2. In the dialog that appears, enter the repository URL: https://github.com/microsoft/appcenter-sdk-apple.git.
  3. In Version, select Up to Next Major and take the default option.
  4. Choose the modules you need in the Package Product column.

Now that you've integrated the frameworks in your application, it's time to start the SDK and make use of the App Center services.

Note

If you're integrating App Center via SwiftPM and want to use it in your app's extension target as well, make sure that you provide DISABLE_DIAMOND_PROBLEM_DIAGNOSTIC=YES in your configuration. This is necessary to avoid SwiftPM limitations in linking a module to multiple targets.

3.4 Integration by copying the binaries into your project

Below are the steps on how to integrate the compiled binaries in your Xcode project to set up App Center Crashes for your app extension.

Note

App Center SDK supports the use of XCframework. If you want to integrate XCframeworks into your project, download the AppCenter-SDK-Apple-XCFramework.zip from the releases page and unzip it. Resulting folder contents aren't platform-specific, instead it contains XCframeworks for each module. They can be integrated the same way as usual frameworks, as described below.

  1. Download the App Center SDK frameworks provided as a zip file.

  2. Unzip the file and you'll see a folder called AppCenter-SDK-Apple that contains different frameworks for each App Center service on each platform folder. The framework called AppCenter is required in the project as it contains code that's shared between the different modules.

  3. [Optional] Create a subdirectory for 3rd-party libraries.

    • As a best practice, 3rd-party libraries are usually in a subdirectory, often called Vendor. If the project isn't organized with a subdirectory for libraries, create a Vendor subdirectory now.
    • Create a group called Vendor inside your Xcode project to mimic your file structure on disk.

  4. Open the unzipped AppCenter-SDK-Apple folder in Finder and copy the folder into your project's folder at the location where you want it. The folder contains frameworks in subfolders for other platforms that App Center SDK supports, so you might need to delete subfolders you don't need.

  5. Add the SDK frameworks to the project in Xcode:

    • Make sure the Project Navigator is visible (⌘+1).
    • Now drag and drop AppCenter.framework and AppCenterCrashes.framework from the Finder (in the location from the previous step) into Xcode's Project Navigator. The AppCenter.framework is required to start the SDK. If it isn't added to the project, the other modules won't work and your app extension won't compile.
    • A dialog will appear, make sure your app extension target is checked. Then click Finish.

Now that you've integrated the frameworks in your app extension, it's time to start the SDK and make use of the App Center services.

4. Start the SDK

To use App Center, you must opt in to the module(s) to use. By default, no modules are started, and you must explicitly call each of them when starting the SDK.

4.1 Add the import statements

Insert the following lines in the file containing the app extension's entry point. For example, inside the main ViewController file of a Today extension.

@import AppCenter;
@import AppCenterCrashes;

import AppCenter
import AppCenterCrashes

4.2 Add the start:withServices: method

Insert the following line in the app extension's entry point. For example, inside the viewDidLoad method of the main ViewController file of a Today extension.

[MSACAppCenter start:@"{Your App Secret}" withServices:@[[MSACCrashes class]]];

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

Currently, only crash reporting is supported for application extensions.

4.3 Replace the placeholder with your App Secret

Make sure to replace {Your App Secret} text with the actual value for your application extension. The App Secret can be found on the Getting Started page or Settings page on the App Center portal.

The Getting Started page contains the above code sample with your App Secret in it, you can copy-paste the whole sample.

Great, you're all set to visualize Crashes data on the portal that the SDK collects automatically.

Look at the documentation for App Center Crashes to learn how to customize your app extension and use more advanced functionalities.