访客标识 Visitor ID¶

SDK 1.6.8 及以上支持由 SDK 生成并管理匿名访客标识（Visitor ID）。启用后，可向匹配的 URLSession 请求注入自定义请求头，并在 Native RUM 中关联 visitor_id；支持 Native Bridge 的 Web SDK 还可在允许的 WebView 页面中读取当前标识。

该能力默认关闭。Visitor ID 不等同于通过用户绑定 API 设置的 user_id，也不能用作登录凭证或鉴权信息。

初始化配置¶

先完成 SDK 初始化，再将有效的 FTVisitorIDConfig 设置到 FTRumConfig.visitorIDConfig，并启动 RUM。配置需要在 RUM 初始化前完成。

Objective-CSwift

#import <GuanceSDK/GuanceSDK.h>


FTRumConfig *rumConfig = [[FTRumConfig alloc] initWithAppid:appid];
FTVisitorIDConfig *visitorConfig = [[FTVisitorIDConfig alloc] init];
visitorConfig.header = @"x-visitor-id";
visitorConfig.ttlHours = 24;
[visitorConfig addMatchWithURLPrefix:@"https://api.example.com/"];
rumConfig.visitorIDConfig = visitorConfig;
[[FTSDKAgent sharedInstance] startRumWithConfigOptions:rumConfig];

import GuanceSDK


let rumConfig = FTRumConfig(appid: appid)
let visitorConfig = FTVisitorIDConfig()
visitorConfig.header = "x-visitor-id"
visitorConfig.ttlHours = 24
visitorConfig.addMatch(urlPrefix: "https://api.example.com/")
rumConfig.visitorIDConfig = visitorConfig
FTSDKAgent.sharedInstance().startRum(withConfigOptions: rumConfig)

配置	类型	默认值	说明
`FTRumConfig.visitorIDConfig`	`FTVisitorIDConfig`	`nil`	不配置时关闭 Visitor ID。配置无效时也不启用该功能
`FTVisitorIDConfig.header`	`NSString`	`nil`	必填，自定义的小写 HTTP 请求头名称，如 `x-visitor-id`。不能占用认证、Cookie、签名、CSRF 或 Trace 等保留请求头
`FTVisitorIDConfig.ttlHours`	`NSTimeInterval`	`24`	固定有效期，单位小时，必须为正的有限数值。读取不会延长有效期

还必须添加至少一条有效的 URL 匹配规则。SDK 自行生成标识，不支持由应用传入自定义标识值。

URL 匹配与请求头注入¶

规则只匹配 HTTP(S) URL。多条规则为“或”的关系，命中任意一条即可；规则抛出异常时按未命中处理。

方法	规则
`addMatchWithURLPrefix:` / Swift `addMatch(urlPrefix:)`	匹配完整 URL 字符串前缀，同时要求 scheme、host、有效端口一致。建议为业务 API 使用带路径分隔符的前缀
`addMatchWithRegularExpression:` / Swift `addMatch(regularExpression:)`	在完整 URL 字符串中进行正则匹配。需要完整匹配时使用 `^` 与 `$`
`addMatchWithHandler:` / Swift `addMatch(handler:)`	自定义 URL 判断；返回 `YES` / `true` 表示命中。回调应快速、线程安全，避免网络、磁盘操作或同步等待

Objective-CSwift

NSRegularExpression *expression = [NSRegularExpression
    regularExpressionWithPattern:@"^https://api\\.example\\.com/v[12]/"
    options:0 error:nil];
[visitorConfig addMatchWithRegularExpression:expression];
[visitorConfig addMatchWithHandler:^BOOL(NSURL *url) {
    return [url.host isEqualToString:@"checkout.example.com"];
}];

let expression = try NSRegularExpression(pattern: #"^https://api\.example\.com/v[12]/"#)
visitorConfig.addMatch(regularExpression: expression)
visitorConfig.addMatch { url in
    url.host == "checkout.example.com"
}

将这些规则加到配置对象后，再赋给 rumConfig.visitorIDConfig 并启动 RUM。

注入范围是匹配的 URLSession data、upload、download 请求，不代表对进程内所有网络协议进行注入。该功能不依赖 RUM 或 Trace 的采样是否命中，也不要求开启自动 Resource 采集；需要观察对应 Resource 事件时，仍须配置 Resource 采集与采样。

有效期、持久化与重置¶

标识在本地持久化，有效期内重启应用可继续使用。有效期从标识创建时开始计算，不会因访问而滑动续期；到期后，下一次获取标识时会生成新值。卸载应用、清除应用数据等操作可能使本地标识丢失。

需要主动轮换标识时调用：

Objective-CSwift

[FTSDKAgent resetVisitorID];

FTSDKAgent.resetVisitorID()

启用时重置会生成新标识；关闭时重置只清除本地记录。已产生事件及已发起请求保留其发生时捕获的标识，不因后续重置或过期被追溯替换。

WebView 共享¶

Web 页面需要集成支持通过 Native Bridge 获取 Visitor ID 的 Web SDK，且允许建立 WebView Bridge。当前标识按读取时的 Native 状态返回，重置或 TTL 到期后可读取新值。

URL 匹配规则控制 URLSession 请求是否注入请求头。
FTSDKConfig.allowWebViewHost 控制 哪些 WebView 页面可使用自动 Bridge 及读取 Native Visitor ID，与请求 URL 规则分别配置。
Visitor ID 读取只允许主 frame；未启用、配置无效或 host 不允许时不会返回 Native 标识。

在 SDK 初始化前设置 WebView 白名单，示例见 WebView 数据监测。仅配置 Visitor ID 的请求 URL 规则，不会自动限制 WebView 的 host 范围。

访客标识 Visitor ID¶

初始化配置¶

URL 匹配与请求头注入¶

有效期、持久化与重置¶

WebView 共享¶

文档内容是否对您有帮助？ ×

文档内容是否对您有帮助？