4.3. Android SDK 集成文档
Android SDK 集成文档
集成SDK
AppAdhoc提供两种SDK包，其中精简包仅支持编程试验，标准包支持编程和可视化试验。
通过在工程build.gradle配置脚本中添加maven线上依赖，导入最新版本SDK和 "msa mdid xxx.aar" 设备ID包 （下载地址） 添加的libs目录。 在Gradle依赖中添加：
repositories {
flatDir {
dirs 'libs'
}
}
// 标准包或者使用精简包
dependencies {
implementation 'com.appadhoc:abtest:5.4.8' // AB测试标准包
// implementation 'com.appadhoc:abtestX:5.4.8' // 标准包AndroidX版本
// 使用标准包或者使用精简包。
implementation(name: 'msa_mdid_1.0.13', ext: 'aar')// 设备id包
// gif图可视化编辑（可选项）
// implementation 'pl.droidsonroids.gif:android-gif-drawable:1.2.21'(需要支持gif图的用户需要添加该库)
}
// 精简包引用,同时支持AndroidX和support
implementation 'com.appadhoc:abtest-lite:5.4.8'// AB测试精简包
如果无法正常集成请添加如下配置：
allprojects{
repositories{
mavenCentral()
}
}
无法正常加载依赖可以通过下载最新Adhoc Android SDK AAR文件方式集成，点击下载： abtest-5.4.8.aar abtest-lite-5.4.8.aar abtestX-5.4.8.aar
加入网络访问权限
在项目中找到项目配置文件 AndroidManifest.xml,加入网络访问等权限：
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
//读取手机IMEI的权限，须在获得此权限后再初始化SDK，如果缺少此权限，会以AndroidID作为设备唯一标识符
<uses-permissionandroid:name="android.permission.READ_PHONE_STATE"/>
//获取wifi状态权限
<uses-permissionandroid:name="android.permission.ACCESS_WIFI_STATE"/>
//读取手机IMEI的权限，须在获得此权限后再初始化SDK，如果缺少此权限，会以AndroidID作为设备唯一标识符
<uses-permissionandroid:name="android.permission.READ_PHONE_STATE"/>
//读写sd卡的权限
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
在应用的build.gradle下增加如下配置
android{
...
defaultConfig{
...
ndk { abiFilters 'armeabi-v7a','x86','arm64-v8a','x86_64','armeabi' }
}
packagingOptions {
doNotStrip "*/armeabi-v7a/*.so"
doNotStrip "*/x86/*.so"
doNotStrip "*/arm64-v8a/*.so"
doNotStrip "*/x86_64/*.so"
doNotStrip "armeabi.so"
}
}
SDK初始化
1.在工程文件“项目名称.java”文件中创建Appllication 类
public class DemoApplication extends Application {
private static final String TAG = "DemoApplication" ;
private static DemoApplication instance;
2.需要在AndroidManifest.xml 里指定类名：
如果已经创建过Application类，跳过新建步骤，直接在onCreate加入上述代码即可。
3.在调用SDK之前记得引入文件
import com.adhoc.adhocsdk.AdhocTracker;
import com.adhoc.adhocsdk.AdhocConfig;
4.并在OnCreate()中加入下面代码：
// 想了解配置项更详细介绍可以查阅doc文件
AdhocTracker.init(this,AdhocConfig.defaultConfig()
//this是Context对象
//设置appKey(必要参数)
.appKey(key)
//开启debug悬浮框,在控制台输出变量、设备加入的试验信息、和上报的日志信息，tag（ADHOC_SDK）
.enableDebugAssist(true)
//多进程数据安全设置选项
//.supportMultiProcess()
//开启实时上报
//.reportImmediately()
//支持后端SDK分流
//.supportBackend(true)
);
其中，“appKey” 是在登录 AppAdhoc 后,创建“应用”之后获得的授权标识。
注意：试验“应用”此时应该提前创建完毕。可在AppAdhoc控制台应用列表找到，如下图红线部分：
请勿在SDK基础上进行自行封装，以免影响到试验逻辑，造成试验无法正常运行。如果确有自行封装的需求，请与客户经理联系，获取注意事项。
编程模式：根据“试验变量”展示相应内容
试验变量的值决定了展示的内容或程序的逻辑。试验变量在编程模式试验中创建，可视化试验无需此步骤。
注意：试验变量值应由PM或相关A/B Testing需求制定人员在后台提前录入完毕，如下图“版本管理”红线部分：
请务必保证代码中的变量名称与此处填写完全一致（包括字母大小写等）。
获取变量的值，请在使用到该变量处添加以下代码：
最好在Activity的onStart方法中加入代码,提供两个方法获取试验数据。
方法一：getFlag方法，该方法只取本地缓数据，默认一个小时从服务器获取一次试验数据。
@Override
public void onStart() {
super.onStart();
//该方法
//获取试验变量isNewHomePage的值
//第二个参数为设定默认值，在网络异常时将按照该默认值执行
int value = AdhocTracker.getFlag("isNewHomePage", 0);
switch (value){
case 0:
//执行默认版本或者原始版本逻辑
break;
case 1:
//执行版本1逻辑
break;
case 2:
//执行版本2逻辑
break;
}
}
方法二：asyncGetFlag方法，从网络获取变量，并执行回调，每次调用都会从服务器获取试验数据。
@Override
public void onStart() {
super.onStart();
// 该方法异步从服务器获取试验数据，并执行回调函数。
AdhocTracker.asyncGetFlag(2000(超时时间，单位毫秒),"isNewHomePage",-1,new OnAdHocReceivedData<Integer>(){
@Override
public void onReceivedData(Integer value){
switch (value){
case 0:
//执行默认版本或者原始版本逻辑
break;
case 1:
//执行版本1逻辑
break;
case 2:
//执行版本2逻辑
break;
}
}
});
}
其中，'isNewHomePage' 即是“试验变量“，应与上图中红线标识保持一致。
请注意在用户访问到试验页面时，需要触发试验变量才算作进入该试验，否则将不会统计进入该试验。
编程模式：上报指标
指标用于量化试验结果的好坏，AppAdhoc 后台中的试验图表根据此数据生成。 在可视化试验中，您也可以通过此方法定义上报指标。
请务必保证代码中的变量名称与此处填写完全一致（包括字母大小写等）。
比如在进入某一逻辑分支后，可以统计点击次数。将上图中的指标“clickTimes”传入函数track实现上报指标, 每次累加1：
AdhocTracker.track("clickTimes", 1);
如果希望对某一指标统计但同时又希望对该指标统计一次，类似对某一帖子打开统计，打开多次只统计一次，可以使用distinctTrack方法。参数“clickTimes”是指标名称，“1”是统计数值，第三个参数“id123456”是一个类似唯一id的值，由开发者传入，比如该值可以是某帖子详情的id，该方法可以实现用户设备最多上报一次。
AdhocTracker.distinctTrack("clickTimes",1,"id123456");// AppAdhoc Android SDK会用参数“id123456”过滤上报数据，实现最多上报一次。
混淆相关
在proguard-rules.txt文件中加入：
-dontwarn com.bun.miitmdid.**
-dontwarn com.adhoc.**
-keep class com.bun.miitmdid.** {*;}
-keep class com.adhoc.** {*;}
//标准包可视化编辑反射使用到ViewPager和RecyclerView避免混淆，support版本
-keep class android.support.v4.view.ViewPager{*;}
-keep class android.support.v4.view.ViewPager$*{*;}
-keep class android.support.v7.widget.RecyclerView{*;}
-keep class android.support.v7.widget.RecyclerView$*{*;}
-keep class * extends android.support.v7.widget.RecyclerView$Adapter
//避免混淆ViewPager和RecyclerView AndroidX版本
-keep class androidx.viewpager.widget.ViewPager{*;}
-keep class androidx.viewpager.widget.ViewPager$*{*;}
-keep class androidx.recyclerview.widget.RecyclerView{*;}
-keep class androidx.recyclerview.widget.RecyclerView$*{*;}
-keep class * extends androidx.recyclerview.widget.RecyclerView$Adapter
集成调试
集成调试只是为验证SDK的集成是否成功（并不是真正开始试验！）。
在SDK启动时设置是否显示调试按钮
AdhocTracker.init(getApplicationContext(),AdhocConfig.defaultConfig()
//设置appKey(必要参数)
.appKey(key)
//true开启调试按钮,false关闭调试按钮
.enableDebugAssist(true)
);
在Debug模式下启动APP，会出现下图中的悬浮图标：详细使用请参考Android集成调试。
点击上面的悬浮图标，扫描后台系统“集成调试”中的二维码，进入相应试验：
高级功能 受众定向（需要联系管理员开启）
AppAdhoc SDK 支持预定义受众定向和自定义受众定向两种方式。
预定义受众定向功能中，开发者只需要在AppAdhoc平台中选择预设的受众标签，SDK会自动采集相关信息并判定当前用户是否进入试验（例如APP版本、语言等用户标签），无需在代码中定义。
开发者也可以根据需要选择自定义手中标签，此方式需要在AppAdhoc平台中填写好标签的key和value，之后再代码中为当前用户设置标签，进而实现将不符合条件的用户排除在此次试验之外。比如只想要女性用户，或30岁以下的用户参与试验等。
关于受众定向详细请参考受众定向。
注意：自定义受众定向条件应由PM或相关AB Test需求制定人员在后台提前录入完毕，如下图“受众定向”红线部分。
在运行控制/右侧定向试验：
选择分组，点击编辑用户群：
即得到受众条件的key，在下图例子中，“sex”是key：
在AdhocTracker.init()方法中进行设置：
//创建受众标签的值
String sex = GetUserSexValue()；
AdhocTracker.init(getApplicationContext(),AdhocConfig.defaultConfig()
//getApplicationContext() 设置APP上下文(必要参数)
//设置appKey(必要参数)
.appKey(key)
//添加自定义用户标签
.addCustomAttribute("sex",sex));
API 参考
集成调试
恭喜，您完成了AppAdhoc A/B Testing SDK的埋点集成工作，后续可通过AppAdhoc平台集成调试功能验证试验流程。
注意：确保app_key, 试验变量字符串，指标字符串与后台截图处一一对应，否则可能出现异常或无试验数据情况。