版本要求
- A/B Testing HarmonyOS SDK 依赖神策 HarmonyOS Analytics SDK v0.0.5 及以上版本,在使用前请确保已经成功集成神策分析 SDK,并进行了 SDK 初始化,详情可参考 集成文档(HarmonyOS SDK)
- A/B Testing HarmonyOS SDK 依赖 A/B Testing 0.9.1 及以上版本,版本问题可咨询技术顾问
SDK 集成
方式一:在 IDE 控制台按照以下命令行完成 SDK 的安装
将 SensorsABTesting.har 拷贝到鸿蒙项目工程目录下,运行以下命令:
(请先咨询技术顾问同学,获取 HarmoyOS SDK 最新安装包 SensorsABTesting.har)
ohpm install SensorsABTesting.har
方式二:参考如下配置,在 oh-package.json5 文件中添加依赖指向 SensorsABTesting.har 文件放置的位置,然后点击同步或执行 「ohpm install」 命令。
(请先咨询技术顾问同学,获取 HarmoyOS SDK 最新安装包 SensorsABTesting.har)
{
"license": "",
"devDependencies": {},
"author": "",
"name": "sdkdemo",
"description": "Please describe the basic information.",
"main": "",
"version": "1.0.0",
"dependencies": {
"@sensorsdata/abtesting": "file:./src/main/SensorsABTesting.har"
},
"dynamicDependencies": {}
}
初始化 SDK
在神策分析中创建 A/B Testing 后,会生成分流试验请求 URL,通过该 URL 初始化 A/B Testing SDK:
import { SensorsABTest, SensorsABTestConfigOptions } from '@sensorsdata/abtesting';
// 必须先初始化神策分析 SDK
// A/B Testing SDK 初始化(试验上线前,请检查试验的分流服务的 url 是否正确)
let config: SensorsABTestConfigOptions = new SensorsABTestConfigOptions("分流地址 URL");
// context 为当前 App 的 UIAbilityContext,内部存储等 API 需要使用
SensorsABTest.start(config, this.context);
获取试验变量
初始化 SDK 之后,通过 API 获取具体试验的变量值,根据获取试验变量值的方式,可分为下面三种策略:
- fetchCacheABTest:读取本地缓存,缓存不存在时使用默认值
- asyncFetchABTest:忽略本地缓存,从服务端获取数据
- fastFetchABTest:优先读取本地缓存,缓存不存在时从服务端获取数据
如何确定应该选择哪个API获取试验变量值?
1.一般情况下,我们推荐使用 fastFetchABTest 获取试验变量值。
2.如果您对性能有要求,可以使用 fetchCacheABTest, 只从本地缓存中获取变量值,但可能导致用户无法及时命中最新的试验。
3.如果您进行时间片轮转试验,且对时效性有要求,可以使用 asyncFetchABTest 获取试验变量值,但会存在一定的网络延迟。
1. 请确保对A/B分流返回的 result 结果 & 接口中使用的默认值,都做了正常的业务逻辑处理!
2. 请确保默认值 default_value 和当前试验值类型相同。比如参数对应试验值为 Int 类型,则传入的 default_value 也必须是 Int 类型,同时返回的试验结果 result 也是 Int 类型
以 fastFetchABTest 为例,可在相应的业务逻辑中添加如下代码:
import { SensorsABTest } from '@sensorsdata/abtesting';
// Integer 类型试验(第二个参数 0,表示未命中试验时,会返回此默认值,请根据业务需要更改此处的值)
SensorsABTest.sharedInstance.fastFetchABTest('device_index', 0, (value) => {
if (typeof value === 'number') {
const integerResult: number = value;
// TODO 请根据 integerResult 进行自己的试验,当前试验对照组返回值为:0,试验组依次返回:1, 2, 3
}
});
携带自定义属性获取试验变量
神策 A/BTesting HarmonyOS SDK 支持自定义属性扩充受众筛选能力,可以在初始化 SDK 后,通过 API 添加自定义属性获取具体试验的变量值,根据获取试验变量值的方式,可分为下面 2 种策略:
- asyncFetchABTest:忽略本地缓存,从服务端获取数据
- fastFetchABTest:优先读取本地缓存,缓存不存在时从服务端获取数据
以 fastFetchABTest 为例,可在相应的业务逻辑中添加如下代码:
import { SensorsABTest, SensorsABTestExperiment } from '@sensorsdata/abtesting';
// Integer 类型试验(第二个参数 0,表示未命中试验时,会返回此默认值,请根据业务需要更改此处的值
let experiment: SensorsABTestExperiment = new SensorsABTestExperiment('property_index', 0);
// 设置自定义属性
experiment.properties = { 自定义属性 key: '自定义属性 value' };
SensorsABTest.sharedInstance.fastFetchABTestWithExperiment(experiment, (value) => {
if (typeof value === 'number') {
const integerResult: number = value;
// TODO 请根据 integerResult 进行自己的试验,当前试验对照组返回值为:0,试验组依次返回:1, 2, 3
}
});
自定义属性值支持字符串、字符串数组、数值、布尔和日期时间格式,并且属性名支持英文、数字、下划线,且不能以数字开头。
获取设备主体试验变量
SDK 支持使用设备主体进行分流。需要您在初始化SDK时,将匿名ID设置为公共属性。初始化并设置公共属性的具体方式如下:
import { SensorsABTest, SensorsABTestExperiment } from '@sensorsdata/abtesting';
// 必须先初始化神策分析 SDK
// A/B Testing SDK 初始化(试验上线前,请检查试验的分流服务的 url 是否正确)
let config: SensorsABTestConfigOptions = new SensorsABTestConfigOptions("分流地址 URL");
// context 为当前 App 的 UIAbilityContext,内部存储等 API 需要使用
SensorsABTest.start(config, this.context);
//设备主体分流需要将匿名ID设置为公共属性
const anonymousId = sensors.getAnonymousID();
sensors.registerApp({
anonymous_id: anonymousId,
});
后续可以使用
- fetchCacheABTest :读取本地缓存,缓存不存在时使用默认值
- asyncFetchABTest :忽略本地缓存,从服务端获取数据
- fastFetchABTest :优先读取本地缓存,缓存不存在时从服务端获取数据
三种方式同获取试验变量
携带自定义主体获取试验变量
SDK 支持使用自定义主体进行分流。在接入前,需要您确认以下几点:
- 确认您要使用的自定义主体参数名(例如 phone_number, account 等,支持自定义)。
- 在神策元数据管理将该自定义主体设置为属性。
- 将自定义主体参数名提供给神策,由神策技术人员将其配置到分流服务后台。
在SDK初始化后,在调用获取试验变量API时,手动将其添加到接口请求参数custom_ids字典中。具体方式如下:
import { SensorsABTest, SensorsABTestExperiment } from '@sensorsdata/abtesting';
// 必须先初始化神策分析 SDK
// A/B Testing SDK 初始化(试验上线前,请检查试验的分流服务的 url 是否正确)
let config: SensorsABTestConfigOptions = new SensorsABTestConfigOptions("分流地址 URL");
// context 为当前 App 的 UIAbilityContext,内部存储等 API 需要使用
SensorsABTest.start(config, this.context);
//自定义主体分流需要设置
SensorsABTest.sharedInstance.setCustomIDs({
"自定义主体 key": "自定义主体 value"
});
后续可以使用
- fetchCacheABTest :读取本地缓存,缓存不存在时使用默认值
- asyncFetchABTest :忽略本地缓存,从服务端获取数据
- fastFetchABTest :优先读取本地缓存,缓存不存在时从服务端获取数据
三种方式同获取试验变量
调试试验
开启神策分析埋点 SDK 的 log 日志后,从事件日志中获取接口获取 distinct_id,将 distinct_id 录入到调试设备管理列表中,在创建试验时,直接将指定调试设备录入到对应试验分组。
- 调试设备在调试状态和正式上线阶段都会生效