广告平台渠道 Android 集成指南
本文档面向的客户为：在 Xinstall 管理后台建立 [ 广告平台渠道 ] 并需要进行统计的客户，是在原有的 Android 集成 基础上进行的额外集成工作。
若您不使用 [ 广告平台渠道 ]，则无需进行该文档中的额外集成工作，也能正常使用 Xinstall 提供的其他功能。
三方广告平台渠道监测，Android 主要用到了IMEI、OAID、advertisingId（Google Ad ID）。其中IMEI在Android 10 之后就获取不到了。如果最低Android 版本高于Android 10 可以跳过设备唯一标识码(IMEI)接入
OAID 使用的是反射获取，最新支持1.0.25，SDK版本不同类会有有变动导致反射无法获取，这时候用户可以自行获取传入oaid。
Google Ad ID 不建议用户自己获取，SDK 会内部获取，如果有特殊原因，需要自己获取，可以外部传入advertisingId（Google Ad ID，即 gaid）
前期准备
在准备接入广告平台渠道监测SDK之前，可以按照集成指南中 -> App集成中的Android集成文档或者在控制台中的 应用集成 -> Android集成 按部就班的完成SDK集成。
三方广告平台渠道监测接入需要获取的参数
一、IMEI 获取
如果我们最低版本高于Android 10，则我们可以直接跳过接入IMEI。
1、声明获取IMEI需要的权限
在AndroidManifest.xml 文件中添加获取IMEI需要的权限声明：
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
2、SDK处理权限申请的初始化
2.1 删除掉原有的初始化代码，在Activity中调用在SDK内申请imei权限的初始化API：
// 配置类 开启广告
XINConfiguration configuration = XINConfiguration.Builder().adEnable(true);
// 初始化方法
XInstall.initWithPermission(this,configuration);
如果希望权限通过后，马上执行后续API的话，可以改用以下方法：
// 配置类 开启广告
XINConfiguration configuration = XINConfiguration.Builder().adEnable(true)；
// 初始化方法 权限通过，初始化完成后会回调 runnable
XInstall.initWithPermission(this,configuration, new Runnable() {
@Override
public void run() {
// 调用 getWakeUpParam 或者 getInstallParam 方法
}
});
2.2 重写 Activity 的 onRequestPermissionsResult方法，并通过调用Xinstall SDK 的onRequestPermissionsResult方法去告知Xinstall SDK 权限相关的信息（是否通过权限）。具体代码如下：
// 注：Activtiy 需要 遵守 ActivityCompat.OnRequestPermissionsResultCallback 协议
@Override
public void onRequestPermissionsResult(int requestCode, @NonNull @NotNull String[] permissions, @NonNull @NotNull int[] grantResults) {
super.onRequestPermissionsResult(requestCode, permissions, grantResults);
// 将权限申请结果告知Xinstall SDK
XInstall.onRequestPermissionsResult(requestCode,permissions,grantResults);
}
3、自行处理权限申请的初始化
如果没有特殊需要在外部做权限申请，建议使用SDK 内部权限申请初始化接口。如果确实需要外部自行处理权限申请的，可按以下步骤处理。
3.1 引入IMEI获取代码需要依赖的support-v7包，代码如下：
dependencies {
implementation "com.android.support:appcompat-v7:28.0.0"
}
如果在项目中已导入该依赖，则忽略此步骤。
3.2 删除原有集成的初始化代码，在外部自行请求权限后初始化
注1： 该方案，在相同权限，有多个SDK 或者服务使用到的时候使用。
非特殊情况建议使用Xinstall 的initWithPermission方法
注2： 初始化，建议在最初调用的Activity中处理，后续SDK 的功能都基于已经完成了初始化。
具体代码如下：
public class TwoAcrivity extends AppCompatActivity implements ActivityCompat.OnRequestPermissionsResultCallback {
// 配置类 开启广告
XINConfiguration configuration = XINConfiguration.Builder().adEnable(true);
@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_two);
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
if (ActivityCompat.checkSelfPermission(this, Manifest.permission.READ_PHONE_STATE)
!= PackageManager.PERMISSION_GRANTED) {
// 注 1111 为特殊定义code 内部会使用到，请勿更改-------------------------
ActivityCompat.requestPermissions(this,
new String[]{Manifest.permission.READ_PHONE_STATE}, 1111);
//------------------------------------------------------------------
} else {
// 不处理获取IMEI需要的权限操作初始化
XInstall.init(getApplicationContext(), configuration);
}
} else {
// 不处理获取IMEI需要的权限操作初始化
XInstall.init(getApplicationContext(), configuration);
}
}
@Override
public void onRequestPermissionsResult(int requestCode, @NonNull @NotNull String[] permissions, @NonNull @NotNull int[] grantResults) {
super.onRequestPermissionsResult(requestCode, permissions, grantResults);
// 将权限申请结果告知Xinstall SDK
XInstall.onRequestPermissionsResult(requestCode,permissions,grantResults);
}
}
二、OAID获取
在Android 10 及以上 版本中，广告渠道商作为非厂商系统应用，将不再拥有获取IMEI的权限。
在此情况下，移动安全联盟针对该问题，联合国内手机厂商推出补充设备标准体系方案，将 OAID 字段作为 IMEI 的替代字段。根据“移动智能终端补充设备标识体系”技术要求，华为、小米、OPPO、vivo、中兴、努比亚、魅族、联想、三星等设备厂商均将逐步实现该识体系。绝大部分广告渠道商也已将 OAID 作为渠道匹配的字段，现在OAID 的准确性和覆盖率均可以满足广告场景的使用需求。
前提准备：
集成前，请先前往 移动安全联盟 申请下载 SDK，并阅读相关集成文档。相关集成事项以集成文档为准。下列步骤为1.0.25版本aar的集成步骤。
1、导入SDK和资源
1.1 将下载的压缩包解压
1.2 将oaid_sdk_1.0.25.aar(不同版本的SDK，名字可能不一样，找到aar文件即可) 拷贝到项目的 app/libs/目录下
1.3 将supplierconfig,json拷贝到app/src/main/assets/目录下
注：该文件中需要自己加入不同手机厂商设备的应用市场的appId, 现阶段只用填vivo的应用市场的appId 及小米应用市场的appId
2、配置配置
2.1 添加依赖
在 app/build.gradle 文件的 dependencies中添加OAID库依赖，具体如下：
dependencies {
// 其他配置---------
......
// ----------------
// oaid 配置
implementation files('libs/oaid_sdk_1.0.25.aar')
}
2.2 配置混淆
在混淆配置文件中，添加如下命令：
-keep class XI.CA.XI.**{*;}
-keep class XI.K0.XI.**{*;}
-keep class XI.XI.K0.**{*;}
-keep class XI.xo.XI.XI.**{*;}
-keep class com.asus.msa.SupplementaryDID.**{*;}
-keep class com.asus.msa.sdid.**{*;}
-keep class com.bun.lib.**{*;}
-keep class com.bun.miitmdid.**{*;}
-keep class com.huawei.hms.ads.identifier.**{*;}
-keep class com.samsung.android.deviceidservice.**{*;}
-keep class com.zui.opendeviceidlibrary.**{*;}
-keep class org.json.**{*;}
-keep public class com.netease.nis.sdkwrapper.Utils {public
<methods>;}
2.3 设置编译选项
在 app/build.gradle 文件的 android -> defaultConfig 中配置编译选项，具体如下：
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内部通过反射获取oaid，所以不同版本SDK 会有不同。如果应为版本原因，SDK内部获取不到oaid。用户可以通过联盟官方文件指导自行获取，并把oaid 传给Xinstall SDK。示例如下：
// 配置类 开启广告
XINConfiguration configuration = XINConfiguration.Builder().adEnable(true);
// 外部传入用户自己获取到的 oaid
configuration.oaid("用户自己获取的oaid");
// 初始化方法 SDK内部会自动处理获取IMEI需要的相关权限处理
XInstall.initWithPermission(this,configuration);
//or 如果希望权限通过后，马上执行后续API的话，可以改用以下方法。----------------
// XInstall.initWithPermission(this,configuration, new Runnable() {
// @Override
// public void run() {
// // 调用 getWakeUpParam 或者 getInstallParam 方法
// }
// });
// --------------------------------------------------------------------
三、Google Ad ID 获取
1、自动获取Google Ad ID
接入SDK后，用户使用 Google Play 发布和分发应用，并且装有Google应用市场，SDK会自动获取到广告ID。
2、手动获取Google Ad ID
用户也可以自行获取广告ID，并手动传递给Xinstall SDK。示例如下：
// 配置类 开启广告
XINConfiguration configuration = XINConfiguration.Builder().adEnable(true)；
// 外部传入用户自己获取到的Google广告ID
configuration.gaid("用户获取的Google广告ID")
// 初始化方法 SDK内部会自动处理获取IMEI需要的相关权限处理
XInstall.initWithPermission(this,configuration);
//or 如果希望权限通过后，马上执行后续API的话，可以改用以下方法。-----------------
// XInstall.initWithPermission(this,configuration, new Runnable() {
// @Override
// public void run() {
// // 调用 getWakeUpParam 或者 getInstallParam 方法
// }
// });
//----------------------------------------------------------------------