跳转至

动态配置与动态更新地址

远程配置

通过远程配置获取平台下发的环境变量,调整 SDK 采集配置。可以在 SDK 初始化时注册统一回调,也可以在业务需要时主动拉取,并在配置应用前进行自定义处理。

使用前提

在 FTSdk.install(sdkConfig) 前,通过 FTSDKConfig.setRemoteConfiguration(true) 开启远程配置,并设置有效的上报地址。随后初始化 RUM,使用 FTRUMConfig.setRumAppId(...) 指定要拉取配置的应用。完整接入步骤见 SDK 初始化 和 RUM 配置。

远程采样配置作用于已接入的模块;日志和链路采集仍需完成各自的初始化。

更新方式

更新方式 最小更新间隔 回调
RUM 初始化、应用回到前台时自动尝试更新 setRemoteConfigMiniUpdateInterval,默认 12 小时 初始化时注册的全局回调
FTSdk.updateRemoteConfig() 使用初始化时设置的间隔 全局回调
FTSdk.updateRemoteConfig(interval, result) 使用本次传入的 interval,单位秒,取值为非负整数;0 跳过间隔检查 非空 result 优先,否则使用全局回调

最小更新间隔用于限制请求频次,SDK 不会每隔 12 小时定时刷新,重启应用也不会重置已保存的请求时间。主动更新是异步请求;传入 0 仍需满足初始化条件,已有请求执行时会跳过本次调用。

回调与自定义配置

ft-sdk >= 1.6.16 支持通过 FetchResult.onConfigSuccessFetched 自定义调整远程配置。

FETCH_RESULT 中两个方法的职责如下:

方法 调用时机与用途
onConfigSuccessFetched(configBean, jsonConfig) 获取到有效且发生变化的远程配置后,在应用配置前调用。jsonConfig 是响应中 content 对应的 JSON,可解析自定义字段并返回修改后的 configBean;返回 null 时沿用传入的对象。
onResult(success) 返回本次更新结果:true 表示配置已应用或远程内容未变化;false 表示更新失败、缺少 RUM App ID 或未达到最小间隔等。

本次传入的非空回调会替代全局回调,两者不会同时执行。SDK 未初始化、未开启远程配置或已有请求执行时,主动调用可能不会收到回调。回调不保证在主线程执行,更新 UI 时需切换到主线程。

最终配置会应用并写入本地缓存。远程内容未变化时,仅执行 onResult(true),即使主动更新传入 0,也不会重新执行 onConfigSuccessFetched;本地用户或业务条件变化不会自动触发配置重算。

代码示例

以下采样 setter 需 ft-sdk >= 1.7.6,取值范围为 [0,100],支持小数;旧采样方法保留 [0,1] 单位。字段与兼容说明见环境变量。

示例省略 sdkConfig、rumConfig 的创建,将回调保存在初始化与业务刷新都能访问的位置。两个场景分时执行:启动时注册回调,后续在业务触发点主动更新。

custom_userid 是远程下发的自定义字段。示例在该字段匹配时,将三项采样率设为 100%;按当前登录用户调整时,还需结合业务侧用户 ID,并处理用户切换后的配置恢复。

// 核心:自定义远程配置回调,初始化和主动更新共用。
final FTRemoteConfigManager.FetchResult FETCH_RESULT =
        new FTRemoteConfigManager.FetchResult() {
            @Override
            public RemoteConfigBean onConfigSuccessFetched(
                    RemoteConfigBean configBean, String jsonConfig) {
                // 远程配置应用前,可解析自定义字段并覆盖配置。
                try {
                    JSONObject json = new JSONObject(jsonConfig);
                    String userId = json.optString("custom_userid", "");

                    if ("custom_user_test6".equals(userId)) {
                        // 采样率范围:0~100,100f 表示 100%。
                        configBean.setSessionSamplingRate(100f);
                        configBean.setLogSamplingRate(100f);
                        configBean.setTraceSamplingRate(100f);
                    }
                } catch (JSONException e) {
                    // 自定义解析失败时,保留原配置。
                }
                return configBean;
            }

            @Override
            public void onResult(boolean success) {
                // true:更新成功或配置未变化。
                // false:更新失败或未达到最小更新间隔等。
            }
        };

// 场景一:SDK / RUM 初始化时,开启远程配置并注册回调。
sdkConfig.setRemoteConfiguration(true)
        .setRemoteConfigurationCallBack(FETCH_RESULT);
FTSdk.install(sdkConfig);
FTSdk.initRUMWithConfig(rumConfig); // 使用已有 RUM 配置,包含 RUM App ID。

// 场景二:后续业务中按需主动更新,0 表示忽略最小更新间隔。
// 配置未变化时,仅回调 onResult(true),不会再次执行自定义解析。
FTSdk.updateRemoteConfig(0, FETCH_RESULT);
// 核心:自定义远程配置回调,初始化和主动更新共用。
val FETCH_RESULT = object : FTRemoteConfigManager.FetchResult() {
    override fun onConfigSuccessFetched(
        configBean: RemoteConfigBean,
        jsonConfig: String
    ): RemoteConfigBean {
        // 远程配置应用前,可解析自定义字段并覆盖配置。
        try {
            val json = JSONObject(jsonConfig)
            val userId = json.optString("custom_userid", "")

            if (userId == "custom_user_test6") {
                // 采样率范围:0~100,100f 表示 100%。
                configBean.setSessionSamplingRate(100f)
                configBean.setLogSamplingRate(100f)
                configBean.setTraceSamplingRate(100f)
            }
        } catch (e: JSONException) {
            // 自定义解析失败时,保留原配置。
        }
        return configBean
    }

    override fun onResult(success: Boolean) {
        // true:更新成功或配置未变化。
        // false:更新失败或未达到最小更新间隔等。
    }
}

// 场景一:SDK / RUM 初始化时,开启远程配置并注册回调。
sdkConfig.setRemoteConfiguration(true)
    .setRemoteConfigurationCallBack(FETCH_RESULT)
FTSdk.install(sdkConfig)
FTSdk.initRUMWithConfig(rumConfig) // 使用已有 RUM 配置,包含 RUM App ID。

// 场景二:后续业务中按需主动更新,0 表示忽略最小更新间隔。
// 配置未变化时,仅回调 onResult(true),不会再次执行自定义解析。
FTSdk.updateRemoteConfig(0, FETCH_RESULT)

动态开启和关闭获取 AndroidID

使用 FTSdk 设置是否在 SDK 中获取 Android ID。

FTSdk.setEnableAccessAndroidID(true);
FTSdk.setEnableAccessAndroidID(false);
FTSdk.setEnableAccessAndroidID(true)
FTSdk.setEnableAccessAndroidID(false)

动态更新上报地址

使用 FTSdk 在 SDK 运行时动态切换数据上报地址。设置成功后,后续数据会按新的地址继续上传。

ft-sdk >= 1.6.17 支持。 setDatakitUrl 与 setDatawayUrl 二选一使用。 使用 setDatawayUrl 时,需要同时传入新的 clientToken。

使用场景说明

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

当后续调用 FTSdk.setDatakitUrl(...) 或 FTSdk.setDatawayUrl(..., ...) 动态设置上报地址后,SDK 会开始消费本地缓存并执行数据上报。

需要注意的是,未设置上传地址期间,采集到的数据仍然会受到本地缓存上限限制。缓存上限主要受以下配置共同影响:

  • FTLoggerConfig.setLogCacheLimitCount
  • FTRUMConfig.setRumCacheLimitCount
  • FTSDKConfig.enableLimitWithCacheSize 对应的总缓存大小上限

如果缓存达到上限,超出部分的数据可能被丢弃,因此建议在该模式下尽快补充上传地址,或结合业务场景合理设置缓存限制。

FTSdk.setDatakitUrl("http://10.0.0.1:9529");
FTSdk.setDatawayUrl("https://open.dataway.url", "your-client-token");
FTSdk.setDatakitUrl("http://10.0.0.1:9529")
FTSdk.setDatawayUrl("https://open.dataway.url", "your-client-token")
方法名 类型 必须 含义
setDatakitUrl String 是 动态设置 Datakit 上报地址,设置成功后 SDK 会继续向新的 Datakit 地址上传数据。
setDatawayUrl String, String 是 动态设置 Dataway 上报地址和 clientToken,设置成功后 SDK 会继续向新的 Dataway 地址上传数据。

文档评价

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