进阶指南

最近更新 2026/09/03

1. 初始化参数

鸿蒙端 RemoteConfig 通过 TDRemoteConfigSettings 完成初始化（与 Analytics SDK 的初始化配置相互独立）。详细字段如下：

1.1 TDRemoteConfigSettings

属性名 / 方法	类型	说明
appId	string	在 AE 后台创建的项目的 app id（必填）
serverUrl	string	在 AE 后台创建的项目的 server url（必填）
templateCode	string	模板 code；不传时 SDK 内部使用默认模板
mode	TDRemoteConfigMode	SDK 运行模式枚举，默认 NORMAL
customFetchParams	Record<string, Object>	初始化时携带的自定义拉取参数（等同于 Fetch 参数）
customBucketId	Record<string, string>	自定义分桶 ID（用于 A/B 实验强制覆盖）
setFetchTask(callbacks)	—	注册 init 阶段拉取回调（onLocalCacheReady / onSuccess / onFailure）

日志开关不在 Settings 内，请使用：

TDRemoteConfig.enableLog(true);

示例：

import {
  TDRemoteConfig,
  TDRemoteConfigSettings,
  TDRemoteConfigMode
} from '@thinkingdata/remoteconfig';

const settings = new TDRemoteConfigSettings();
settings.appId = 'YOUR_APP_ID';
settings.serverUrl = 'YOUR_SERVER_URL';
settings.mode = TDRemoteConfigMode.NORMAL;
settings.customFetchParams = { platform: 'harmonyos' };
settings.setFetchTask({
  onLocalCacheReady: () => {},
  onSuccess: () => {},
  onFailure: (code, error) => {}
});
TDRemoteConfig.init(context, settings);

1.2 TDRemoteConfigMode

枚举值	说明
NORMAL	正常模式。按缓存与过期策略拉取配置，并入库本地。
DEBUG	Debug 模式。便于发送测试 / 强制更频繁地拉取配置。设备需加入 AE 控制台的测试设备列表；可在运营后台关注测试进度节点。

说明：鸿蒙 RemoteConfig 仅提供 NORMAL / DEBUG，不包含 Analytics 侧的 DEBUG_ONLY。采集相关 Debug 模式请在 Analytics SDK 中单独配置。

2. 自定义拉取时机

2.1 自动拉取

在以下场景，SDK 会自动拉取远端配置数据：

• App 冷启动（TDRemoteConfig.init 后触发首次拉取）
• App 前后台切换，且本地配置已过期（过期时间由服务端 expirationPeriod 下发，缺省为 12 小时）
• ThinkingData Analytics 账号系统发生变更，例如 login、logout、setDistinctId
• 网络从不可用恢复为可用时补拉
• 定时器巡检：普通模式约 30s 检查一次是否过期；Debug 模式约 5s 拉取一次

2.2 手动拉取

手动调用 SDK 方法，随时拉取远端配置：

TDRemoteConfig.fetch();

链式回调示例：

TDRemoteConfig.fetch()
  .onSuccess(() => {
    // 配置已更新
  })
  .onFailure((code: number, error: string) => {
    // 拉取失败
  });

该 API 内部有频控限制，请避免频繁拉取。如需强制更积极地拉取，可使用 TDRemoteConfigMode.DEBUG 初始化。

3. 自定义 Fetch 参数

Fetch 参数为客户端 SDK 请求 AE 服务端取值时可用的参数。您可自定义 Fetch 参数，将参数添加为配置通道的环境参数，即可在配置策略时，使用 Fetch 参数自定义目标受众环境。

3.1 添加

TDRemoteConfig.setCustomFetchParams({
  user_level: 'vip',
  region: 'cn'
});

也可在初始化时通过 Settings 设置：

settings.customFetchParams = {
  user_level: 'vip',
  region: 'cn'
};

3.2 删除

根据指定的 key 进行删除：

TDRemoteConfig.removeCustomFetchParam('user_level');

3.3 自定义分桶 ID（可选）

用于 A/B 实验分组强制覆盖：

TDRemoteConfig.setCustomBucketId({
  experiment_key: 'bucket_b'
});