Java A/B Testing SDK 依赖神策分析 SDK。在使用前请确保已经成功集成神策分析 SDK,并进行了 SDK 初始化,详情可参考 SDK集成(Java)

Java A/B Testing SDK 需要 JDK 1.7+,Java A/B Testing SDK 依赖 Java 神策分析 SDK,支持版本 3.2.0+,引用 guava 18.0 版本

1. SDK 集成

本次 SDK 推荐的集成方式是采用 Maven 集成。

<dependency>
      <groupId>com.sensorsdata.analytics.javasdk</groupId>
      <artifactId>SensorsABTesting</artifactId>
      <version>0.0.1</version>
</dependency>
CODE

非 Maven 项目可以去 Maven 中央仓库搜索下载 jar 包到本地,然后手动添加到项目中。

2. 初始化 SDK

Java A/B Testing SDK 依赖神策分析 SDK。请确保已经成功集成神策分析 SDK,并进行了 SDK 初始化。成功引入 A/B Testing SDK 之后,请先在神策分析前端页面创建相关的分流试验,然后获取生成的分流 URL。

2.1. 在普通 Java 项目初始化 SDK

        // 初始化神策分析 SDK
        final ISensorsAnalytics sa = new SensorsAnalytics(new ConcurrentLoggingConsumer("file.log"));
        // 构建配置 A/B Testing 试验全局参数
        ABGlobalConfig abGlobalConfig = ABGlobalConfig.builder()
                                            .setApiUrl("分流试验请求地址")    
                                            .setSensorsAnalytics(sa)    // 神策分析埋点 SDK 实例
                                            .build();
        // 初始化 A/B Testing SDK
        final ISensorsABTest abTest = new SensorsABTest(abGlobalConfig);
JAVA

2.2. 在 Spring 框架里面初始化 SDK

A/B Testing SDK 与神策分析 SDK 初始化方式相同,需要在全局初始化一次即可。推荐将初始化操作装配成 Bean,交给 Spring 容器来管理。下面提供两种方式创建 Bean,在实际项目中根据实际情况任选其一进行创建即可。

2.2.1. 使用 xml 配置文件创建 Bean 对象

首先构建静态工厂,生成 A/B  Testing 试验实例对象。

public class ABTestInstanceFactory {

  public static ISensorsABTest getABTestConfigInstance(String url, ISensorsAnalytics sa)
      throws InvalidArgumentException {
    ABGlobalConfig config = ABGlobalConfig.builder().setApiUrl(url).setSensorsAnalytics(sa).build();
    return new SensorsABTest(config);
  }

}
JAVA

然后在 xml 配置文件中创建 Bean 对象

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
      http://www.springframework.org/schema/beans/spring-beans-3.2.xsd">

    <!-- 本地日志模式(此模式会在指定路径生成相应的日志文件) -->
    <bean id="loggingConsumer" class="com.sensorsdata.analytics.javasdk.consumer.ConcurrentLoggingConsumer">
        <constructor-arg name="filenamePrefix" value="您的日志文件路径"/>
    </bean>

    <!-- debug 模式(此模式只适用于测试集成 SDK 功能,千万不要使用到生产环境!!!) -->
    <!--<bean id="debugConsumer" class="com.sensorsdata.analytics.javasdk.consumer.DebugConsumer">
        <constructor-arg name="serverUrl" value="数据接收地址"/>
        <constructor-arg name="writeData" value="true"/>
    </bean>-->

    <!-- 网络批量发送模式(此模式在容器关闭的时候,如果存在数据还没有发送完毕,就会丢失未发送的数据!!!)-->
    <!--<bean id="batchConsumer" class="com.sensorsdata.analytics.javasdk.consumer.BatchConsumer">
        <constructor-arg name="serverUrl" value="数据接收地址"/>
    </bean>-->

    <!-- 此处选择合适的模式进行数据采集操作(此处选择本地日志模式) -->
    <bean id="sensorsAnalytics" class="com.sensorsdata.analytics.javasdk.SensorsAnalytics" destroy-method="shutdown">
        <constructor-arg name="consumer" ref="loggingConsumer"/>
    </bean>

    <!-- 通过构建的静态工厂创建 A/B Testing SDK Bean -->
    <bean id="abTest" class="com.sensorsdata.demo.config.ABTestInstanceFactory"
          factory-method="getABTestConfigInstance">
        <constructor-arg name="url" value="分流试验请求地址"/>
        <constructor-arg name="sa" ref="sensorsAnalytics"/>
    </bean>
</beans>

CODE

2.3. 使用注解创建 Bean 对象

@Configuration
public class SensorsConfig {

  @Bean(name = "sa", destroyMethod = "shutdown")
  public ISensorsAnalytics initSensorsAnalytics() throws IOException {
    //本地日志模式(此模式会在指定路径生成相应的日志文件)
    return new SensorsAnalytics(new ConcurrentLoggingConsumer("file.log"));
    //debug 模式(此模式只适用于测试集成 SDK 功能,千万不要使用到生产环境!!!)
    //return new SensorsAnalytics(new DebugConsumer("数据接收地址", true));
    //网络批量发送模式(此模式在容器关闭的时候,如果存在数据还没有发送完毕,就会丢失未发送的数据!!!)
    //return new SensorsAnalytics(new BatchConsumer("数据接收地址"));
  }

  @Bean
  public ISensorsABTest initSensorsABTest(ISensorsAnalytics sa) throws InvalidArgumentException {
    String url = "分流试验地址";
    ABGlobalConfig config = ABGlobalConfig.builder().setApiUrl(url).setSensorsAnalytics(sa).build();
    return new SensorsABTest(config);
  }

}

JAVA

2.4. 在业务代码中调用 Bean 对象

@Service
public class TestServiceImpl implements ITestService {

  //注入神策实例化对象
  @Autowired
  ISensorsAnalytics sa;
  
  //注入 A/B Testing 实例化对象
  @Autowired
  ISensorsABTest abTest;
  
  public String abTest(String userId) throws InvalidArgumentException, IOException {
    Experiment<String> experiment = abTest.asyncFetchABTest(userId, true, "color", "grey");
    String result = experiment.getResult();
    switch (result) {
      case "试验值一":
        //命中试验一 do something
        break;
      case "试验值二":
        //命中试验二 do something
        break;
      case "grey":
        //没有命中任何试验,返回设置默认值
        break;
    }
    return "success";
  }
}

JAVA

3. 获取分流试验变量信息

Java SDK 提供两种方式获取试验变量信息:

  • asyncFetchABTest :忽略内存缓存,从服务端获取数据
  • fastFetchABTest 优先读取内存缓存,缓存不存在时从服务端获取数据。

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

fastFetchABTest 为例

String distinctId = "fz123456"; // 具体的用户 ID 标识
boolean isLoginId = true; // 当前用户是否是登录 ID
  
// Integer 类型试验(第四个参数 0,表示未命中试验时,会返回此默认值,请根据业务需要更改此处的值)
Experiment<Integer> experiment = abTest.fastFetchABTest(distinctId, isLoginId, "具体的试验参数", 0);
int result = experiment.getResult();                 
// TODO 根据 result 处理相应逻辑
        switch (result) {
            case 0:
                break;
            case 1:
                // 试验组 1 的处理逻辑
                break;
            case 2:
                // 试验组 2 的处理逻辑
                break;
            // ……
            // ……
            default:
                // 其他情况的处理逻辑
                break;
        }
JAVA

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

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

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

fastFetchABTest 为例,可在相应的业务逻辑中添加如下代码:

// 当前为 Integer 类型试验(第二个参数 0,表示未命中试验时,会返回此默认值,请根据业务需要更改此处的值)
String distinctId = "fz123456"; // 具体的用户 ID 标识
boolean isLoginId = true; // 当前用户是否是登录 ID
Map<String, Object> properties = Maps.newHashMap();
properties.put("自定义属性对应英文名", "自定义属性对应 value"); // 自定义属性

// 当前为 Integer 类型试验(第四个参数 0,表示未命中试验时,会返回此默认值,请根据业务需要更改此处的值)
Experiment<Integer> experiment = abTest.fastFetchABTest(distinctId, isLoginId, "具体的试验参数", 0, properties);
// TODO 请根据 experiment.getResult() 进行自己的试验
switch (result) {
    case 0:
        break;
    case 1:
        // 试验组 1 的处理逻辑
        break;
    case 2:
        // 试验组 2 的处理逻辑
        break;
    // ……
    // ……
    default:
        // 其他情况的处理逻辑
        break;
}
JAVA

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

5. API 介绍

5.1. 初始化全局参数设置说明

Java A/B Testing SDK 的全局参数封装在 ABGlobalConfig 类中,具体参数如下:

参数名类型说明
eventCacheTime

Integer

单用户事件缓存时间,默认值为 1440min,最大限制 1440min,最小限制 0min

eventCacheSize

Integer

事件总缓存用户量,默认值为 4096,无上限设置,最小限制 0

experimentCacheSize

Integer

试验总缓存用户量,默认值 4096,无上限设置,最小限制 0

experimentCacheTime

Integer

单用户试验缓存时间,默认值为 1440min,最大限制 1440min,最小限制 0min

enableEventCacheBoolean上报事件缓存开关,默认开启缓存

apiUrl

String

分流试验地址,必填,默认为空

sensorsAnalytics

ISensorsAnalytics

神策分析 SDK 实例对象,必填,默认为空(此处使用神策分析 SDK 版本为 3.2.0 及以上版本)

enableLogBoolean是否开启 SDK 运行输出控制台日志。默认开启

5.2. API 方法说明

描述说明
方法名asyncFetchABTest/fastFetchABTest
参数
  • distinctId 具体的用户 ID 标识
  • isLoginId 当前用户是否是登录 ID
  • experimentVariableName 试验变量名称
  • defaultValue 未命中试验,返回默认值(支持数据类型:number|boolean|String|json)
  • enableAutoTrackEvent 是否开启自动上报 $ABTestTrigger 事件,默认自动上报
  • timeoutMilliseconds 请求超时设置 默认 3000ms
  • properties 自定义属性
返回值
Experiment<T>

5.3. 方法返回值说明

Java A/B Testing SDK 统一返回 Experiment<T>对象,具体返回参数如下:

参数名类型说明

distinctId

String具体的用户 ID 标识

isLoginId

boolean当前用户是否是登录 ID

abTestExperimentId

String试验 ID

abTestExperimentGroupId

String试验分组 ID
isWhiteListboolean是否白名单用户,白名单用户不进行试验事件的上报
isControlGroupboolean是否是对照组

result

T 范型试验命中返回值,目前支持类型 (number|boolean|String|json)

6. 手动触发 A/B 测试($ABTestTrigger)事件说明

Java A/B Testing SDK 中提供的方法中,如果设置参数 enableAutoTrackEvent=true 或者不设置,并且事件内存缓存中不存在,SDK 会自动上报 A/B 测试($ABTestTrigger)事件。

如果设置 enableAutoTrackEvent=false ,则需要用户自己手动触发上报 A/B 测试($ABTestTrigger)事件

SDK 提供 trackABTestTrigger 方法,示例如下:

// 手动触发 A/B 测试($ABTestTrigger)事件
abTest.trackABTestTrigger(experiment)
JAVA

 trackABTestTrigger 方法使用说明:

方法名trackABTestTrigger
参数

Experiment<T>,即获取分流试验结果返回对象

Map<String,Object>,上报事件的属性值集合,可不传

返回结果