Trace SDK

Bitrise statusCocoapodsCocoapods platformsMac CatalystCocoapodsCarthageSwift versionSPMTwitter URLJoin Slack groupBCH complianceQuality Gate Status

在 Bug 到达生产环境之前发现它们 — 获取详细的崩溃报告并监控您的应用在整个安装基础上的表现。当检测到问题时，我们会向您展示用户会话期间发生的确切情况，以便尽可能快地定位、重现和修复问题。使用 Trace 来

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

* Trace * Trace 配置设置

要求

安装

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

每个框架都可以在 Xcode 的框架列表中找到。目前支持以下集成选项

Bitrise 工作流

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

使用 添加 trace SDK 步骤自动将 SDK 添加到您的项目。所有下载、链接 SDK 和支持的系统框架和库都将为您完成。此步骤 必须 在 Xcode Archive & Export step 之前，因为它必须事先链接。

直接从源代码安装

如果步骤项目位于 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，则将 -force_load 添加到 SDK。 这用于确保 SDK 在应用程序启动时启动。

# 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

注意：目前不支持开箱即用的 Cartage，需要几个步骤才能使其运行。请按照 集成步骤 进行操作。等待 [].xcframework 支持](Carthage/Carthage#2881)

将其添加到您的 Cartfile

github "bitrise-io/trace-cocoa-sdk"
$ carthage update

将库包含到您的 Xcode 项目后

Carthage 作为静态库

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

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

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 Package Manager 是一种用于自动分发 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 文件中。请查看 release section 获取 SDK 的最新稳定版本。

使用 Xcode Swift 包管理器集成

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

此外，您还可以导航到目标 “General” 面板，并在 “Frameworks, Libraries, and Embedded Content” 部分中，单击 + 按钮，选择 Add Other，然后选择 Add Package Dependency。

可选：仅在项目无法构建时才需要 将 `Other Linker Flags 添加到应用程序目标

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

调用 Trace 初始化程序

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

手动

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

在构建时嵌入静态库

注意：代码段假定该库与您的 xcproject/xcworkspace 项目位于同一目录中。 如果您使用其他位置，请添加新路径。

嵌入式 Xcode 项目

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

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

上传 dSYM

Bitrise 工作流步骤

此步骤会自动上传从 Xcode 存档创建的所有 dSYM 文件。它使用默认的 Xcode 路径来查找所有 dSYM 文件并自动上传所有文件。

注意：使用 bitcode 功能向 iTunes Connect 提交构建的应用程序必须手动下载所有 dSYM 文件，并使用 Github 上找到的 upload dSYM 脚本进行上传。 只有在 Apple 处理完之后（可能需要长达一个小时）。 请参阅以下说明

所有其他依赖项管理器

在 Xcode 项目/工作区上完成 Trace SDK 安装步骤后，选择您的 application target 并转到 build phases 选项卡。

选择加号按钮并添加 New Run Script Phase。 将其命名为 Bitrise Trace SDK - Upload dSYM's

将以下代码复制并粘贴到脚本部分

#!/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（支持 Bitcode 的应用程序）

您必须首先从 iTunes Connect 的 Activity->Build->Download 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->Settings 中找到的 Trace 令牌。

就这样！ 运行构建时，如果您转到构建日志部分，您将看到完成后的结果。 查看 Bitrise Trace SDK - Upload dSYM's。

存储

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

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

常见问题

C++ 系统库未链接

无法找到 Trace 库

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

无法找到收集器令牌

确保 bitrise_configuration.plist 包含在您的项目中，并且目标成员资格设置为正确的目标。

无法找到收集器令牌

[Bitrise:Trace/internalError] Bitrise configuration file is missing from Bundle.main [Bitrise:Trace/internalError] Application failed to read the configuration file, all data will be cached until it's resolved

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

限制

-force_load 和 -all_load

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

SDK 没有自动加载 (例如，上述方法失败)

在目标设置中的“Other Linker Flags”中添加 -ObjC 标志。 此标志会导致链接器加载库中定义 Objective-C 类或类别的每个对象文件。 虽然此选项通常会导致更大的可执行文件（由于加载到应用程序中的额外对象代码），但它将允许成功创建有效的 Objective-C 静态库，该库包含现有类上的类别。

Mac Catalyst 支持

Mac Catalyst 支持仅在 SPM 和手动安装中可用，因为我们应该使用 .XCFramework。 使用 lipo 创建静态库不起作用，因为它无法理解相似但具有不同风格以支持 Mac 的架构。

其他

特别感谢

许可证

Trace 在 MIT 许可下发布。 有关详细信息，请参见 LICENSE。