动态配置与动态更新地址¶

开启动态配置¶

动态配置默认关闭。开启后，SDK 会在安装时读取本地缓存；当 RUM 配置已安装且存在有效上报地址时，SDK 使用 RUM 应用 ID 获取服务端配置。若上报地址在运行时才设置，SDK 会在地址有效后继续获取动态配置。

import {
  FTSDK,
  FTSDKConfig,
  FTRUMConfig,
  FTRemoteConfigFetchResult,
  RemoteConfigBean
} from '@guancecloud/ft_sdk/Index';

const remoteConfigResult: FTRemoteConfigFetchResult = {
  // 服务端返回有效且发生变化的配置时调用。
  onConfigSuccessFetched(configBean: RemoteConfigBean, jsonConfig: string): RemoteConfigBean | null {
    // 可根据 jsonConfig 解析自定义环境变量，并返回修改后的配置。
    return configBean;
  },
  // 成功获取或服务端配置未变化时为 true；请求失败或未满足刷新间隔时为 false。
  onResult(success: boolean): void {
    // 按需记录获取结果
  }
};

const sdkConfig = FTSDKConfig.builder()
  .setRemoteConfiguration(true)
  .setRemoteConfigMiniUpdateInterval(43200)
  .setRemoteConfigurationCallBack(remoteConfigResult);

FTSDK.install(sdkConfig, this.context);
FTSDK.installRUMConfig(new FTRUMConfig().setRumAppId('your-rum-app-id'));

方法	类型	默认值	说明
`setRemoteConfiguration`	`boolean`	`false`	是否开启动态配置
`setRemoteConfigMiniUpdateInterval`	`number`	`43200`	最小获取间隔，单位秒。小数向下取整，负数按 `0` 处理；传入 `0` 可用于立即刷新
`setRemoteConfigurationCallBack`	`FTRemoteConfigFetchResult \\| null`	`null`	设置获取结果回调。`onConfigSuccessFetched` 可返回修改后的 `RemoteConfigBean`，`onResult` 用于接收结果

本地缓存会在各配置安装前合并：基础 SDK 支持环境、服务名和上传相关配置；RUM 支持采样率、自动采集开关和 WebView Host 白名单；Log 支持采样率、等级和开关；Trace 支持采样率、自动追踪和类型。在线获取到新配置后，只有上传开关与参数、Log 配置、Trace 采样率，以及 RUM 采样率和错误采样率会立即生效；其他配置会在下次初始化时生效。

主动同步动态配置¶

使用 FTSDK 主动同步动态配置。在自动更新不满足需求时，可通过主动调用调整更新时机。

/**
 * 主动更新远程配置，调用频次受 FTSDKConfig.setRemoteConfigMiniUpdateInterval 影响。
 */
FTSDK.updateRemoteConfig();

/**
 * 主动更新远程配置，使用指定的最小更新间隔。
 * 传入 0 时立即请求。
 *
 * @param intervalSeconds 最小更新间隔，单位秒；负数按 0 处理。
 * @param result 获取结果回调，可覆盖初始化时的回调。
 */
FTSDK.updateRemoteConfig(intervalSeconds, result);

代码示例¶

import {
  FTSDK,
  FTRemoteConfigFetchResult,
  RemoteConfigBean
} from '@guancecloud/ft_sdk/Index';

const result: FTRemoteConfigFetchResult = {
  onResult(success: boolean): void {
    // 获取成功、服务端配置未变化时为 true。
  },
  onConfigSuccessFetched(configBean: RemoteConfigBean, jsonConfig: string): RemoteConfigBean | null {
    // 可选扩展：根据 jsonConfig 解析自定义环境变量，并修改 configBean。
    return configBean;
  }
};

// 传入 0 可立即请求，并使用本次回调覆盖初始化时的回调。
FTSDK.updateRemoteConfig(0, result);

动态开启和关闭设备标识¶

使用 FTSDK 设置是否在 SDK 中获取系统设备标识。默认使用 SDK 持久化的隐私 UUID 作为 device_uuid；开启后，SDK 优先获取 ODID，ODID 不可用时回退到 UDID，仍不可用时使用隐私 UUID。

// 开启系统设备标识访问
FTSDK.setEnableAccessDeviceID(true);

// 切回 SDK 隐私 UUID
FTSDK.setEnableAccessDeviceID(false);

动态更新上报地址¶

使用 FTSDK 在 SDK 运行时动态切换数据上报地址。请在 FTSDK.install(...) 完成后调用；设置成功后，后续数据会按新的地址继续上传。

setDatakitUrl 与 setDatawayUrl 二选一使用。使用 setDatawayUrl 时，需要同时传入新的 clientToken。

使用场景说明¶

FTSDKConfig.builder() 支持初始化时不传入 datakitUrl 或 datawayUrl。在这种场景下，SDK 会先执行数据采集，但不会上传数据。

后续调用 FTSDK.setDatakitUrl(...) 或 FTSDK.setDatawayUrl(..., ...) 设置完整且有效的 HTTP(S) 上报地址后，SDK 会开始消费本地缓存并恢复自动上传；DataWay 模式还需要有效的客户端 Token。相对路径、非 HTTP(S) 协议或格式错误的地址不会恢复自动上传；如需立即请求上传，可调用 FTSDK.flushSyncData()。

如果已开启动态配置，切换到有效上报地址后，SDK 会立即从新地址刷新远程配置；旧地址的进行中请求结果会被忽略。如果已开启黑名单过滤，SDK 会清除旧地址的远程规则，并立即从新地址重新拉取；本地规则会继续保留。

运行时设置的地址仅保存在内存中，应用重启后需要再次设置。若要在 SDK 安装前设置上报地址，可在 FTSDKConfig.builder() 返回的配置对象上调用 setDatakitUrl(...) 或 setDatawayUrl(...)，详见 SDK 初始化。

未设置上传地址期间，采集到的数据仍受本地缓存上限限制。缓存达到上限后，超出的数据可能被丢弃，因此建议尽快补充上报地址，并结合业务场景合理设置缓存限制。

import { FTSDK } from '@guancecloud/ft_sdk/Index';

// 使用 DataKit 上报
FTSDK.setDatakitUrl('http://10.0.0.1:9529');

// 或使用 DataWay 上报
FTSDK.setDatawayUrl('https://open.dataway.url', 'your-client-token');

方法名	类型	必须	含义
`setDatakitUrl`	`string`	是	在 `FTSDK.install(...)` 后动态设置 DataKit 上报地址；设置成功后，SDK 会继续向新的 DataKit 地址上传数据
`setDatawayUrl`	`string, string`	是	在 `FTSDK.install(...)` 后动态设置 DataWay 上报地址和 `clientToken`；设置成功后，SDK 会继续向新的 DataWay 地址上传数据