鸿蒙

最近更新 2026/10/07

最新版本： v1.0.0

更新时间： 2026-07-24

资源下载：下载

1. 概述

从 6.1 版本开始，AE 新增实验套件功能，支持在 AE 后台创建实验，设置对照组和实验组的变量值，通过客户端 SDK 拉取至 App，为不同组别的用户展示不同的内容。

本文介绍 HarmonyOS 客户端 SDK 的集成过程，App 端只需要关注与数数 SDK 的交互即可，不需要关心 AE 后台的任务细节。

需要注意的是，实验 SDK 必须搭配配置中心 SDK 一起使用。

2. 集成

2.1 自动集成 SDK

在应用模块目录下执行：

ohpm install @thinkingdata/experiment

或使用简写：

ohpm i @thinkingdata/experiment

ohpm 会自动安装传递依赖（@thinkingdata/remoteconfig、@thinkingdata/analytics 等）。

也可在应用模块 oh-package.json5 中手动添加依赖后执行 ohpm install：

{
  "dependencies": {
    "@thinkingdata/experiment": "1.0.0"
  }
}

2.2 手动集成 SDK

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

SDK 名称	功能介绍	版本要求
TDAnalytics	实现数据采集与处理	1.9.0
TDRemoteConfig	拉取 AE 后台的配置信息	1.0.0

1. 点击页面上方资源下载链接，下载并解压，将 TDExperiment.har、TDAnalytics.har、TDRemoteConfig.har 放入应用模块 libs/ 目录
2. 在应用模块 oh-package.json5 中添加本地 HAR 依赖：

{
  "dependencies": {
    "@thinkingdata/experiment": "file:./libs/TDExperiment.har",
    "@thinkingdata/analytics": "file:./libs/TDAnalytics.har",
    "@thinkingdata/remoteconfig": "file:./libs/TDRemoteConfig.har"
  }
}

1. 执行 ohpm install 安装依赖

接入方代码中需直接 import { TDAnalytics } 并完成初始化。若 IDE 或编译无法解析 analytics 模块，请在 oh-package.json5 中额外显式声明 "@thinkingdata/analytics": "1.9.0"。

3. 初始化

实验 SDK 需要搭配分析 SDK 使用。请先完成 TDAnalytics 初始化，再初始化实验 SDK。

import { common } from '@kit.AbilityKit';
import { TDAnalytics } from '@thinkingdata/analytics';
import { TDExperiment, TDExperimentConfig } from '@thinkingdata/experiment';

const context = ... as common.UIAbilityContext;
const APP_ID = 'your_app_id';
const SERVER_URL = 'https://your-receiver-url';

// 初始化采集 SDK
TDAnalytics.init(context, APP_ID, SERVER_URL);
TDAnalytics.login('user_distinct_id');

// 初始化实验 SDK
const config = new TDExperimentConfig(APP_ID, SERVER_URL);
config.automaticExposureTracking = true;
config.customBucketId = { 'user_id': 'user_distinct_id' };
config.customFetchParams = { 'platform': 'harmonyos' };
config.initCallback = {
  onFetchSuccess: () => {
    // 拉取实验配置信息成功
  },
  onError: (code: number, message: string) => {
    // 拉取实验配置信息失败
  }
};
TDExperiment.enableLog(true);
TDExperiment.init(context, config);

初始化参数说明：

• appId：APP ID
• serverUrl：数据上报地址
• automaticExposureTracking：默认设置为 true，在 get 获取实验参数的时候自动上传曝光事件
• customBucketId：自定义分流主体
• customFetchParams：客户端配置通道上的自定义参数
• enableLog：是否开启调试日志（通过 TDExperiment.enableLog 设置）
• initCallback.onFetchSuccess：拉取实验配置信息成功
• initCallback.onError：拉取实验配置信息失败

4. 使用

4.1 获取实验信息

TDExperiment.getValueAsString(key, defaultValue);

TDExperiment.getValueAsNumber(key, defaultValue);

TDExperiment.getValueAsBoolean(key, defaultValue);

TDExperiment.getValueAsJson(key, defaultValue);

如果 automaticExposureTracking 为 true，在 get 的时候会自动上传曝光事件。

4.2 上传曝光事件

可以调用 exposure 方法，手动上传曝光事件。

TDExperiment.exposure(key);

4.3 主动拉取所有实验信息

TDExperiment.fetch();

TDExperiment.fetch().addOnSuccessListener({
  onSuccess: () => {
    // 成功
  }
}).addOnFailureListener({
  onFailure: (code: number, msg: string) => {
    // 失败
  }
});

4.4 自定义分流主体

TDExperiment.setCustomBucketId({ 'bucket_id': 'account_id' });

4.5 自定义请求参数

TDExperiment.setCustomFetchParams({ 'key': 'value' });