菜单

Unity SDK 集成（A/B Testing）

版本兼容

SDK 集成

  1. 从 GitHub - releases 下载神策 A/B Testing Unity SDK 最新资源包（.unitypackage 文件）

  2. 将上述文件通过 Assets > Import Package > Custom Package 添加到项目中
  3. 将 SensorsABTesting 目录下的 SensorsABTesting.prefab 预制体拖到需要加载的位置（如果和 SensorsAnalytics.prefab 同一位置，请放在其后面）
  4. 配置 SDK 初始化参数
         
 
ABTest Url：A/B Testing 分流地址
  • 每个项目都有单独的分流地址
  • 详参见神策分析 -> A/B 测试 ->  试验列表 ->  更多 ->  示例代码

获取试验变量

初始化 SDK 之后，通过 API 获取具体试验的变量值，根据获取试验变量值的方式，可分为下面三种策略：

  • FetchCacheABTest：读取本地缓存，缓存不存在时使用默认值
  • AsyncFetchABTest：忽略本地缓存，从服务端获取数据
  • FastFetchABTest：优先读取本地缓存，缓存不存在时从服务端获取数据

如何确定应该选择哪个API获取试验变量值？

1.一般情况下，我们推荐使用 FastFetchABTest 获取试验变量值。

2.如果您对性能有要求，可以使用 FetchCacheABTest, 只从本地缓存中获取变量值，但可能导致用户无法及时命中最新的试验。

3.如果您进行时间片轮转试验，且对时效性有要求，可以使用 AsyncFetchABTest 获取试验变量值，但会存在一定的网络延迟。

1. AsyncFetchABTest 和 FastFetchABTest 接口会在主线程回调试验变量值，FetchCacheABTest 接口会在当前线程返回试验变量值

2. 请确保对A/B分流返回的 result 结果 & 接口中使用的默认值，都做了正常的业务逻辑处理！

3. 请确保默认值 default_value 和当前试验值类型相同。比如参数对应试验值为 Int 类型，则传入的 default_value 也必须是 Int 类型，同时返回的试验结果 result 也是 Int 类型

以 FastFetchABTest 为例，可在相应的业务逻辑中添加如下代码：

using SensorsABTesting;

// Integer 类型试验（第二个参数 0，表示未命中试验时，会返回此默认值，请根据业务需要更改此处的值）
SensorsABTestAPI.FastFetchABTest("试验参数名", 0, (int result) =>
 {
    Debug.Log("FastFetchABTest 获取 Int 试验结果：" + result.ToString());
});

携带自定义属性获取试验变量

单次获取试验携带自定义属性

SDK 支持自定义属性扩充受众筛选能力，可以在初始化 SDK 后，通过 API 添加自定义属性获取具体试验的变量值，根据获取试验变量值的方式，可分为下面 2 种策略：

  • AsyncFetchABTest：忽略本地缓存，从服务端获取数据
  • FastFetchABTest：优先读取本地缓存，缓存不存在时从服务端获取数据

AsyncFetchABTest 和 FastFetchABTest 接口会在主线程回调试验变量值

以 FastFetchABTest 为例，可在相应的业务逻辑中添加如下代码：

using SensorsABTesting;

// JSON 类型试验（第二个参数 defaultValueDic，表示未命中试验时，会返回此默认值，请根据业务需要更改此处的值
Dictionary<string, object> defaultValueDic = new Dictionary<string, object>();
defaultValueDic.Add("默认json-key", "默认json-value");
SensorsABTestExperiment experiment = SensorsABTestExperiment.CreateExperiment("试验参数名", defaultValueDic);
Dictionary<string, object> properties = new Dictionary<string, object>();
properties.Add("自定义属性 key", "自定义属性 value");
experiment.Properties = properties;
 
SensorsABTestAPI.FastFetchABTest(experiment, (Dictionary<string, object> dicResult) =>
{
    // TODO 请根据 dicResult 进行自己的试验，
});

设置全局自定义属性

通过初始化 SDK 或者接口动态设置全局自定义属性，后续所有获取试验分流场景，都会包含自定义属性筛选。

例如 App 运行过程中，根据需要，动态重置自定义属性（重新设置后，会覆盖初始化设置的自定义属性内容）。后续分流请求，都会包含新设置的自定义属性

using SensorsABTesting;

Dictionary<string, object> customProperties = new Dictionary<string, object>();
customProperties.Add("自定义属性 key", "自定义属性值");
SensorsABTestAPI.SetCustomProperties(customProperties);

自定义属性值支持字符串、字符串数组、数值、布尔和日期时间格式，并且属性名支持英文、数字、下划线，且不能以数字开头。

获取设备主体试验变量

SDK 支持使用设备主体进行分流。需要您在初始化 SDK 后，立即将匿名ID设置为公共属性。初始化并设置公共属性的具体方式如下：

using SensorsAnalytics;

// 必须先初始化神策分析 SDK（参考文档 https://manual.sensorsdata.cn/sa/docs/tech_sdk_client_unity_ues）
// A/B Testing SDK 初始化，略

//设备主体分流需要将匿名ID设置为公共属性
string anonymousId = SensorsDataAPI.AnonymousId();
Dictionary<string, object> dictionary = new Dictionary<string, object>();
dictionary.Add("anonymous_id", anonymousId);
SensorsDataAPI.RegisterSuperProperties(dictionary);

后续可以使用

  • FetchCacheABTest：读取本地缓存，缓存不存在时使用默认值
  • AsyncFetchABTest：忽略本地缓存，从服务端获取数据
  • FastFetchABTest ：优先读取本地缓存，缓存不存在时从服务端获取数据

三种方式 获取试验变量

携带自定义主体获取试验变量

SDK 支持使用自定义主体进行分流。在接入前，需要您确认以下几点：

  • 确认您要使用的自定义主体参数名（例如 phone_number, account等，支持自定义）。
  • 在神策元数据管理将该自定义主体设置为公共属性。
  • 将自定义主体参数名提供给神策，由神策技术人员将其配置到分流服务后台。

在 SDK 初始化后，将您使用的自定义主体设置为公共属性，并在调用获取试验变量API时，手动将其添加到接口请求参数 custom_ids 字典中。具体方式如下：

using SensorsAnalytics;
using SensorsABTesting;

// 必须先初始化神策分析 SDK（参考文档 https://manual.sensorsdata.cn/sa/docs/tech_sdk_client_unity_ues）
// A/B Testing SDK 初始化，略

//自定义主体分流需要将自定义主体名设置为公共属性，并将其加入分流请求中
Dictionary<string, object> customIDs = new Dictionary<string, object>();
customIDs.Add("自定义主体 key", "自定义主体值")
SensorsDataAPI.RegisterSuperProperties(customIDs);

// 设置自定义主体
SensorsABTestAPI.SetCustomIDs(customIDs);

后续可以使用

  • fetchCacheABTest ：读取本地缓存，缓存不存在时使用默认值
  • asyncFetchABTest ：忽略本地缓存，从服务端获取数据
  • fastFetchABTest ：优先读取本地缓存，缓存不存在时从服务端获取数据

三种方式 获取试验变量

调试试验

配置 Scheme 

参考  配置 Scheme（只支持 Android & iOS）

添加脚本代码

在脚本（比如脚本类名为 ExampleBehaviour）代码中，添加如下代码，处理 SchemeUrl。

// 声明 static 示例脚本
static ExampleBehaviour saInstance;

void Awake(){
	//判断是否需要 SDK 处理，防止重复添加回调
    if (saInstance == null){
        DontDestroyOnLoad(gameObject);
        saInstance = this;
        Application.deepLinkActivated += handSchemeUrl;
    }else{
        Destroy(gameObject);
        return;
    }   
}
 
private void handSchemeUrl(string url)
{
	//SDK 处理 URl
    SensorsABTestAPI.HandleOpenURL(url);
}

 

可先将设备录入到调试设备管理列表中，在创建试验时，直接将指定调试设备录入到对应试验分组。

  • 录入前请确保 App 已正确 配置 Scheme
  • 调试设备在调试状态和正式上线阶段都会生效
 
上一个
HarmonyOS SDK 集成（A/B Testing）
下一个
试验实施指南
最近修改: 2025-08-11