macOS 入门

项目
03/17/2024

重要

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

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

App Center SDK 使用模块化体系结构，因此可以使用任何或所有服务。

让我们开始在应用中设置 App Center macOS SDK，以使用 App Center Analytics 和 App Center 崩溃。

1.先决条件

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

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

注意

App Center SDK 将在 6 月 SDK 版本中 放弃对 Xcode 10 的支持 。

App Center SDK 分析和崩溃通过 XCFramework 或 SwiftPM 与 Mac Catalyst 兼容。

App Center SDK 与 Apple Silicon 兼容。

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

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

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

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

3. 添加 App Center SDK 模块

可以通过 Cocoapods、 Carthage、 Swift 包管理器或手动将二进制文件添加到项目中，将适用于 macOS 的 App Center SDK 添加到应用。

注意

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

3.1 通过 Cocoapods 集成

向添加以下依赖项， podfile 以将 App Center Analytics 和 App Center 崩溃包含在应用中。这会拉取以下框架： AppCenter、 AppCenterAnalytics 和 AppCenter 崩溃。相反，你可以指定要在应用中使用的服务。每个服务都有自己的子规格，它们都依赖于 AppCenter。它将自动拉入。
```
 # Use the following line to use App Center Analytics and Crashes.
 pod 'AppCenter'

 # Use the following lines if you want to specify which service you want to use.
 pod 'AppCenter/Analytics'
 pod 'AppCenter/Crashes'
```
运行 pod install 以安装新定义的 Pod 并打开项目的 .xcworkspace。

现在，你已将框架集成到应用程序中，接下来可以启动 SDK 并使用 App Center 服务。

3.2 通过 Carthage 集成

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

将以下依赖项添加到， 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

运行 carthage update --platform macOS。这会将依赖项提取到 Carthage/Checkouts 文件夹中，然后生成每个框架。
打开应用程序目标的“ 常规设置”选项卡。将 AppCenter.framework、 AppCenterAnalytics.framework 和 AppCenterCrashes.framework 文件从 Carthage/Build/macOS 文件夹拖放到 Xcode 的项目导航器中。启动 SDK 需要 AppCenter.framework 。如果未将其添加到项目中，其他模块将无法工作，并且应用将无法编译。
将显示一个对话框，确保已选中应用目标。然后单击“完成”。

注意

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

现在，你已将框架集成到应用程序中，接下来可以启动 SDK 并使用 App Center 服务。

3.3 通过 Swift 包管理器集成

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

现在，你已将框架集成到应用程序中，接下来可以启动 SDK 并使用 App Center 服务。

注意

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

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

下面是有关如何将编译的二进制文件集成到 Xcode 项目中的步骤，以便为 macOS 应用设置 App Center Analytics 和 App Center 崩溃。

注意

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

下载以 zip 文件的形式提供的 App Center SDK 框架。
解压缩该文件，你将看到一个名为 AppCenter-SDK-Apple 的文件夹，其中包含每个平台文件夹中每个 App Center 服务的不同框架。项目中需要名为 AppCenter 的框架，因为它包含在不同模块之间共享的代码。
[可选]为第三方库创建子目录。
- 第三方库通常位于子目录中 (它通常称为 “供应商) ”，因此，如果项目不使用库的子目录，请立即创建 Vendor 子目录。
- 在 Xcode 项目中创建一个名为 “供应商 ”的组，以模拟磁盘上的文件结构。
在 Finder 中打开解压缩的 AppCenter-SDK-Apple 文件夹，并将该文件夹复制到项目所需位置的文件夹中。该文件夹在 App Center SDK 支持的其他平台的子文件夹中包含框架，因此可能需要删除不需要的子文件夹。
在 Xcode 中将 SDK 框架添加到项目中：
- 确保项目导航器 (⌘+1) 可见。
- 现在，从 Finder 拖放 AppCenter.framework、 AppCenterAnalytics.framework 和 AppCenterCrashes.framework (供应商 文件夹内的 AppCenter.framework) 到 Xcode 的 Project Navigator。启动 SDK 需要 AppCenter.framework。如果缺少其他模块，则其他模块将无法工作，并且应用将无法编译。
- 将显示一个对话框，确保已选中应用目标。然后单击“完成”。

注意

SDK 二进制文件未按照 macOS 框架约定打包。原因是适用于 Mac 的 App Center SDK 不是常规框架，而是静态框架。必须将其链接为静态框架：确保未嵌入二进制文件，并且不要将它们包含在“复制捆绑包资源”生成阶段。

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

4.启动 SDK

若要使用 App Center，必须选择加入要使用的模块 () 。默认情况下，不会启动任何模块，必须在启动 SDK 时调用每个模块。如果要针对某个扩展进行开发，请参阅扩展入门页。

4.1 添加 import 语句

打开项目的 AppDelegate 文件并添加以下 import 语句：

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

import AppCenter
import AppCenterAnalytics
import AppCenterCrashes

4.2 添加 `start:withServices:` 方法

在应用的 didFinishLaunchingWithOptions 委托方法中插入以下行：

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

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

如果有 Catalyst 应用程序，则可以同时为 iOS 和 macOS 传递应用机密：

[MSACAppCenter start:@"ios={Your iOS App Secret};macos={Your macOS App Secret}" withServices:@[[MSACAnalytics class], [MSACCrashes class]]];

AppCenter.start(withAppSecret:"ios={Your iOS App Secret};macos={Your macOS App Secret}", services: [Analytics.self, Crashes.self])

警告

不建议在源代码中嵌入应用机密。

如果需要单独启动 App Center 服务，应：

使用应用机密配置或启动它。
如果代码可以多次调用，检查是否已配置 App Center。
在没有应用机密的情况下启动所需的服务 () 。

[MSACAppCenter configureWithAppSecret:@"{Your App Secret}"];
if ([MSACAppCenter isConfigured]) {
   [MSACAppCenter startService:[MSACAnalytics class]];
   [MSACAppCenter startService:[MSACCrashes class]];
}

AppCenter.configure(withAppSecret: "{Your App Secret}")
if AppCenter.isConfigured {
    AppCenter.startService(Analytics.self)
    AppCenter.startService(Crashes.self)
}

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

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

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

上面的示例演示如何使用 start:withServices (start(withAppSecret:services:) for Swift) 方法，并包括 App Center Analytics 和 App Center 崩溃。

如果不想使用这两个服务之一，请从上面的方法调用中删除相应的参数。

除非在 start 方法中将每个模块显式指定为参数，否则不能使用该 App Center 服务。此外， start:withServices Swift) API (start(withAppSecret:services:) 只能在应用的生命周期中使用一次 - 所有其他调用都将向控制台记录警告，并且只有第一次调用中包含的模块可用。

例如 - 如果要加入 App Center Analytics，则应修改 start:withServices Swift) API 调用 (start(withAppSecret:services:) ，如下所示：

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

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

4.4 为沙盒应用添加 Internet 功能

如果应用正在使用应用沙盒，则必须设置允许传出 (客户端) 连接的功能，以允许应用访问 Internet。 Xcode 9 默认启用应用沙盒，但需要显式设置传出连接的功能。

在项目导航器中选择项目，选择“ 功能 ”选项卡，如果应用正在使用沙盒，请启用传出连接。

很好，你已准备好在 SDK 自动收集的门户上可视化分析和崩溃数据。

查看 App Center Analytics 文档和 App Center 崩溃文档，了解如何自定义和使用每个服务的高级功能。

macOS 入门

1.先决条件

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

3. 添加 App Center SDK 模块

3.1 通过 Cocoapods 集成

3.2 通过 Carthage 集成

3.3 通过 Swift 包管理器集成

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

4.启动 SDK

4.1 添加 import 语句

4.2 添加 start:withServices: 方法

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

4.4 为沙盒应用添加 Internet 功能

其他资源

4.2 添加 `start:withServices:` 方法