> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.
# iOS SDK 高级配置
> 深入配置 iOS RUM SDK 的高级功能，包括自定义事件、用户追踪、采样控制和数据安全
本文介绍 iOS RUM SDK 的高级用法：手动追踪视图、操作、资源和错误，添加全局属性和用户信息，修改或丢弃事件，采样与远程配置，以及关联分布式追踪。
SDK 兼容 Datadog 开源协议：在 Swift Package Manager 或 CocoaPods 中添加依赖时使用 `FlashcatCore`、`FlashcatRUM` 等名称，代码中 import 时使用 `DatadogCore`、`DatadogRUM` 等模块名，因此可以直接参考 Datadog 生态的文档和示例。
## 丰富用户会话
### 自定义视图
默认情况下，RUM SDK 会自动追踪 `UIViewController` 或 SwiftUI `View`。您也可以手动追踪特定的视图或为自动追踪的视图添加自定义属性。
调用 `RUMMonitor.shared().startView()` 开始追踪新的 RUM 视图。同一 `key` 的所有视图将被分组在 RUM Explorer 中。
```swift theme={null}
import DatadogRUM
// 在您的 UIViewController 中
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
RUMMonitor.shared().startView(
key: "view-key",
name: "View Name",
attributes: ["foo": "bar"]
)
}
override func viewDidDisappear(_ animated: Bool) {
super.viewDidDisappear(animated)
RUMMonitor.shared().stopView(
key: "view-key",
attributes: ["foo": "bar"]
)
}
```
```objective-c theme={null}
@import DatadogObjc;
// 在您的 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"}];
}
```
### 自定义操作
除了自动追踪用户操作外，您还可以手动追踪特定的自定义操作（如点击、滚动、滑动等）。
```swift theme={null}
import DatadogRUM
// 在您的 UIViewController 中
@IBAction func didTapDownloadResourceButton(_ sender: UIButton) {
RUMMonitor.shared().addAction(
type: .tap,
name: sender.currentTitle ?? "",
attributes: ["resource_id": "123"]
)
}
```
```objective-c theme={null}
@import DatadogObjc;
- (IBAction)didTapDownloadResourceButton:(UIButton *)sender {
[[RUMMonitor shared] addActionWithType:RUMActionTypeTap
name:sender.currentTitle
attributes:@{@"resource_id": @"123"}];
}
```
使用 `addAction()` 时，RUM SDK 会创建一个 RUM 操作，并将所有新的资源、错误和长任务附加到此操作，直到视图被视为已完成加载。
### 自定义资源
Flashduty iOS SDK 会自动追踪通过启用的 `URLSession` 发起的网络请求。您也可以手动追踪自定义资源（如第三方 API、GraphQL 查询等）。
```swift theme={null}
import DatadogRUM
// 在您的网络客户端中
RUMMonitor.shared().startResource(
resourceKey: "resource-key",
request: request,
attributes: ["foo": "bar"]
)
// 加载成功时
RUMMonitor.shared().stopResource(
resourceKey: "resource-key",
response: response,
size: size,
attributes: ["foo": "bar"]
)
// 加载失败时
RUMMonitor.shared().stopResourceWithError(
resourceKey: "resource-key",
error: error,
attributes: ["foo": "bar"]
)
```
```objective-c theme={null}
@import DatadogObjc;
// 在您的网络客户端中
[[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`：
```swift theme={null}
import DatadogRUM
RUMMonitor.shared().addError(
message: "Error message",
type: "ErrorType",
source: .source,
stack: "Error stack trace",
attributes: ["foo": "bar"],
file: #file,
line: #line
)
```
```objective-c theme={null}
@import DatadogObjc;
[[RUMMonitor shared] addErrorWithMessage:@"Error message"
type:@"ErrorType"
source:DDRUMErrorSourceCustom
stack:@"Error stack trace"
attributes:@{@"foo": @"bar"}
file:file
line:line];
```
更多错误上报详情，请参阅 [iOS 异常上报](/zh/rum/error-tracking/error-reporting/ios)。
## 追踪自定义全局属性
除 SDK 自动采集的默认属性外，您可以为所有 RUM 事件添加自定义全局属性，用于按业务信息（如购物车价值、用户等级、广告活动）过滤和分组，对比不同用户群体的性能与错误分布。
```swift theme={null}
import DatadogRUM
// 添加全局属性
RUMMonitor.shared().addAttribute(forKey: "user_plan", value: "premium")
// 删除全局属性
RUMMonitor.shared().removeAttribute(forKey: "user_plan")
```
```objective-c theme={null}
@import DatadogObjc;
// 添加全局属性
[[RUMMonitor shared] addAttributeForKey:@"user_plan" value:@"premium"];
// 删除全局属性
[[RUMMonitor shared] removeAttributeForKey:@"user_plan"];
```
**保留键名：**\
不能使用以下键名，因为它们被 SDK 内部使用：`date`、`error.kind`、`error.message`、`error.stack`、`error.source_type`、`view.id`、`view.url`、`view.loading_time`、`view.referrer`、`application.id`
## 追踪用户会话
为 RUM 会话添加用户信息后，可以跟踪特定用户的浏览路径，了解哪些用户受错误影响最大。
```swift theme={null}
import DatadogCore
Datadog.setUserInfo(
id: "1234",
name: "John Doe",
email: "john@doe.com"
)
```
```objective-c theme={null}
@import DatadogObjc;
[DDDatadog setUserInfoWithId:@"1234"
name:@"John Doe"
email:@"john@doe.com"
extraInfo:nil];
```
当前仅支持设置用户标准字段：`id`、`name`、`email`、`anonymous_id`；其他用户属性不支持。如有需求，可以在 `context` 字段进行配置。
**参数说明：**
* `usr.id` (字符串) - 唯一用户标识符
* `usr.name` (字符串) - 用户友好名称，默认在 RUM UI 中显示
* `usr.email` (字符串) - 用户电子邮件，若无名称则显示邮件
* 以上属性均为可选，建议至少提供一个
## 追踪后台事件
您可以追踪应用在后台运行时的事件（如崩溃和网络请求）。
```swift theme={null}
import DatadogRUM
RUM.enable(
with: RUM.Configuration(
applicationID: "",
trackBackgroundEvents: true
)
)
```
```objective-c theme={null}
@import DatadogObjc;
DDRUMConfiguration *configuration = [[DDRUMConfiguration alloc]
initWithApplicationID:@""];
configuration.trackBackgroundEvents = YES;
[RUM enableWith:configuration];
```
追踪后台事件可能会产生额外的会话，从而影响计费。如有疑问，请联系 Flashduty 支持团队。
## 初始化参数
在创建 SDK 配置时，可以设置以下属性：
| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `clientToken` | String | ✅ | 客户端令牌 |
| `env` | String | ✅ | 环境名称（如 `production`、`staging`） |
| `service` | String | 可选 | 服务名称，默认为应用 bundle 标识符 |
| `batchSize` | BatchSize | 可选 | 批量上传数据大小（`.small`、`.medium`、`.large`） |
| `uploadFrequency` | UploadFrequency | 可选 | 数据上传频率（`.frequent`、`.average`、`.rare`） |
创建 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 秒 |
| `appHangThreshold` | TimeInterval? | 否 | App Hang 检测阈值（秒），**默认 `nil`，即不开启**，详见下方说明 |
| `vitalsUpdateFrequency` | VitalsFrequency | 否 | 性能指标更新频率，可选：`.frequent`、`.average`、`.rare`、`.never` |
### App Hang 检测
App Hang 指主线程被阻塞、界面无法响应用户操作的时间段。在 iOS 应用中，它是分析看板**无响应时长率**指标的唯一数据来源。
`appHangThreshold` **默认为 `nil`，即 App Hang 检测处于关闭状态**。不显式配置该参数，iOS 应用不会上报任何 App Hang 数据，分析看板中的「无响应时长率」将始终为空。
```swift theme={null}
RUM.enable(
with: RUM.Configuration(
applicationID: "",
appHangThreshold: 0.25 // 超过 250ms 的主线程阻塞会被记录
)
)
```
配置要点：
* 最小允许值为 `0.1` 秒，低于该值会被自动提升到 0.1 秒。生产环境建议 **0.25–0.5 秒**：阈值过低会产生大量噪音数据。
* SDK 以 2.5% 的容差检测，持续时间非常接近阈值的卡顿可能不会被上报。
* 需要同时开启崩溃采集，否则 App Hang 错误不会带上堆栈信息。
* 挂死到应用被系统终止的 App Hang 会被记为致命错误，计入崩溃次数并影响无崩溃率；未致命的 App Hang 只记为 `error.category = App Hang` 的错误。
* Android 侧无对应配置项：主线程冻结的判定阈值固定为 5 秒。
### 自动追踪视图
要启用视图自动追踪，在初始化 RUM 时设置 `uiKitViewsPredicate` 或 `swiftUIViewsPredicate`。
对于 **UIKit**，使用 `DefaultUIKitRUMViewsPredicate` 类：
```swift theme={null}
import DatadogRUM
RUM.enable(
with: RUM.Configuration(
applicationID: "",
uiKitViewsPredicate: DefaultUIKitRUMViewsPredicate()
)
)
```
对于 **SwiftUI**，使用 `DefaultSwiftUIRUMViewsPredicate` 类：
```swift theme={null}
import DatadogRUM
RUM.enable(
with: RUM.Configuration(
applicationID: "",
swiftUIViewsPredicate: DefaultSwiftUIRUMViewsPredicate()
)
)
```
您还可以实现自定义的 `predicate` 来自定义追踪行为。
### 自动追踪用户操作
要启用用户操作自动追踪，在初始化 RUM 时设置 `uiKitActionsPredicate` 或 `swiftUIActionsPredicate`。
对于 **UIKit**：
```swift theme={null}
import DatadogRUM
RUM.enable(
with: RUM.Configuration(
applicationID: "",
uiKitActionsPredicate: DefaultUIKitRUMActionsPredicate()
)
)
```
对于 **SwiftUI**：
```swift theme={null}
import DatadogRUM
RUM.enable(
with: RUM.Configuration(
applicationID: "",
swiftUIActionsPredicate: DefaultSwiftUIRUMActionsPredicate(isLegacyDetectionEnabled: true)
)
)
```
### 自动追踪网络请求
要启用网络请求自动追踪（资源和错误），在初始化 RUM 时设置 `urlSessionTracking` 并启用 `URLSessionInstrumentation`：
```swift theme={null}
import DatadogRUM
RUM.enable(
with: RUM.Configuration(
applicationID: "",
urlSessionTracking: RUM.Configuration.URLSessionTracking()
)
)
URLSessionInstrumentation.enable(
with: .init(
delegateClass: SessionDelegate.self
)
)
```
如需把 RUM 资源与后端 trace 关联，请配置 `firstPartyHostsTracing`，详见 [集成 RUM 与分布式追踪](#集成-rum-与分布式追踪)。
### 自动追踪错误
SDK 自动收集所有“致命”和“非致命”的 iOS 错误，并附加当前 RUM 视图的错误详情和元数据。
致命错误包括应用崩溃。非致命错误包括：
* **Swift errors**: Swift `throw` 的错误
* **Objective-C exceptions**: Objective-C 异常
您可以通过 RUM Explorer 和 Error Tracking 查看错误详情。
## 修改或丢弃 RUM 事件
在 RUM 事件发送到 Flashduty 之前，您可以通过事件映射器（Event Mappers）对其进行修改或完全丢弃。
事件映射器在创建 RUM 配置时设置：
```swift theme={null}
import DatadogRUM
let configuration = RUM.Configuration(
applicationID: "",
viewEventMapper: { RUMViewEvent in
return RUMViewEvent
},
errorEventMapper: { RUMErrorEvent in
return RUMErrorEvent
},
resourceEventMapper: { RUMResourceEvent in
return RUMResourceEvent
},
actionEventMapper: { RUMActionEvent in
return RUMActionEvent
},
longTaskEventMapper: { RUMLongTaskEvent in
return RUMLongTaskEvent
}
)
RUM.enable(with: configuration)
```
```objective-c theme={null}
@import DatadogObjc;
DDRUMConfiguration *configuration = [[DDRUMConfiguration alloc] initWithApplicationID:@""];
[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` 中使用它：
```swift theme={null}
let configuration = RUM.Configuration(
applicationID: "",
resourceEventMapper: { RUMResourceEvent in
var RUMResourceEvent = RUMResourceEvent
RUMResourceEvent.resource.url = redacted(RUMResourceEvent.resource.url)
return RUMResourceEvent
}
)
```
```objective-c theme={null}
DDRUMConfiguration *configuration = [[DDRUMConfiguration alloc] initWithApplicationID:@""];
[configuration setResourceEventMapper:^DDRUMResourceEvent * _Nullable(DDRUMResourceEvent * _Nonnull RUMResourceEvent) {
return RUMResourceEvent;
}];
```
从 error、resource 或 action 映射器返回 `nil` 将完全丢弃该事件；该事件不会发送到 Flashduty。从 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 附加到支持请求、电子邮件或错误报告中，以便您的支持团队稍后在 Flashduty 中找到用户会话。
您可以在运行时访问 RUM 会话 ID，无需等待 `sessionStarted` 事件：
```swift theme={null}
import DatadogRUM
RUMMonitor.shared().currentSessionID(completion: { sessionId in
currentSessionId = sessionId
})
```
```objective-c theme={null}
@import DatadogObjc;
[[RUMMonitor shared] currentSessionIDWithCompletion:^(NSString * _Nullable sessionId) {
// use session ID
}];
```
## 设置追踪同意（GDPR 合规）
为符合 GDPR 法规，iOS SDK 在初始化时需要追踪同意值 `trackingConsent`：
| 值 | 行为 |
| - | - |
| `.pending` | 收集并批处理数据，但不发送到 Flashduty，等待新的同意值再决定如何处理已批处理的数据 |
| `.granted` | 收集数据并发送到 Flashduty |
| `.notGranted` | 不收集任何数据，不发送日志、trace 或 RUM 事件 |
初始化后可调用 `Datadog.set(trackingConsent:)` 更改同意值，SDK 会随之调整行为。例如当前为 `.pending` 时：
* 改为 `.granted`，SDK 会发送所有当前和未来的数据；
* 改为 `.notGranted`，SDK 会清除所有当前数据，且不再收集。
```swift theme={null}
import DatadogCore
Datadog.set(trackingConsent: .granted)
```
```objective-c theme={null}
@import DatadogObjc;
[DDDatadog setWithTrackingConsent:DDTrackingConsentGranted];
```
## 数据管理
### 清除所有数据
您可以选择删除 SDK 存储的所有未发送数据，使用 `Datadog.clearAllData()` API：
```swift theme={null}
import DatadogCore
Datadog.clearAllData()
```
```objective-c theme={null}
@import DatadogObjc;
[DDDatadog clearAllData];
```
### 停止数据收集
您可以使用 `Datadog.stopInstance()` API 停止命名的 SDK 实例（如果名称为 `nil` 则停止默认实例）进一步收集和上传数据。
```swift theme={null}
import DatadogCore
Datadog.stopInstance()
```
```objective-c theme={null}
@import DatadogObjc;
[DDDatadog stopInstance];
```
调用此方法会禁用 SDK 和所有活跃的功能，如 RUM。要恢复数据收集，您必须重新初始化 SDK。如果您想动态更改配置，可以使用此 API。
## 采样
默认情况下，RUM 会收集所有会话的数据。您可以通过 `sessionSampleRate` 参数设置采样率（百分比）来减少收集的会话数量。例如，采集 90% 的会话：
```swift theme={null}
import DatadogRUM
RUM.enable(
with: RUM.Configuration(
applicationID: "",
sessionSampleRate: 90
)
)
```
```objective-c theme={null}
@import DatadogObjc;
DDRUMConfiguration *configuration = [[DDRUMConfiguration alloc] initWithApplicationID:@""];
configuration.sessionSampleRate = 90;
[RUM enableWith:configuration];
```
被采样的会话将不收集任何视图及其相关遥测数据。
## 远程配置
SDK 0.6.0 起，会话采样率可以在控制台 **应用管理 → 远程配置** 页签在线调整，无需改代码、重新发版。该功能默认关闭，需要在初始化时开启：
```swift theme={null}
import DatadogRUM
RUM.enable(
with: RUM.Configuration(
applicationID: "",
sessionSampleRate: 100, // 控制台未下发时使用的采样率
remoteConfigurationEnabled: true
)
)
```
```objective-c theme={null}
@import DatadogObjc;
DDRUMConfiguration *configuration = [[DDRUMConfiguration alloc] initWithApplicationID:@""];
configuration.remoteConfigurationEnabled = YES;
[RUM enableWith:configuration];
```
开启后的行为：
* SDK 在 `RUM.enable()` 时向 RUM 接入端点请求一次配置，之后每次新建会话时再请求。控制台发布的采样率对**下一个新会话**生效，进行中的会话不受影响。
* 下发的值会持久化到本地，冷启动后的第一个会话即按上次下发的采样率抽样。
* 请求失败、超时或响应无法识别时，沿用已生效的值，不会清空；控制台停用远程配置后，恢复使用初始化时的 `sessionSampleRate`。
* iOS SDK 只读取**会话采样率**与**自定义配置项**两项，其余配置项不生效。自定义配置项可通过 `RUMMonitor.shared().getRemoteConfig()` 读取，未开启远程配置或控制台未设置时返回 `nil`。
需要按业务规则决定采样时，可通过 `beforeSampling` 回调干预：每次新建会话时，它收到即将生效的采样率（`sessionSampleRate`）与控制台的自定义配置项（`custom`），返回新的采样率即可覆盖，返回 `nil` 表示不干预。回调在会话创建过程中同步执行，需保持轻量、不可阻塞；返回 0–100 以外的值会被忽略。
```swift theme={null}
RUM.enable(
with: RUM.Configuration(
applicationID: "",
remoteConfigurationEnabled: true,
beforeSampling: { context in
// 例如：内部账号全量采集，其余沿用控制台下发的采样率
isInternalUser ? 100 : nil
}
)
)
```
若要不受采样率限制地采集当前用户（例如排查特定用户的问题），可调用 `RUMMonitor.shared().setForcedSession()`：此后新建的会话一律采集，直到进程结束；已在进行中的会话不会被重新判定。
控制台侧的配置项、发布与生效方式见 [应用管理 · 远程配置](/zh/rum/quickstart/app-management)。
## 集成 RUM 与分布式追踪
把 iOS 应用发出的请求与对应的后端 trace 关联起来，就能在一处同时看到前端体验和后端、基础设施、日志信息，快速定位问题所在。
### 配置方法
初始化 RUM SDK，使用 `firstPartyHostsTracing` 来配置当前应用的 API 服务域名：
```swift theme={null}
import DatadogRUM
RUM.enable(
with: RUM.Configuration(
applicationID: "",
urlSessionTracking: RUM.Configuration.URLSessionTracking(
firstPartyHostsTracing: .trace(
hosts: [
"api.example.com",
"example.com"
],
sampleRate: 20
)
)
)
)
URLSessionInstrumentation.enable(
with: .init(
delegateClass: SessionDelegate.self
)
)
```
```objective-c theme={null}
@import DatadogObjc;
DDRUMConfiguration *configuration = [[DDRUMConfiguration alloc] initWithApplicationID:@""];
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`。
## 相关文档
了解如何集成 iOS SDK
了解 SDK 收集的数据类型
了解 SDK 兼容性要求
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.