Android SDK 集成（A/B Testing）

A/B Testing SDK 依赖于神策分析 SDK v4.3.6 及以上版本，在使用前请确保已经成功集成神策分析 SDK，并进行了 SDK 初始化，详情可参考 SDK 集成（Android）。

SDK 集成

在主 module 的 build.gradle 文件中添加 A/B Testing SDK 依赖：

apply plugin: 'com.android.application'

dependencies {
   // 添加 A/B Testing SDK 依赖
    implementation 'com.sensorsdata.analytics.abtesting:SensorsABTesting:1.1.2'
}

初始化 SDK

在神策分析中创建 A/B Testing 后，会生成分流试验请求 URL，通过该 URL 初始化 A/B Testing SDK：

import com.sensorsdata.abtest.SensorsABTest;
import com.sensorsdata.abtest.SensorsABTestConfigOptions;

    try {
        // 确保先初始化神策分析 SDK（参考文档 https://manual.sensorsdata.cn/sa/latest/tech_sdk_client_android_basic-17563982.html）
        // A/B Testing SDK 初始化
        SensorsABTestConfigOptions abTestConfigOptions = new SensorsABTestConfigOptions("分流试验请求地址");
        SensorsABTest.startWithConfigOptions(this, abTestConfigOptions);
    } catch (Exception e) {
        e.printStackTrace();
    }

获取试验变量

初始化 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 为例，可在相应的业务逻辑中添加如下代码：

import com.sensorsdata.abtest.SensorsABTest;
import com.sensorsdata.abtest.OnABTestReceivedData;

    try {
        // Integer 类型试验（第二个参数 0，表示未命中试验时，会返回此默认值，请根据业务需要更改此处的值）
        SensorsABTest.shareInstance().fastFetchABTest("具体的试验参数", 0, new OnABTestReceivedData<Integer>() {
            @Override
            public void onResult(Integer result) {
                // TODO 根据 result 处理相应逻辑
                switch (result) {
                    case 0:
                        break;
                    case 1:
                        // 试验组 1 的处理逻辑
                        break;
                    case 2:
                        // 试验组 2 的处理逻辑
                        break;
                    // ……
                    // ……
                    default:
                        // 其他情况的处理逻辑
                        break;
                }
            }
        });
    } catch (Exception e) {
        e.printStackTrace();
    }

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

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

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

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

asyncFetchABTest 和 fastFetchABTest 接口会在主线程回调试验变量值

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

import com.sensorsdata.abtest.SensorsABTest;
import com.sensorsdata.abtest.SensorsABTestConfigOptions;
import com.sensorsdata.abtest.OnABTestReceivedData;
import com.sensorsdata.abtest.SensorsABTestExperiment;  

// 当前为 Integer 类型试验（第二个参数 0，表示未命中试验时，会返回此默认值，请根据业务需要更改此处的值）
try {
    SensorsABTestExperiment experiment = SensorsABTestExperiment.newBuilder("具体的试验参数", 0)
            .addProperty("自定义属性对应英文名", "自定义属性对应 value")  // 自定义属性
            .create();
     SensorsABTest.shareInstance().fastFetchABTest(experiment, new OnABTestReceivedData<Integer>() {
        @Override
        public void onResult(Integer result) {
            // TODO 请根据 result 进行自己的试验
        }
    });
} catch (Exception e) {
    e.printStackTrace();
}

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

设置全局自定义属性

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

版本要求

A/B Testing Android SDK 版本 >= v1.1.2

初始化接口设置自定义属性

SensorsABTestConfigOptions abTestConfigOptions = new SensorsABTestConfigOptions(AB_DISPATCH_SERVER_URL);
JSONObject properties = new JSONObject();
properties.put("自定义属性对应英文名", "自定义属性对应 value");
// 初始化设置自定义属性
abTestConfigOptions.setCustomProperties(properties);
SensorsABTest.startWithConfigOptions(this, abTestConfigOptions);

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

 JSONObject properties = new JSONObject();
properties.put("自定义属性 key", "自定义属性 value"); 
SensorsABTest.shareInstance().setCustomProperties(properties);

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

获取设备主体试验变量

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

import com.sensorsdata.abtest.SensorsABTest;
import com.sensorsdata.abtest.SensorsABTestConfigOptions;

    try {
        // 确保先初始化神策分析 SDK（参考文档 https://manual.sensorsdata.cn/sa/latest/tech_sdk_client_android_basic-17563982.html）
        // A/B Testing SDK 初始化
        SensorsABTestConfigOptions abTestConfigOptions = new SensorsABTestConfigOptions("分流试验请求地址");
        SensorsABTest.startWithConfigOptions(this, abTestConfigOptions);
        //设备主体分流需要将匿名ID设置为公共属性
        try {
           JSONObject properties = new JSONObject();
           properties.put("anonymous_id", SensorsDataAPI.sharedInstance().getAnonymousId());
           SensorsDataAPI.sharedInstance().registerSuperProperties(properties);
        } catch (JSONException e) {
           e.printStackTrace();
        }
    } catch (Exception e) {
        e.printStackTrace();
    }

后续可以使用

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

三种方式用法同获取试验变量

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

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

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

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

import com.sensorsdata.abtest.SensorsABTest;
import com.sensorsdata.abtest.SensorsABTestConfigOptions;

    try {
        // 确保先初始化神策分析 SDK（参考文档 https://manual.sensorsdata.cn/sa/latest/tech_sdk_client_android_basic-17563982.html）
        // A/B Testing SDK 初始化
        SensorsABTestConfigOptions abTestConfigOptions = new SensorsABTestConfigOptions("分流试验请求地址");
        SensorsABTest.startWithConfigOptions(this, abTestConfigOptions);
        
        try {
           //自定义主体分流需要将自定义主体名设置为公共属性            
           JSONObject properties = new JSONObject();
           properties.put("自定义主体参数名", "自定义主体参数值");   //例如： properties.put("phone_number", "12345678910");
           SensorsDataAPI.sharedInstance().registerSuperProperties(properties);
           //将自定义主体加入分流请求中
           HashMap<String, String> customIds = new HashMap<>();
           customIds.put("自定义主体参数名", "自定义主体参数值");
           SensorsABTest.shareInstance().setCustomIDs(customIds);          
        } catch (Exception e) {
           e.printStackTrace();
        }
    } catch (Exception e) {
        e.printStackTrace();
    }

后续可以使用

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

三种方式用法同获取试验变量

调试试验

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

录入前请确保 App 已正确配置 Scheme

调试设备在调试状态和正式上线阶段都会生效