动态配置与动态更新地址¶
远程配置¶
通过远程配置获取平台下发的环境变量,调整 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 在 SDK 运行时动态切换数据上报地址。设置成功后,后续数据会按新的地址继续上传。
ft-sdk >= 1.6.17 支持。
setDatakitUrl与setDatawayUrl二选一使用。 使用setDatawayUrl时,需要同时传入新的clientToken。
使用场景说明¶
FTSDKConfig.builder() 支持初始化时不传入 datakitUrl 或 datawayUrl。在这种场景下,SDK 会先执行数据采集,但不会进行上传。
当后续调用 FTSdk.setDatakitUrl(...) 或 FTSdk.setDatawayUrl(..., ...) 动态设置上报地址后,SDK 会开始消费本地缓存并执行数据上报。
需要注意的是,未设置上传地址期间,采集到的数据仍然会受到本地缓存上限限制。缓存上限主要受以下配置共同影响:
FTLoggerConfig.setLogCacheLimitCountFTRUMConfig.setRumCacheLimitCountFTSDKConfig.enableLimitWithCacheSize对应的总缓存大小上限
如果缓存达到上限,超出部分的数据可能被丢弃,因此建议在该模式下尽快补充上传地址,或结合业务场景合理设置缓存限制。
| 方法名 | 类型 | 必须 | 含义 |
|---|---|---|---|
| setDatakitUrl | String | 是 | 动态设置 Datakit 上报地址,设置成功后 SDK 会继续向新的 Datakit 地址上传数据。 |
| setDatawayUrl | String, String | 是 | 动态设置 Dataway 上报地址和 clientToken,设置成功后 SDK 会继续向新的 Dataway 地址上传数据。 |