iOS 扩展入门

重要

Visual Studio App Center 计划于 2025 年 3 月 31 日停用。 虽然可以继续使用 Visual Studio App Center，直到它完全停用，但你可以考虑迁移到几个建议的替代方法。

详细了解支持时间线和替代方法。

• Android
• iOS
• iOS 扩展
• React Native
• MAUI/Xamarin
• UWP
• WPF/WinForms
• Unity
• macOS
• macOS 扩展
• tvOS
• Cordova

应用程序扩展仅支持故障报告。

若要了解如何将 App Center SDK 添加到容器应用，请参阅 App Center iOS 入门文档。

让我们开始在应用扩展中设置 App Center iOS SDK，以使用 App Center 崩溃。

1.先决条件

若要使用 App Center SDK，必须满足以下要求：

• iOS 项目是在 macOS 版本 10.14.4 或更高版本上的 Xcode 13 或更高版本中设置的。
• 你的目标是在 ios 11.0 或更高版本上运行的设备。
• 未使用提供故障报告功能的任何其他库。

2.在 App Center 门户中创建应用以获取应用机密

如果已在 App Center 门户中创建了应用，则可以跳过此步骤。

1. 前往 appcenter.ms。
2. 注册或登录，点击门户右上角显示 “新增” 的蓝色按钮，然后从下拉菜单中选择“ 添加新应用 ”。
3. 输入应用的名称和可选说明。
4. 选择 “iOS ”作为 OS，选择 “Objective-C/Swift ”作为平台。
5. 点击右下角显示 “添加新应用”的按钮。

创建应用后，可以在 App Center 门户的“设置”页上获取其应用机密。 在 “设置” 页面的右上角，单击 三个垂直点 ，然后选择 Copy app secret 获取应用机密。

注意

使用另一个 iOS 项目中的现有应用机密会产生副作用。 App Center 不支持在同一 App Center 应用程序上按项目进行筛选。 例如，列出特定版本的崩溃将列出此版本这两个项目的所有崩溃，没有区别。 可能会令人困惑。

注意

在 4.0.0 App Center 版本中引入了中断性变更。 按照 迁移到 App Center SDK 4.0.0 及更高 版本部分从早期版本迁移 App Center。

3.添加 App Center SDK 模块

可以通过 Cocoapods、 Carthage 或手动将二进制文件添加到项目，将 App Center SDK 集成到应用中。

3.1 通过 Cocoapods 集成

1. 将以下依赖项添加到 ， podfile 以将 App Center 崩溃包含在应用中。 这会拉取以下框架： AppCenter 和 AppCenterCrashes。

    pod 'AppCenter/Crashes'
   

2. 运行 pod install 以安装新定义的 Pod 并打开项目的 .xcworkspace。

注意

如果在运行 pod install时看到类似于 [!] Unable to find a specification for `AppCenter` 的错误，请运行 pod repo update 以从 Cocoapods 存储库获取最新的 Pod，然后运行 pod install。

在应用程序中集成框架后，可以启动 SDK 并使用 App Center 服务。

3.2 通过 Carthage 集成

下面是有关如何使用 Carthage 版本 0.30 或更高版本将 App Center SDK 集成到 Xcode 项目中的步骤，Carthage 是一个分散式依赖项管理器，用于生成依赖项并为您提供二进制框架。

1. 将以下依赖项添加到 ， Cartfile 以将 App Center 包含在应用中。 这会拉入所有框架。 然后，可以仅链接这些框架以在应用中使用。

   # 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. 运行 carthage update。 这会将依赖项提取到 Carthage/Checkouts 文件夹中，然后生成每个框架。

3. 打开应用程序目标的“ 常规 设置”选项卡。将 AppCenter.framework 和 AppCenterCrashes.framework 文件从 Carthage/Build/ 文件夹拖放到 Xcode 的 Project Navigator 中。 启动 SDK 需要 AppCenter.framework 。 如果未将其添加到项目中，则其他模块将不起作用，并且你的应用将无法编译。

4. 将显示一个对话框，确保已选中你的应用目标。 然后单击“完成”。

   注意

   如果在生成阶段使用 carthage copy-frameworks ，则不应添加 App Center SDK，因为它们作为静态框架提供。

在应用程序中集成框架后，可以启动 SDK 并使用 App Center 服务。

3.3 通过 Swift 包管理器集成

1. 在“Xcode”菜单中，单击“ 文件 > ”“Swift 包 > ”“添加包依赖项”。
2. 在出现的对话框中，输入存储库 URL： https://github.com/microsoft/appcenter-sdk-apple.git。
3. 在 “版本”中，选择“ 下一个主要 版本”并采用默认选项。
4. 在“ 包产品 ”列中选择所需的模块。

在应用程序中集成框架后，可以启动 SDK 并使用 App Center 服务。

注意

如果要通过 SwiftPM 集成 App Center，并且还想要在应用的扩展目标中使用它，请确保在配置中提供 DISABLE_DIAMOND_PROBLEM_DIAGNOSTIC=YES 。 这是在将模块链接到多个目标时避免 SwiftPM 限制所必需的。

3.4 通过将二进制文件复制到项目中进行集成

下面是有关如何在 Xcode 项目中集成已编译的二进制文件以设置应用扩展的 App Center 崩溃的步骤。

注意

App Center SDK 支持使用 XCframework。 如果要将 XCframeworks 集成到项目中，请从发布页下载 AppCenter-SDK-Apple-XCFramework.zip 并将其解压缩。 生成的文件夹内容不是特定于平台的，而是包含每个模块的 XCframeworks。 可以像通常的框架一样集成它们，如下所述。

1. 下载以 zip 文件的形式提供的 App Center SDK 框架。

2. 解压缩该文件，你将看到一个名为 AppCenter-SDK-Apple 的文件夹，其中包含每个平台文件夹中每个 App Center 服务的不同框架。 项目中需要调用 AppCenter 的框架，因为它包含在不同模块之间共享的代码。

3. [可选]为第三方库创建子目录。

   • 最佳做法是，第三方库通常位于子目录中，通常称为 Vendor。 如果项目未使用库的子目录进行组织，请立即创建 Vendor 子目录。
   • 在 Xcode 项目中创建名为 Vendor 的组，以模拟磁盘上的文件结构。

4. 在 Finder 中打开解压缩的 AppCenter-SDK-Apple 文件夹，并将该文件夹复制到项目所在位置的文件夹中。 文件夹包含 App Center SDK 支持的其他平台的子文件夹中的框架，因此可能需要删除不需要的子文件夹。

5. 在 Xcode 中将 SDK 框架添加到项目中：

   • 确保项目导航器 (⌘+1) 可见。
   • 现在，将 AppCenter.framework 和 AppCenterCrashes.framework 从 Finder (拖放到上一步) 到 Xcode 的项目导航器中的位置。 启动 SDK 需要 AppCenter.framework 。 如果未将其添加到项目中，则其他模块将不起作用，并且应用扩展不会编译。
   • 将显示一个对话框，确保已选中应用扩展目标。 然后单击“完成”。

现在，你已在应用扩展中集成了框架，接下来可以启动 SDK 并使用 App Center 服务。

4. 启动 SDK

若要使用 App Center，必须选择加入要使用的模块 () 。 默认情况下，不启动任何模块，在启动 SDK 时必须显式调用每个模块。

4.1 添加 import 语句

在包含应用扩展入口点的文件中插入以下行。 例如，在“今日”扩展名的 main ViewController 文件中。

@import AppCenter;
@import AppCenterCrashes;

import AppCenter
import AppCenterCrashes

4.2 添加 start:withServices: 方法

在应用扩展的入口点中插入以下行。 例如，在 viewDidLoad main 的 ViewController 文件的 方法中，扩展名为 Today。

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

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

目前，应用程序扩展仅支持崩溃报告。

4.3 将占位符替换为应用机密

请确保将文本替换为 {Your App Secret} 应用程序扩展的实际值。 可以在 App Center 门户的“入门”页或“设置”页上找到应用机密。

入门页包含上述代码示例，其中包含应用机密，你可以复制粘贴整个示例。

很好，你都可以在 SDK 自动收集的门户上可视化崩溃数据。

查看 App Center 崩溃 文档，了解如何自定义应用扩展并使用更高级的功能。