访客标识 Visitor ID¶

SDK 0.4.3 起支持。

Visitor ID 是由 SDK 生成并管理的匿名访客标识。启用后，可向匹配的 HTTP(S) 请求注入自定义请求头，并在 RUM 数据中关联 visitor_id；集成了相应 Web SDK 的 WebView 页面也可读取 Native 标识。

该功能默认关闭。Visitor ID 不等同于通过 bindRUMUserData() 设置的用户标识，也不能用作登录凭证或鉴权信息。SDK 自行生成标识，不支持由应用指定标识值。

初始化配置¶

先完成 SDK 初始化，再通过 FTRUMConfig.visitorIdConfig 配置并初始化 RUM：

import {
  FTMobileReactNative,
  FTReactNativeRUM,
  FTRUMConfig,
  FTVisitorIdConfig,
} from '@cloudcare/react-native-mobile';
const rumConfig: FTRUMConfig = {
  androidAppId: 'android_app_id',
  iOSAppId: 'ios_app_id',
  visitorIdConfig: {
    header: 'x-visitor-id',
    ttlHours: 24,
    urlPrefixes: ['https://api.example.com/'],
  },
};
await FTReactNativeRUM.setConfig(rumConfig);

省略 visitorIdConfig 或设置为 null 表示不启用。配置不合法时 FTReactNativeRUM.setConfig() 会返回失败的 Promise，应修正配置后再初始化。

URL 匹配与请求头注入¶

多条规则为“或”的关系，命中任意一条即可。React Native 提供 URL 前缀和正则两种匹配方式：

• URL 前缀：按完整 URL 字符串前缀匹配，同时要求协议、主机和有效端口一致。建议使用带路径分隔符的前缀，例如 https://api.example.com/orders/，避免误匹配 orders-history 等路径。
• 正则表达式：在完整 URL 中查找匹配；需要限制起点或完整匹配时，使用 ^、$。传入的是字符串，反斜杠需要转义；表达式应兼容 iOS 与 Android 的正则语法。

例如，向 /orders/ 下的请求或 /v1/、/v2/ 下的请求注入标识：

const visitorIdConfig: FTVisitorIdConfig = {
  header: 'x-visitor-id',
  urlPrefixes: ['https://api.example.com/orders/'],
  regularExpressions: ['^https://api\\.example\\.com/v[12]/'],
};
// 在 RUM 初始化前，将其赋给 rumConfig.visitorIdConfig。

FTVisitorIdConfig 与 FTRUMConfig 从同一个 React Native 主 SDK 包导入。

请求头注入适用于 SDK 已接入的 HTTP(S) 网络请求，WebSocket 请求不注入。Android 端需完成 ft-plugin 网络接入配置；使用自定义网络客户端时，也需确保该客户端已接入 SDK。

Visitor ID 请求头注入不依赖 RUM 或 Trace 是否采样命中，也不要求开启自动 Resource 采集。需要在平台查看对应 Resource 数据时，仍须开启 Resource 采集并配置相应采样。

有效期、持久化与重置¶

标识在本地持久化，存储正常且有效期未结束时，重启应用可继续使用。有效期从标识创建时开始计算，访问或读取不会延长有效期；到期后，下一次获取标识时生成新值。

卸载应用、清除应用数据等操作可能使本地标识丢失；本地存储不可用时，标识只能在当前进程内保留。Android 多进程应用中的标识按进程独立管理。

启用 Visitor ID 后，需要主动更换标识时调用：

await FTMobileReactNative.resetVisitorId();

重置会生成新的标识，后续请求和读取使用新值。已缓存的数据和已发起请求中的标识不会被追溯替换。

WebView 共享¶

Web 页面需集成支持通过 Native Bridge 获取 Visitor ID 的 Web SDK，并完成 WebView 接入。配置有效的 visitorIdConfig 后，Web SDK 可读取当前 Native 标识；未启用 Visitor ID 时，不会返回 Native 标识。

两类规则分别控制不同范围：

• visitorIdConfig.urlPrefixes、regularExpressions 控制业务 HTTP(S) 请求是否注入 Visitor ID 请求头。
• React Native 的 FTMobileConfig.allowWebViewHost 配置 WebView host 范围，供支持该能力的 Web SDK 在读取 Native 标识时使用，详见 WebView host 配置。iOS 还限制为主 frame 读取。

在 SDK 初始化时配置 FTMobileConfig.allowWebViewHost，并在 SDK 和 RUM 初始化完成后加载 WebView 页面。仅设置请求 URL 匹配规则不会自动限制 WebView 页面范围。TTL 到期或重置后，后续读取使用新的当前标识，Web 侧不应永久缓存旧值。