iOS RUM SDK 高级配置

概述

FlashCat 真实用户监控（RUM）提供多种高级配置选项,允许您根据需求修改收集的数据和上下文,支持以下场景:

保护敏感数据:屏蔽个人身份信息等敏感数据

关联用户会话:将用户会话与内部用户标识关联,便于支持和问题排查

减少数据量:通过采样降低 RUM 数据收集量,优化成本

增强上下文:为数据添加比默认属性更丰富的上下文信息

以下章节详细介绍如何实现这些功能。

丰富用户会话

自定义视图

默认情况下,RUM SDK 会自动追踪 UIViewController 或 SwiftUI View。如果您想手动追踪特定的视图或为自动追踪的视图添加自定义时间和属性,可以使用 RUM iOS SDK 提供的 API。

手动开始和停止视图

调用 RUMMonitor.shared().startView(key:name:attributes:) 开始追踪新的 RUM 视图。同一 key 的所有视图将被分组在 RUM Explorer 中。

当视图不再可见时,调用 RUMMonitor.shared().stopView(key:attributes:) 停止追踪。

@import FlashcatObjc;
// in your `UIViewController`:

- (void)viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];

    [[RUMMonitor shared] startViewWithKey:@"view-key" name:@"View Name" attributes:@{@"foo": @"bar"}];
}

- (void)viewDidDisappear:(BOOL)animated {
    [super viewDidDisappear:animated];

    [[RUMMonitor shared] stopViewWithKey:@"view-key" attributes:@{@"foo": @"bar"}];
}

自定义操作

除了自动追踪用户操作外,您还可以手动追踪特定的自定义操作（如点击、滚动、滑动等）,可以使用 RUMMonitor.shared().addAction(type:name:attributes:):

@import FlashcatObjc;

- (IBAction)didTapDownloadResourceButton:(UIButton *)sender {
    [[RUMMonitor shared] addActionWithType:RUMActionTypeTap name:sender.currentTitle attributes:@{@"resource_id": @"123"}];
}

注意: 使用 RUMMonitor.shared().addAction(type:name:attributes:) 时,RUM SDK 会创建一个 RUM 操作,并将所有新的资源、错误和长任务附加到此操作,直到视图被视为已完成加载。

自定义资源

FlashCat iOS SDK 会自动追踪通过启用的 URLSession 发起的网络请求。如果您想手动追踪自定义资源（如网络请求、第三方提供商的 API、GraphQL 查询等）,可以使用以下方法:

调用 RUMMonitor.shared().startResource(resourceKey:request:attributes:) 开始加载资源,然后调用 RUMMonitor.shared().stopResource(resourceKey:response:size:attributes:) 在加载完成时停止,或调用 RUMMonitor.shared().stopResourceWithError(resourceKey:error:attributes:) 在加载失败时停止:

@import FlashcatObjc;

// in your network client:
[[RUMMonitor shared] startResourceWithResourceKey:@"resource-key" request:request attributes:@{@"foo": @"bar"}];

[[RUMMonitor shared] stopResourceWithResourceKey:@"resource-key" response:response size:size attributes:@{@"foo": @"bar"}];

注意: 用于上述两个调用的 resourceKey 必须唯一,才能使 RUM iOS SDK 将资源的开始与其完成匹配。

自定义错误

要追踪特定错误,当错误发生时通知 RUMMonitor:

@import FlashcatObjc;

[[RUMMonitor shared] addErrorWithMessage:@"Error message"
                                    type:@"ErrorType"
                                  source:DDRUMErrorSourceCustom
                                   stack:@"Error stack trace"
                              attributes:@{@"foo": @"bar"}
                                    file:file
                                    line:line];

追踪自定义全局属性

FlashCat iOS SDK 会自动捕获默认 RUM 属性。此外,您还可以向 RUM 事件添加额外的上下文信息,例如自定义属性。

自定义属性使您能够根据代码级别的信息（如购物车价值、商家等级或广告活动）过滤和分组观察到的用户行为信息。

设置自定义全局属性

要设置自定义全局属性,请使用 RUMMonitor.shared().addAttribute(forKey:value:):

@import FlashcatObjc;

[[RUMMonitor shared] addAttributeForKey:@"user_plan" value:@"premium"];

注意: 不能使用以下键名,因为它们被 SDK 内部使用: date, error.kind, error.message, error.stack, error.source_type, view.id, view.url, view.loading_time, view.referrer, application.id。

要删除自定义全局属性,请使用 RUMMonitor.shared().removeAttribute(forKey:):

@import FlashcatObjc;

[[RUMMonitor shared] removeAttributeForKey:@"user_plan"];

追踪用户会话

为 RUM 会话添加用户信息可以让您:

跟踪特定用户的浏览路径

了解哪些用户受错误影响最大

监控关键用户的性能

以下属性是可选的,您应该至少提供其中一个:

usr.id (字符串): 唯一用户标识符

usr.name (字符串): 用户友好名称,默认在 RUM UI 中显示

usr.email (字符串): 用户电子邮件,若无名称则显示邮件

要识别用户会话,在初始化 SDK 后使用 Flashcat.setUserInfo(id:name:email:extraInfo:):

@import FlashcatObjc;

[Flashcat setUserInfoWithId:@"1234"
                       name:@"John Doe"
                      email:@"john@doe.com"
                  extraInfo:@{@"plan": @"premium", @"signup_date": @"2024-01-15"}];

追踪后台事件

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

在配置 RUM 时添加 trackBackgroundEvents 设置:

@import FlashcatObjc;

DDRUMConfiguration *configuration = [[DDRUMConfiguration alloc] initWithApplicationID:@"<RUM_APPLICATION_ID>"];
configuration.trackBackgroundEvents = YES;

[RUM enableWith:configuration];

初始化参数

在创建 Flashcat 配置时,可以设置以下属性:

Flashcat 配置

参数	类型	必填	说明
`clientToken`	String	是	客户端令牌
`env`	String	是	环境名称
`site`	Flashcat.Site	是	数据上报站点 (`.us1`, `.us3`, `.us5`, `.eu1`, `.ap1`)
`service`	String	否	服务名称,默认为应用 bundle 标识符
`batchSize`	BatchSize	否	批量上传数据大小,可选: `.small`, `.medium`, `.large`
`uploadFrequency`	UploadFrequency	否	数据上传频率,可选: `.frequent`, `.average`, `.rare`

RUM 配置

创建 RUM 配置时可以设置以下参数:

参数	类型	必填	说明
`applicationID`	String	是	RUM 应用 ID
`sessionSampleRate`	Float	否	会话采样率 (0-100),默认 100
`uiKitViewsPredicate`	UIKitRUMViewsPredicate	否	UIKit 视图追踪策略
`uiKitActionsPredicate`	UIKitRUMActionsPredicate	否	UIKit 操作追踪策略
`swiftUIViewsPredicate`	SwiftUIRUMViewsPredicate	否	SwiftUI 视图追踪策略
`swiftUIActionsPredicate`	SwiftUIRUMActionsPredicate	否	SwiftUI 操作追踪策略
`urlSessionTracking`	URLSessionTracking	否	URLSession 网络请求追踪配置
`trackBackgroundEvents`	Bool	否	是否追踪后台事件,默认 false
`trackFrustrations`	Bool	否	是否追踪用户挫败感（如错误点击）,默认 true
`trackLongTasks`	Bool	否	是否追踪长任务,默认 true
`longTaskThreshold`	TimeInterval	否	长任务阈值(秒),默认 0.1 秒
`vitalsUpdateFrequency`	VitalsFrequency	否	性能指标更新频率,可选: `.frequent`, `.average`, `.rare`, `.never`

自动追踪视图

要启用视图自动追踪,在初始化 RUM 时设置 uiKitViewsPredicate 或 swiftUIViewsPredicate。

对于 UIKit,使用 DefaultUIKitRUMViewsPredicate 类:

对于 SwiftUI,使用 DefaultSwiftUIRUMViewsPredicate 类:

您还可以实现自定义的 predicate 来自定义追踪行为。

自动追踪用户操作

要启用用户操作自动追踪,在初始化 RUM 时设置 uiKitActionsPredicate 或 swiftUIActionsPredicate。

对于 UIKit:

对于 SwiftUI:

自动追踪网络请求

要启用网络请求自动追踪（资源和错误）,在初始化 RUM 时设置 urlSessionTracking 并启用 URLSessionInstrumentation:

您还可以配置 firstPartyHostsTracing 以启用分布式追踪,将 RUM 资源与后端 traces 关联:

自动追踪错误

所有"致命"和"非致命"的 iOS 错误都会自动收集并附加当前 RUM 视图的完整错误详情和元数据。

致命错误包括应用崩溃。非致命错误包括:

Swift errors: Swift throw 的错误

Objective-C exceptions: Objective-C 异常

您可以通过 RUM Explorer 和 Error Tracking 查看错误详情。

修改或丢弃 RUM 事件

在 RUM 事件发送到 FlashCat 之前,您可以通过事件映射器（Event Mappers）对其进行修改或完全丢弃。

事件映射器在创建 RUM 配置时设置:

@import FlashcatObjc;

DDRUMConfiguration *configuration = [[DDRUMConfiguration alloc] initWithApplicationID:@"<RUM_APPLICATION_ID>"];

[configuration setViewEventMapper:^DDRUMViewEvent * _Nonnull(DDRUMViewEvent * _Nonnull RUMViewEvent) {
    return RUMViewEvent;
}];

[configuration setErrorEventMapper:^DDRUMErrorEvent * _Nullable(DDRUMErrorEvent * _Nonnull RUMErrorEvent) {
    return RUMErrorEvent;
}];

[configuration setResourceEventMapper:^DDRUMResourceEvent * _Nullable(DDRUMResourceEvent * _Nonnull RUMResourceEvent) {
    return RUMResourceEvent;
}];

[configuration setActionEventMapper:^DDRUMActionEvent * _Nullable(DDRUMActionEvent * _Nonnull RUMActionEvent) {
    return RUMActionEvent;
}];

[configuration setLongTaskEventMapper:^DDRUMLongTaskEvent * _Nullable(DDRUMLongTaskEvent * _Nonnull RUMLongTaskEvent) {
    return RUMLongTaskEvent;
}];

每个映射器都是一个签名为 (T) -> T? 的 Swift 闭包,其中 T 是具体的 RUM 事件类型。这允许在事件发送之前更改部分事件。

例如,要屏蔽 RUM Resource 的 url 中的敏感信息,实现一个自定义的 redacted(_:) -> String 函数并在 resourceEventMapper 中使用它:

DDRUMConfiguration *configuration = [[DDRUMConfiguration alloc] initWithApplicationID:@"<RUM_APPLICATION_ID>"];

[configuration setResourceEventMapper:^DDRUMResourceEvent * _Nullable(DDRUMResourceEvent * _Nonnull RUMResourceEvent) {
    return RUMResourceEvent;
}];

从 error、resource 或 action 映射器返回 nil 将完全丢弃该事件;该事件不会发送到 FlashCat。从 view 事件映射器返回的值不能为 nil（要丢弃视图,请自定义 UIKitRUMViewsPredicate 的实现;详见追踪视图自动化）。

根据事件的类型,只有某些特定的属性可以被修改:

事件类型	属性键	说明
RUMActionEvent	`RUMActionEvent.action.target?.name`	操作名称
	`RUMActionEvent.view.url`	与此操作关联的视图 URL
RUMErrorEvent	`RUMErrorEvent.error.message`	错误消息
	`RUMErrorEvent.error.stack`	错误堆栈跟踪
	`RUMErrorEvent.error.resource?.url`	错误引用的资源 URL
	`RUMErrorEvent.view.url`	与此错误关联的视图 URL
RUMResourceEvent	`RUMResourceEvent.resource.url`	资源 URL
	`RUMResourceEvent.view.url`	与此资源关联的视图 URL
RUMViewEvent	`RUMViewEvent.view.name`	视图名称
	`RUMViewEvent.view.url`	视图 URL
	`RUMViewEvent.view.referrer`	链接到页面初始视图的 URL

获取 RUM 会话 ID

检索 RUM 会话 ID 对于故障排查非常有用。例如,您可以将会话 ID 附加到支持请求、电子邮件或错误报告中,以便您的支持团队稍后在 FlashCat 中找到用户会话。

您可以在运行时访问 RUM 会话 ID,无需等待 sessionStarted 事件:

@import FlashcatObjc;

[[RUMMonitor shared] currentSessionIDWithCompletion:^(NSString * _Nullable sessionId) {
    // use session ID
}];

设置追踪同意（GDPR 合规）

为符合 GDPR 法规,FlashCat iOS SDK 在初始化时需要追踪同意值。

trackingConsent 设置可以是以下值之一:

.pending: FlashCat iOS SDK 开始收集和批处理数据,但不发送到 FlashCat。FlashCat iOS SDK 等待新的追踪同意值来决定如何处理批处理的数据。

.granted: FlashCat iOS SDK 开始收集数据并发送到 FlashCat。

.notGranted: FlashCat iOS SDK 不收集任何数据。不会发送日志、traces 或 RUM 事件到 FlashCat。

在 FlashCat iOS SDK 初始化后更改追踪同意值,请使用 Flashcat.set(trackingConsent:) API 调用。FlashCat iOS SDK 会根据新值更改其行为。

例如,如果当前追踪同意是 .pending:

如果您将值更改为 .granted,FlashCat iOS SDK 将发送所有当前和未来的数据到 FlashCat;

如果您将值更改为 .notGranted,FlashCat iOS SDK 将清除所有当前数据并且不收集未来的数据。

@import FlashcatObjc;

[Flashcat setWithTrackingConsent:DDTrackingConsentGranted];

添加用户属性

您可以使用 Flashcat.addUserExtraInfo(_:) API 将额外的用户属性附加到先前设置的属性上。

@import FlashcatObjc;

[Flashcat addUserExtraInfo:@{@"company": @"FlashCat"}];

数据管理

清除所有数据

您可以选择删除 SDK 存储的所有未发送数据,使用 Flashcat.clearAllData() API:

@import FlashcatObjc;

[Flashcat clearAllData];

停止数据收集

您可以使用 Flashcat.stopInstance() API 停止命名的 SDK 实例（如果名称为 nil 则停止默认实例）进一步收集和上传数据。

@import FlashcatObjc;

[Flashcat stopInstance];

调用此方法会禁用 SDK 和所有活跃的功能,如 RUM。要恢复数据收集,您必须重新初始化 SDK。如果您想动态更改配置,可以使用此 API。

采样

默认情况下,FlashCat RUM 会收集所有会话的数据。您可以通过 sessionSampleRate 参数设置采样率（百分比）来减少收集的会话数量。例如,采集 90% 的会话:

@import FlashcatObjc;

DDRUMConfiguration *configuration = [[DDRUMConfiguration alloc] initWithApplicationID:@"<RUM_APPLICATION_ID>"];
configuration.sessionSampleRate = 90;

[RUM enableWith:configuration];

被采样的会话将不收集任何视图及其相关遥测数据。

集成 RUM 与分布式追踪

集成 RUM 与分布式追踪,可让您将 iOS 应用程序的请求与其对应的后端跟踪关联起来。这种组合让您能够一目了然地查看完整的前端和后端数据。

使用来自 RUM 的前端数据以及来自 trace ID 注入的后端、基础设施和日志信息来定位堆栈中任何地方的问题并了解用户的体验。

配置方法

初始化 RUM SDK,使用 firstPartyHostsTracing 来配置当前应用的 API 服务域名:

@import FlashcatObjc;

DDRUMConfiguration *configuration = [[DDRUMConfiguration alloc] initWithApplicationID:@"<RUM_APPLICATION_ID>"];

DDURLSessionTracking *urlSessionTracking = [DDURLSessionTracking new];
[urlSessionTracking setFirstPartyHostsTracing:[DDRUMFirstPartyHostsTracing alloc] initWithHosts:@[@"api.example.com", @"example.com"] sampleRate:20];

configuration.urlSessionTracking = urlSessionTracking;

[RUM enableWith:configuration];

[DDURLSessionInstrumentation enableWithConfiguration:[DDURLSessionInstrumentationConfiguration alloc] initWithDelegateClass:[SessionDelegate class]]];

参数说明:

hosts: 需要追踪的域名列表

sampleRate: 要追踪的请求百分比（0-100）,默认 100

如何关联

分布式追踪协议通过在 HTTP Header 上添加对应的头部字段（traceparent、tracestate）实现,以下是对相应 header 的说明:

traceparent: [version]-[trace id]-[parent id]-[trace flags]

version: 当前为 00

trace id: 128 bits 的 trace ID 通过 16 进制处理后变成 32 个字符

parent id: 64 bits 的 span ID,16 进制处理后为 16 个字符

trace flags: 代表是否有降采样,01 代表命中采样,00 代表非采样

tracestate: dd=s:[sampling priority];o:[origin]

sampling priority: 1 代表 trace 被采样

origin: 始终为 rum,代表通过 RUM SDK 采集

示例:

traceparent: 00-00000000000000008448eb211c80319c-b7ad6b7169203331-01
tracestate: dd=s:1;o:rum

如何验证

添加配置后,可在 Xcode 的网络调试工具或代理工具（如 Charles、Proxyman）中查看从应用中发送的请求,如能正确携带对应的 header 则说明配置无误。

注意事项

确保正确配置 applicationID 和 clientToken,以避免数据上传失败

根据应用需求调整采样率和隐私设置,平衡数据量与合规性

事件映射器中修改的属性应遵循允许修改的属性列表

对于复杂的视图追踪场景,建议实现自定义的 ViewsPredicate

高级配置

概述#

丰富用户会话#

自定义视图#

手动开始和停止视图#

自定义操作#

自定义资源#

自定义错误#

追踪自定义全局属性#

设置自定义全局属性#

追踪用户会话#

追踪后台事件#

初始化参数#

Flashcat 配置#

RUM 配置#

自动追踪视图#

自动追踪用户操作#

自动追踪网络请求#

自动追踪错误#

修改或丢弃 RUM 事件#

获取 RUM 会话 ID#

设置追踪同意（GDPR 合规）#

添加用户属性#

数据管理#

清除所有数据#

停止数据收集#

采样#

集成 RUM 与分布式追踪#

配置方法#

如何关联#

如何验证#

注意事项#

更多阅读#

概述