iOS RUM SDK 接入指南

概述

FlashCat iOS RUM SDK 支持 iOS 12.0、iPadOS 12.0、tvOS 12.0 及以上版本。通过集成 SDK，您可以实时监控 iOS 应用的性能、错误和用户行为。

接入步骤

步骤 1：添加 SDK 依赖

FlashCat iOS SDK 支持通过 Swift Package Manager 安装。

在 Xcode 中，打开您的项目，选择 File > Add Package Dependencies

在搜索栏中输入 FlashCat SDK 的 Git 仓库 URL：

https://github.com/flashcat-cloud/fc-ios-sdk

选择需要的版本或分支（默认发布分支为 public）

在 Add to Target 中选择您的应用目标

添加以下包依赖：

FlashcatCore：核心 SDK

FlashcatRUM：RUM 功能模块

步骤 2：在 UI 中获取应用信息

在 FlashCat 控制台的 RUM 应用管理页面：

创建或选择一个 iOS 应用

获取以下信息：

Application ID：应用唯一标识符

Client Token：客户端访问令牌

步骤 3：初始化 SDK

在您的 AppDelegate.swift 的 application(_:didFinishLaunchingWithOptions:) 方法中初始化 FlashCat SDK：

初始化参数说明

clientToken：从 FlashCat 控制台获取的客户端令牌（必填）

env：环境名称，如 production、staging（必填）

site：数据上报站点，可选值：.us1、.us3、.us5、.eu1、.ap1（必填）

trackingConsent：用户追踪同意状态，可选值：

.pending：SDK 开始收集和批处理数据，但不发送到 FlashCat，等待新的追踪同意值

.granted：SDK 开始收集数据并发送到 FlashCat

.notGranted：SDK 不收集任何数据

您可以在初始化后通过 Flashcat.set(trackingConsent:) 动态修改追踪同意状态。

步骤 4：启用 RUM 功能并开始发送数据

配置并启用 RUM 功能。建议在 AppDelegate 中尽早启用：

RUM 配置参数说明

applicationID：从控制台获取的 RUM 应用 ID

uiKitViewsPredicate：UIKit 视图追踪策略

uiKitActionsPredicate：UIKit 用户操作追踪策略

swiftUIViewsPredicate：SwiftUI 视图追踪策略

swiftUIActionsPredicate：SwiftUI 用户操作追踪策略

urlSessionTracking：URLSession 网络请求追踪配置

步骤 5：追踪网络事件

启用 URLSession 追踪

要监控从 URLSession 实例发送的网络请求，需要启用 URLSessionInstrumentation 并传入您的 delegate 类型：

配置完成后，SDK 会自动追踪所有网络请求，包括：

请求 URL、方法、状态码

请求和响应头信息

请求时长和数据大小

网络错误信息

注意：只有在视图处于活动状态时发起的网络请求才会被追踪。

视图追踪

FlashCat iOS SDK 支持自动追踪 UIKit 和 SwiftUI 视图。

UIKit 视图自动追踪

UIKit 视图会通过默认的 DefaultUIKitRUMViewsPredicate 自动追踪。SDK 会追踪 UIViewController 的生命周期，自动记录视图的显示和隐藏。

SwiftUI 视图追踪

对于 SwiftUI 应用，需要在视图中手动添加追踪代码：

trackRUMView(name:) 方法会在 SwiftUI 视图出现和消失时自动开始和停止视图追踪。

自定义视图追踪

如果需要更精细的控制，可以手动追踪视图：

用户操作追踪

UIKit 操作自动追踪

UIKit 中的用户操作（如点击按钮、切换开关等）会通过 DefaultUIKitRUMActionsPredicate 自动追踪。

SwiftUI 操作追踪

对于 SwiftUI 控件，可以添加 .trackRUMTapAction(name:) 修饰符：

注意：在 List 内使用 .trackRUMTapAction(name:) 可能会影响默认手势（例如禁用 Button 操作或破坏 NavigationLink）。对于 List 元素，建议使用自定义操作 API。

自定义操作追踪

手动追踪用户操作：

追踪 iOS 错误

FlashCat iOS SDK 会自动捕获应用崩溃和未捕获的异常。您也可以手动记录错误：

所有错误信息都会在 FlashCat 控制台的 RUM Explorer 中显示，包括错误堆栈、属性和 JSON 详情。

追踪后台事件

您可以追踪应用在后台运行时的事件（例如崩溃和网络请求）。

在配置 RUM 时添加以下代码：

追踪用户信息

您可以为当前会话设置用户信息：

设备离线时发送数据

iOS SDK 确保在用户设备离线时的数据可用性。在网络信号弱或设备电量过低的情况下，所有事件首先以批次形式存储在本地设备上。

只要网络可用且电量充足，批次就会被发送，以确保 FlashCat SDK 不会影响最终用户的体验。如果应用在前台运行时网络不可用，或者数据上传失败，批次会被保留，直到成功发送为止。

这意味着即使用户在离线时打开您的应用，也不会丢失数据。为了确保 SDK 不会占用过多磁盘空间，磁盘上过旧的数据会被自动丢弃。

WebView 集成

如果您的 iOS 应用中包含 WKWebView，可以通过以下方式启用 WebView 追踪：

添加 WebView 依赖

Swift Package Manager

在添加包依赖时，同时添加 FlashcatWebView 模块。

启用 WebView 追踪

在您的 ViewController 中启用 WebView 追踪：

参数说明：

webView: 需要追踪的 WKWebView 实例

hosts: 允许追踪的域名列表，支持通配符

这样，您的 WebView 中的 Web 页面就可以与原生应用的 RUM 数据关联起来。

禁用自动用户数据收集

为了符合隐私法规或组织数据治理政策，您可能需要禁用自动收集用户数据。

要禁用客户端 IP 或地理位置数据的自动收集：

创建应用后，进入 应用管理页面并点击您的应用

点击 用户数据收集

使用开关来控制这些设置

验证接入

接入完成后，您可以通过以下步骤验证是否接入成功：

查看控制台日志：在 Xcode 控制台中搜索 FlashCat 关键字，查看 SDK 初始化和数据上报日志

访问控制台：登录 FlashCat 控制台，进入对应的 RUM 应用，查看是否有数据上报

触发测试事件：

打开应用的不同页面，验证页面浏览事件

执行一些用户操作（点击、滑动等），验证交互事件

触发网络请求，验证资源加载事件

手动触发一个错误，验证错误追踪

支持的版本

FlashCat iOS SDK 支持以下平台和版本：

iOS: 12.0 及以上

iPadOS: 12.0 及以上

tvOS: 12.0 及以上

macOS: 10.14 及以上（Mac Catalyst）

语言支持：

Swift 5.0 及以上

Objective-C

SDK接入

概述

接入步骤

步骤 1：添加 SDK 依赖

步骤 2：在 UI 中获取应用信息

步骤 3：初始化 SDK

初始化参数说明

步骤 4：启用 RUM 功能并开始发送数据

RUM 配置参数说明

步骤 5：追踪网络事件

启用 URLSession 追踪

视图追踪

UIKit 视图自动追踪

SwiftUI 视图追踪

自定义视图追踪

用户操作追踪

UIKit 操作自动追踪

SwiftUI 操作追踪

自定义操作追踪

追踪 iOS 错误

追踪后台事件

追踪用户信息

设备离线时发送数据

WebView 集成

添加 WebView 依赖

Swift Package Manager

启用 WebView 追踪

禁用自动用户数据收集

验证接入

支持的版本

更多阅读

SDK接入

概述#

接入步骤#

步骤 1：添加 SDK 依赖#

步骤 2：在 UI 中获取应用信息#

步骤 3：初始化 SDK#

初始化参数说明#

步骤 4：启用 RUM 功能并开始发送数据#

RUM 配置参数说明#

步骤 5：追踪网络事件#

启用 URLSession 追踪#

视图追踪#

UIKit 视图自动追踪#

SwiftUI 视图追踪#

自定义视图追踪#

用户操作追踪#

UIKit 操作自动追踪#

SwiftUI 操作追踪#

自定义操作追踪#

追踪 iOS 错误#

追踪后台事件#

追踪用户信息#

设备离线时发送数据#

WebView 集成#

添加 WebView 依赖#

Swift Package Manager#

启用 WebView 追踪#

禁用自动用户数据收集#

验证接入#

支持的版本#

更多阅读#

概述

接入步骤

步骤 1：添加 SDK 依赖

步骤 2：在 UI 中获取应用信息

步骤 3：初始化 SDK

初始化参数说明

步骤 4：启用 RUM 功能并开始发送数据

RUM 配置参数说明

步骤 5：追踪网络事件

启用 URLSession 追踪

视图追踪

UIKit 视图自动追踪

SwiftUI 视图追踪

自定义视图追踪

用户操作追踪

UIKit 操作自动追踪

SwiftUI 操作追踪

自定义操作追踪

追踪 iOS 错误

追踪后台事件

追踪用户信息

设备离线时发送数据

WebView 集成

添加 WebView 依赖

Swift Package Manager

启用 WebView 追踪

禁用自动用户数据收集

验证接入

支持的版本

更多阅读