菜单

HarmonyOS SDK 集成(A/B Testing)

版本要求

  1. A/B Testing HarmonyOS SDK 依赖神策 HarmonyOS Analytics SDK v0.0.5 及以上版本,在使用前请确保已经成功集成神策分析 SDK,并进行了 SDK 初始化,详情可参考 集成文档(HarmonyOS SDK)
  2. 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 录入到调试设备管理列表中,在创建试验时,直接将指定调试设备录入到对应试验分组。

   

 

  • 调试设备在调试状态和正式上线阶段都会生效
上一个
本地分流 Java SDK 集成(A/B Testing)
下一个
试验实施指南
最近修改: 2024-12-27