Trace SDK

在生产之前捕捉错误 —— 获取详细的崩溃报告并监控您的应用在整个安装基础上的性能。当发现问题时，我们将向您显示用户会话中发生的情况，以便快速定位、重现和修复问题。使用 Trace 来

• 发现问题：在用户报告之前知道问题。
• 评估影响：重点关注对用户最有影响力的问题的解决。
• 追踪原因：减少重现问题所花费的时间。

• 什么是 Trace？

注意：以下链接需要用户登录并拥有 Trace 插件

* Trace * Trace 配置设置

要求

• iOS 10.0+
• Xcode 11.0+
• Xcode 13 测试版（使用 [https://github.com/bitrise-io/trace-cocoa-sdk/pull/84 分支）
• Swift 5.2+

安装

Trace SDK 不包含任何外部依赖项，但依赖于 iOS 上的一些系统框架，例如

• SystemConfiguration.framework
• libc++.tbd
• libz.tbd

这些框架都可以在 Xcode 的框架列表中找到。当前支持以下集成选项

Bitrise 工作流

使用 Bitrise 工作流步骤：添加 Trace SDK

使用 添加跟踪 SDK 步骤自动将 SDK 添加到您的项目中。所有下载、链接 SDK 以及支持系统框架和库的工作都由您完成。此步骤 必须 在 Xcode 存档 & 导出步骤 之前执行，因为它需要在之前进行链接。

直接从源代码安装

如果步骤项目位于 repo 文件夹中，则在您的 bitrise.yml 文件内添加以下步骤

- path::./step/:
    title: Add Trace SDK to Xcode project
    inputs:
    - lib_version: "latest"

如果您使用 GIT，请使用以下命令

- git::https://github.com/bitrise-steplib/bitrise-step-add-trace-sdk.git@master:
    title: Add Trace SDK to the Xcode project
    inputs:
    - project_path: "$BITRISE_PROJECT_PATH"
    - scheme: "$BITRISE_SCHEME"
    - lib_version: latest

注意：参数 latest 总是使用 SDK 的最新稳定版本。

CocoaPods

可选：设置 pod

$ pod init

将 Trace SDK 添加到 Podfile

# Podfile

target 'YOUR_TARGET_NAME' do
    pod 'BitriseTrace'
end

替换 YOUR_TARGET_NAME，然后在 Podfile 目录中输入以下内容

$ pod install

可选：如果您的项目在 other linker flags 中没有使用 -ObjC，请向 SDK 添加 -force_load。这用于确保 SDK 在应用程序启动时启动。

• 在项目导航器（蓝色项目图标）中选择您的应用程序项目，以导航到目标配置窗口，并在侧边栏的“Targets”标题下选择应用程序目标。
• 在窗口顶部的工具栏中，打开“构建设置”面板。
• 在搜索框中查找 Other Linker Flags 或 OTHER_LDFLAGS 并输入

# When not using `use_frameworks!` i.e Static library approach 
-force_load $(TARGET_BUILD_DIR)/BitriseTrace/libBitriseTrace.a

# When using `use_frameworks!` i.e Framework approach
-force_load $(TARGET_BUILD_DIR)/BitriseTrace/Trace.framework/Trace

现在 SDK 已设置到您的工作区中，请添加在 设置页面 中找到的收集令牌（bitrise_configuration.plist）。确保此文件已添加到您的应用程序目标中。

Carthage

注意：Carthage 目前不支持直接使用，需要执行以下几步才能运行。请遵循 集成步骤。等待 []xcframework 支持的完成

将以下内容添加到您的 Cartfile

github "bitrise-io/trace-cocoa-sdk"

$ carthage update

一旦您已在您的 Xcode 项目中包含了这个库

• 在项目导航器（蓝色项目图标）中选择您的应用程序项目，以导航到目标配置窗口，并在侧边栏的“Targets”标题下选择应用程序目标。
• 在窗口顶部的工具栏中，打开“构建设置”面板。
• 搜索 Other Linker Flags 或 OTHER_LDFLAGS 并输入 -force_load '$(BUILT_PRODUCTS_DIR)/libTrace.a'
• 这就是全部！

Carthage 作为静态库

Carthage 默认将 Trace 构建为动态库。

如果您希望使用 Carthage 构建 Trace 为静态库，您可以使用以下脚本在构建前手动修改框架类型

carthage update `Trace` --platform iOS --no-build
sed -i -e 's/MACH_O_TYPE = mh_dylib/MACH_O_TYPE = staticlib/g' Carthage/Checkouts/Trace/Trace.xcodeproj/project.pbxproj
trace build Trace --platform iOS

Swift Package Manager (SPM) (iOS 和 Mac Catalyst 兼容)

Swift 包管理器是一个用于自动分布 Swift 代码的工具，并集成到 Swift 编译器中。

使用以下方法之一将库添加到您的项目中

使用 Swift CLI 和 Package.swift

dependencies: [
    .package(url: "https://github.com/bitrise-io/trace-cocoa-sdk.git", .upToNextMajor(from: "1.7.39"))
]

将 Trace SDK 作为依赖项添加到您的 Package.swift 文件中。请查看 SDK 的 发布部分 以查找 SDK 的最新稳定版本。

使用 Xcode Swift 包管理器集成

要将包依赖项添加到您的 Xcode 项目/工作区，请选择 文件 > Swift 包 > 添加包依赖项 并输入仓库 URL https://github.com/bitrise-io/trace-cocoa-sdk.git。

此外，您还可以转至目标的一般选项卡，在“框架、库和嵌入内容”部分，单击 + 按钮，选择添加其他，然后选择添加包依赖关系。

可选 仅当项目无法构建时需要 将“其他链接器标志”添加到应用程序目标

• 在项目导航器（蓝色项目图标）中选择您的应用程序项目，以导航到目标配置窗口，并在侧边栏的“Targets”标题下选择应用程序目标。
• 在窗口顶部的工具栏中，打开“构建设置”面板。
• 搜索 Other Linker Flags 或 OTHER_LDFLAGS 并输入 -ObjC -l z -l c++

注意：这些标志确保您的项目包含所需系统框架，以帮助构建项目。

调用 Trace 初始化器

在您的项目中添加 import Trace 并调用 let trace = Trace.shared 以启动 SDK。

• 这就是全部！

手册

如果你不希望使用上述任何依赖管理器，你可以手动将Trace集成到你的项目中。

构建时嵌入静态库

• 从Github 发布页面下载libTrace.a静态库 assert。请选择名为libTrace.a的资产下的第一个文件。
• 将库拖至 Xcode 项目的根目录，即与您的xcproject/xcworkspace项目相同的目录。

• 接下来，在 Xcode 中，在项目导航器（蓝色项目图标）中选择您的应用程序项目，转到目标配置窗口，然后在侧边栏中“目标”标题下选择应用程序目标。
• 现在，在该窗口顶部的选项卡栏中，打开“构建设置”面板。
• 搜索其他链接器标志或OTHER_LDFLAGS，并输入-force_load libTrace.a

注意：代码片段假设库与您的 xcproject/xcworkspace 项目在相同目录。如果您使用不同的位置，请添加新路径。

• 在“框架、库和嵌入内容”部分下单击 + 按钮。
• 添加 libz.tbd 和 libc++.tbd。
• 这就是全部！

嵌入 Xcode 项目

• 打开终端，在存储 Xcode 项目的顶级项目目录中执行 cd。
• 通过运行以下命令将 Trace 添加为 git 子模块

$ git submodule add https://github.com/bitrise-io/trace-cocoa-sdk.git

• 打开新的 trace-cocoa-sdk 文件夹，并将 Trace.xcodeproj（蓝色项目文件，.xcodeproj）拖到应用程序的 Xcode 项目的项目导航器中。应该会出现在应用程序蓝色项目图标的下方。

• 接下来，在项目导航器（蓝色项目图标）中选择您的应用程序项目，转到目标配置窗口，然后在侧边栏的“目标”标题下选择应用程序目标。
• 在该窗口顶部的选项卡栏中，打开“通用”面板。
• 在“框架、库和嵌入内容”部分下单击 + 按钮。
• 从搜索列表中添加libTrace.a库。
• 同样添加 libz.tbd 和 libc++.tbd。
• 现在，在该窗口顶部的选项卡栏中，打开“构建设置”面板。
• 搜索 Other Linker Flags 或 OTHER_LDFLAGS 并输入 -force_load '$(BUILT_PRODUCTS_DIR)/libTrace.a'

注意：不要担心列表上的其他属性。

• 这就是全部！

上传 dSYM 文件

Bitrise 工作流程步骤

此步骤将自动上传由 Xcode 归档创建的所有 dSYM 文件。它使用默认的 Xcode 路径查找所有 dSYM 文件，并自动上传所有文件。

注意：在启用位码功能的情况下创建构建并提交到 iTunes Connect 的应用需要手动下载所有 dSYM 文件，并使用在 GitHub 上的上传 dSYM 脚本进行上传。处理可能需要一个小时，请参考下述说明。

其他所有依赖项管理器

在 Xcode 项目/工作空间中完成 Trace SDK 安装步骤后，选择您的 应用程序目标 并转到 构建阶段 选项卡。

点击加号按钮，添加 新的运行脚本阶段。将其命名为 Bitrise Trace SDK - 上传 dSYM 文件

在脚本部分复制并粘贴以下代码：

#!/bin/sh
set +o posix

echo "Bitrise Trace SDK - starting Upload dSYM's"

# See script header for more information - https://github.com/bitrise-io/trace-cocoa-sdk/blob/main/UploadDSYM/main.swift#L4

# Run script
/usr/bin/xcrun --sdk macosx swift <(curl -Ls --retry 3 --connect-timeout 20 -H "Cache-Control: max-age=604800" https://raw.githubusercontent.com/bitrise-io/trace-cocoa-sdk/main/UploadDSYM/main.swift)

# Script logs can be viewed in Xcode report navigator or Bitrise app build logs

echo "Bitrise Trace SDK - finished Upload dSYM's"

iTunes Connect（支持位码的应用）

您首先需要从 iTunes Connect 的“活动”->“构建”->“下载 dSYM”中下载压缩的 dSYM 文件。

打开终端应用并运行以下 shell 命令：

/usr/bin/xcrun --sdk macosx swift <(curl -Ls --retry 3 --connect-timeout 20 -H "Cache-Control: max-age=604800" https://raw.githubusercontent.com/bitrise-io/trace-cocoa-sdk/main/UploadDSYM/main.swift) APM_APP_VERSION version_here APM_BUILD_VERSION build_version_here APM_DSYM_PATH path_to_folder_or_zip_file

本地脚本

/usr/bin/xcrun --sdk macosx swift main.swift APM_APP_VERSION version_here APM_BUILD_VERSION build_version_here APM_DSYM_PATH path_to_folder_or_zip_file

API 需要以下参数：

APM_APP_VERSION：在 iTunes Connect 站点或 Info.plist 文件中找到的应用版本号。例如，1.0.0 APM_BUILD_VERSION：在 iTunes Connect 站点或 Info.plist 文件中找到的应用版本号。例如，123 APM_DSYM_PATH：DSYM 文件夹或 zip 文件的路径。

注意：该脚本假定当前 shell 工作目录具有 bitrise_configuration.plist 文件。否则请使用 APM_COLLECTOR_TOKEN token_here

APM_COLLECTOR_TOKEN：在 bitrise_configuration.plist 中的 Trace 令牌或在 Trace->设置中找到。

到此为止！在运行构建时，如果转到构建日志部分，您将看到完成时的结果。查找 Bitrise Trace SDK - 上传 dSYM 文件。

存储

SDK的二进制文件托管在Firebase上，可以在此处下载最新版本[下载]，或者通过在URL中添加版本信息来下载特定版本，例如 https://monitoring-sdk.firebaseapp.com/{MAJOR.MINOR.PITCH}/libTrace.a

默认情况下，导航到SDK网站的根目录会始终重定向到最新版本。

常见问题

C++系统库未链接

• 在“框架、库和嵌入内容”部分下单击 + 按钮。
• 添加 libz.tbd 和 libc++.tbd。
• 这就是全部！

无法找到Trace库

此错误是由Xcode无法找到Trace库引起的。默认情况下，我们的安装指南使用最简单的方法。要解决此错误，请转到您的应用程序目标中的Other Linker Flags或OTHER_LDFLAGS，并输入-force_load CORRECT_PATH_TO_libTrace.a'

找不到收集器令牌

请确保在您的项目中包含了bitrise_configuration.plist，并将目标成员设置为正确的选项。

未找到收集器令牌

[Bitrise:Trace/internalError] Bitrise配置文件从Bundle.main中缺失 [Bitrise:Trace/internalError] 应用程序无法读取配置文件，所有数据将在解决前进行缓存

将设置页面中找到的收集器令牌（bitrise_configuration.plist）添加。确保将此文件添加到您的应用程序目标中。

限制

-force_load和-all_load

.XCFramework当前不允许开发者在应用启动时加载库。这仅影响SPM包。目前没有可用的解决方案。

SDK不自动加载（即上面失败的情况）

在目标设置的其他链接器标志中添加-ObjC标志。此标志会使链接器加载库中定义Objective-C类或分类的每个目标文件。虽然这通常会导致可执行文件更大（由于向应用程序中加载了额外的目标代码），但它将允许创建包含现有类分类的有效Objective-C静态库。

对Mac催化剂的支持

Mac催化剂支持仅可在SPM和手动安装中使用，因为我们应使用.XCFramework。使用 来创建静态库不适用，因为它无法理解类似但支持Mac不同风味的目标架构。