跳到主要内容

鸿蒙

最近更新 2026/09/03
提示

鸿蒙 SDK 要求 DevEco Studio 4.0+，HarmonyOS API 10+；并依赖 ThinkingData Analytics SDK 1.8.1+（发布包声明依赖 1.9.0）。

最新版本：v1.0.0

更新时间：2026-07-22

资源下载：下载

1. 概述​

从 AE 4.4 版本开始，运营模块上线了“配置中心”功能，支持在 AE 后台添加功能参数配置，通过客户端 SDK 拉取至 App，精细化定制您与玩家的互动内容。

本文介绍鸿蒙端客户端 SDK（@thinkingdata/remoteconfig）的集成过程。App 端只需要关注与数数 SDK 的交互即可，不需要关心 AE 后台配置细节。API 与架构对齐 Android tdremoteconfig v1.3.0。

2. 集成​

配置中心鸿蒙 SDK 需要依赖以下 数数 SDK：

SDK 名称功能介绍版本要求
@thinkingdata/analytics实现数据采集与处理>= 1.9.0
@thinkingdata/remoteconfig拉取 AE 后台的配置信息>= 1.0.0

2.1 ohpm 安装（推荐）​

ohpm install @thinkingdata/remoteconfig
# 或
ohpm i @thinkingdata/remoteconfig

也可在宿主模块 oh-package.json5 中声明依赖后执行安装：

{
  "dependencies": {
    "@thinkingdata/remoteconfig": "1.0.0"
  }
}
ohpm install

2.2 本地 HAR 集成（开发 / 调试）​

{
  "dependencies": {
    "@thinkingdata/remoteconfig": "file:../TDRemoteConfig.har",
    "@thinkingdata/analytics": "file:../TDAnalytics.har"
  }
}
//执行
ohpm install

3. 初始化​

必须先初始化 ThinkingData Analytics SDK，再初始化 RemoteConfig。

3.1 简单初始化​

import { TDAnalytics } from '@thinkingdata/analytics';
import { TDRemoteConfig } from '@thinkingdata/remoteconfig';

// 先初始化 TA SDK
await TDAnalytics.init(context, 'YOUR_APP_ID', 'YOUR_SERVER_URL');

// 再初始化 RemoteConfig
TDRemoteConfig.enableLog(true); // 开发阶段建议开启
TDRemoteConfig.init(context, 'YOUR_APP_ID', 'YOUR_SERVER_URL');

3.2 使用 TDRemoteConfigSettings 初始化（推荐）​

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

const settings = new TDRemoteConfigSettings();
settings.appId = 'YOUR_APP_ID';
settings.serverUrl = 'YOUR_SERVER_URL';
// settings.templateCode = 'TEMPLATE_CODE'; // 多模板时指定，默认留空

// 可选：Debug 模式（跳过缓存控制，便于发送测试）
// settings.mode = TDRemoteConfigMode.DEBUG;

// 可选：初始化时携带的自定义拉取参数
settings.customFetchParams = { platform: 'harmonyos' };

// 可选：自定义分桶 ID（用于 A/B 实验）
settings.customBucketId = { experiment_key: 'bucket_a' };

// 初始化回调（init 阶段自动触发一次拉取）
settings.setFetchTask({
  onLocalCacheReady: () => {
    // 本地缓存已就绪，可安全读取上次成功的配置
  },
  onSuccess: () => {
    // 本次网络拉取成功
  },
  onFailure: (code: number, error: string) => {
    // 本次网络拉取失败
  }
});

TDRemoteConfig.init(context, settings);

回调触发时序：

  1. onLocalCacheReady()：磁盘缓存加载完成后立即触发（有缓存才触发）
  2. 随后发起网络拉取：成功走 onSuccess()，失败走 onFailure()

4. 使用​

4.1 数据结构样例​

"configId" : {
    "templateId" : [
        {
         "#strategy_id" : "2024121001",
          "paramater_x" : "1111",
          "#ops_receipt_properties" : {}
        }
    ],
    "#custom_params" : {

    }
}

其中：

  • configId：在运营后台配置中心模块创建的“配置项ID”，用于标识业务模块信息。配置项说明详见配置项管理
  • templateId：业务在“配置项”下添加的“模版ID”，用于标识具体的功能模块信息。配置模板说明详见配置模板管理
  • #strategy_id：策略的唯一ID，用于策略生命周期管理。配置策略说明见配置策略管理
  • paramater_x：配置模板参数，对应功能模块所需的配置参数
  • #ops_receipt_properties：用于事件回收统计，当你需要自动统计策略效果（暂未支持）时，回收事件需要携带此属性
  • #custom_params：客户端配置通道上的自定义参数，可定义需要携带到客户端的用户属性信息。

4.2 设置本地默认值​

您可以在 TDRemoteConfig SDK 中设置配置项默认值，在 AE 服务端未添加配置项、或者本地未拉取到远端值时，SDK 会获取到本地默认值。

直接设置​

TDRemoteConfig.setDefaultValues({
  welcome_message: 'Hello',
  max_retry: 3,
  feature_enabled: false
} as Record<string, Object>, 'YOUR_APP_ID');

清空默认值​

TDRemoteConfig.clearDefaultValues('YOUR_APP_ID');

4.3 获取值的方式​

获取配置项下某一类已经发布上线中的策略内容：

const array = TDRemoteConfig.getData()
  .get('configId')
  .get('templateId')
  .arrayValue();

也可按字段类型读取：

const data = TDRemoteConfig.getData('YOUR_APP_ID');

const welcome: string = data.get('welcome_message').stringValue();
const maxRetry: number = data.get('max_retry').numberValue();
const enabled: boolean = data.get('feature_enabled').booleanValue();
const uiConfig: Record<string, Object> = data.get('ui_config').objectValue();

其中：

取值规则​

某一个 key 的取值过程：

  • 优先取该 key 对应的远端配置的值
  • 若远端没有配置该 key，则去查找该 key 的本地默认值
  • 若本地默认值也没有该 key，返回空（对应类型的空值，不抛异常）

4.4 主动拉取​

TDRemoteConfig.fetch('YOUR_APP_ID')
  .onSuccess(() => {
    const value = TDRemoteConfig.getData('YOUR_APP_ID').get('key').stringValue();
  })
  .onFailure((code: number, error: string) => {
    // 拉取失败
  });

fetch() 受频控保护，短时间内多次调用不会重复发起网络请求。如需强制拉取，使用 TDRemoteConfigMode.DEBUG 模式初始化。

4.5 监听更新​

SDK 初始化之前或之后，均可添加配置拉取成功的通知监听：

TDRemoteConfig.addConfigFetchListener({
  onFetchSuccess: (statusData: Record<string, Object>) => {
    // 拉取配置成功
  }
});

通知名称​

onFetchSuccess（拉取配置成功）

通知携带的参数​

提示

通知将默认携带本次请求和上次请求期间，变更为暂停生效（suspend）、强制下线（force_offline）的策略状态，您可结合业务需求取用。若无需使用，可直接忽略。

使用以下方式获取通知参数：

const map = statusData['strategy_status_map'] as Record<string, Object>;

对应的 value 结构示例如下，用来描述配置项模版中策略 id 为 20241209 的策略状态：

{
  "configId" : {
    "templateId" : {
      "20241209" : "suspend"
    }
  }
}

4.6 自定义拉取参数与 Client Params​

自定义拉取参数会附加到每次拉取请求中：

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

TDRemoteConfig.removeCustomFetchParam('user_level', 'YOUR_APP_ID');

Client Params 会持久化到本地，并随每次拉取上报：

TDRemoteConfig.addClientParams({ login_count: 5, vip_level: 2 });
TDRemoteConfig.accumulateNum('launch_count', 1);
const all = TDRemoteConfig.getClientParams();
TDRemoteConfig.removeClientParam('vip_level');

4.7 账号切换​

TA SDK 的 login / logout / setDistinctId 会触发远程配置自动重拉（SDK 内部监听身份变更）。应用回前台时也会自动检测 identity 变化。

import { TDAnalytics } from '@thinkingdata/analytics';

TDAnalytics.login('user_account_id');
TDAnalytics.logout();
TDAnalytics.setDistinctId('new_distinct_id');

5. 发送测试​

为了快速验证接入可用性与配置策略有效性，SDK 支持开启测试模式。

const settings = new TDRemoteConfigSettings();
settings.mode = TDRemoteConfigMode.DEBUG;
settings.appId = 'YOUR_APP_ID';
settings.serverUrl = 'YOUR_SERVER_URL';
TDRemoteConfig.init(context, settings);

客户端开启 Debug 模式后，会按测试策略节奏拉取配置。在 AE 运营模块可以创建模版测试或者策略测试，等待拉取配置的过程中，可以关注前端页面的进度节点。

参考操作文档 配置模板管理 中的客户端发送测试部分。

客户端 SDK 发送测试需要使用测试设备，您可在测试设备列表中选择或添加测试设备。

开发阶段也可开启 SDK 日志，便于排查：

TDRemoteConfig.enableLog(true);
hdc shell hilog -T TDRemoteConfigSDK
这篇文档对你有帮助吗？
本页内容