访客标识 Visitor ID¶

ft-sdk >= 1.7.6-alpha04 支持通过 FTRUMConfig.setVisitorIdConfig(...) 开启匿名访客标识：为匹配 URL 的 OkHttp HTTP/HTTPS 请求注入指定 Header，并为原生 RUM 数据关联 visitor_id。该标识不用于登录认证，不替代 bindRumUserData 设置的用户信息。

初始化配置¶

完成 SDK 基础初始化后，在创建业务 OkHttpClient 前配置 Visitor ID。以下示例仅允许向 https://api.example.com/v1/ 前缀对应的业务接口注入 Header，请替换为实际业务地址：

FTVisitorIdConfig visitorIdConfig = new FTVisitorIdConfig()
    .setHeader("x-visitor-id")
    .setTtlHours(24)
    .addMatch("https://api.example.com/v1/");

FTSdk.initRUMWithConfig(new FTRUMConfig()
    .setRumAppId(RUM_APP_ID)
    .setVisitorIdConfig(visitorIdConfig));

val visitorIdConfig = FTVisitorIdConfig()
    .setHeader("x-visitor-id")
    .setTtlHours(24.0)
    .addMatch("https://api.example.com/v1/")

FTSdk.initRUMWithConfig(
    FTRUMConfig()
        .setRumAppId(RUM_APP_ID)
        .setVisitorIdConfig(visitorIdConfig)
)

不设置或传入 null 时关闭此能力，无需额外开启开关。配置在 initRUMWithConfig 时校验并保存副本，之后修改原配置对象不会更新已生效的配置。Header、有效期或匹配规则校验失败时，SDK 输出错误日志并关闭 Visitor ID。

addMatch 支持以下三种规则：

• 字符串：匹配完整 URL 前缀，同时要求协议、主机和有效端口相同。例如 https://api.example.com/v1/ 不会匹配其他域名或 HTTP 地址。
• java.util.regex.Pattern：对完整 URL 执行 matcher.find()。如需限定协议、域名和路径，请在表达式中显式约束范围。
• FTVisitorIdConfig.UrlMatcher：通过 matches(String url) 返回是否匹配。回调可能并发执行，应保证线程安全并避免耗时操作；抛出运行时异常时，该条规则按不匹配处理。

OkHttp 接入与注入范围¶

使用 ft-plugin 自动插桩时，完成上述初始化后，经插桩的 OkHttpClient.Builder.build() 会安装 Visitor ID 拦截器。已经创建的 Client 不会自动补装；未使用插件或调用点未被插桩时，请按 手动接入 Visitor ID 配置。

• Header 注入独立于 setEnableTraceUserResource、RUM 采样和 Trace 采样；仅开启 Visitor ID 不会自动开启 Resource 或 Trace 采集。
• 匹配请求中若已有同名 Header，SDK 会用自己管理的 Visitor ID 覆盖，并输出警告日志。
• SDK 上报地址，以及 setResourceUrlHandler 中 isInTakeUrl 返回 true 的地址，不注入 Visitor ID Header。
• 重定向或重试会重新判断目标地址；目标不匹配时移除 SDK 已注入的 Header，匹配时继续使用该请求开始时的 ID。
• 原生 Header 注入适用于 OkHttp HTTP/HTTPS 请求，不覆盖 WebSocket 握手、HttpURLConnection / HttpsURLConnection 或 WebView 内的网络请求。

有效期与重置¶

Visitor ID 按进程独立保存到本地 SharedPreferences，在有效期内重启同一进程可复用；多进程之间不共享。持久化失败时使用内存中的稳定 ID，直到到期或主动重置。到期后的下一次读取会生成新 ID。

业务确认退出登录或切换账号后，可主动重置：

FTSdk.resetVisitorId();

FTSdk.resetVisitorId()

重置会立即生成新 ID 并重新计算有效期，不改变绑定用户、RUM Session、Trace ID 或采样配置；未开启 Visitor ID 时调用无效。不要仅因 HTTP 401 或普通请求失败而自动重置。已开始的 OkHttp 请求及其关联的 Resource、网络 Error 保留请求开始时的 ID。

HttpURLConnection / HttpsURLConnection 不注入 Visitor ID Header，其 Resource、网络 Error 沿用原生 RUM 的事件级 visitor_id，在事件生成时取值，不绑定请求开始时的 ID。上报中存在 visitor_id 不代表业务请求发送了同名 Header。

原生 RUM 的 visitor_id 由 SDK 管理，普通全局属性或事件属性不能覆盖；最终的 DataModifier / LineDataModifier 仍可修改或移除上报字段。WebView RUM 数据保留 Browser SDK 自己的 Visitor ID，不会被原生上下文覆盖。