Android SDK 集成指南
一、下载并导入 SDK
从下载中心下载 Android 最新版本 SDK 从下载的文件中,将 aar 文件拷贝到项目的libs文件夹中,并使用 gradle 导入
implementation files('libs/XInstall.aar')
二、初始化
在AndroidManifest.xml中添加权限声明
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
在AndroidManifest.xml的application标签内设置AppKey
<meta-data
android:name="com.xinstall.APP_KEY"
android:value="XINSTALL_APPKEY" />
备注: 将XINSTALL_APPKEY替换成 XInstall 为应用分配的appkey
App 启动时,调用 XInstall.init(context)方法完成 sdk 初始化
示例代码
在自定义 Application 中初始化
public class MyApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
if (isMainProcess()) {
/**
* 调用初始化时请注意:
* 1. 首次调用,需要确保客户同意《隐私政策》之后,再次初始化Xinstall SDK
* 2. 仅在主进程UI线程中调用初始化接口
*/
XInstall.init(this);
//启用log
XInstall.setDebug(true);
}
}
public boolean isMainProcess() {
int pid = android.os.Process.myPid();
ActivityManager activityManager = (ActivityManager) getSystemService(Context.ACTIVITY_SERVICE);
for (ActivityManager.RunningAppProcessInfo appProcess : activityManager.getRunningAppProcesses()) {
if (appProcess.pid == pid) {
return getApplicationInfo().packageName.equals(appProcess.processName);
}
}
return false;
}
}
为满足隐私合规要求,开发者可以控制SDK获取Android ID 、serial Number 及粘贴板权限。
// androidID/serial Number 配置值即为可以外部获取。如不想SDK 自动获取,也不想传入值 传""即可。建议尽量获取
XInstall.init(this, XINConfiguration.Builder().androidId("android ID").serial("serial Number").canClip(true));
备注: 当应用存在多个进程时,确保只在主进程进行初始化 在AndroidManifest.xml中的application标签中添加android:name=".MyApplication"指定自定义的Application类,以便程序启动的时候初始化自定义Application类,而不是默认配置的Application类
<application
android:name=".MyApplication"
android:allowBackup="false"
android:icon="@drawable/ic_launcher"
android:label="@string/app_name"
android:supportsRtl="true"
android:theme="@style/AppTheme">
...
</application>
三、功能集成
1.快速下载
如果只需要快速下载功能,无需其它功能(携带参数安装、渠道统计、一键拉起),完成初始化即可
2.一键拉起
2.1 在AndroidManifest.xml的拉起页面activity标签中添加intent-filter(一般为MainActivity),配置scheme,用于浏览器中拉起
<activity
android:name=".MainActivity"
android:launchMode="singleTask">
<intent-filter>
<action android:name="android.intent.action.VIEW"/>
<category android:name="android.intent.category.DEFAULT"/>
<category android:name="android.intent.category.BROWSABLE"/>
<data android:scheme="XINSTALL_SCHEME"/>
</intent-filter>
</activity>
如果拉起页面和启动页是同一Activity,则AndroidManifest.xml的配置如下
<activity
android:name=".MainActivity"
android:launchMode="singleTask">
<intent-filter>
<action android:name="android.intent.action.MAIN"/>
<category android:name="android.intent.category.LAUNCHER"/>
</intent-filter>
<intent-filter>
<action android:name="android.intent.action.VIEW"/>
<category android:name="android.intent.category.DEFAULT"/>
<category android:name="android.intent.category.BROWSABLE"/>
<data android:scheme="XINSTALL_SCHEME"/>
</intent-filter>
</activity>
备注: 将XINSTALL_SCHEME配置成 XInstall 为应用分配的scheme,在后台Android集成-功能集成文档中查看,格式为xi+appkey
2.2 在拉起页面中如下调用相关代码,获取 web 端传过来的动态参数
您可以在下述两种回调方法中任选一个进行实现,不同的回调方法有不同的逻辑,请选择最符合您实际场景的方法,请勿同时实现两个方法。
方法一:
public static void getWakeUpParam(Activity activity, Intent intent, XWakeUpListener wakeUpListener)
class MainActivity extends AppCompatActivity {
@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
//获取唤醒参数
XInstall.getWakeUpParam(this,getIntent(), wakeUpAdapter);
}
@Override
protected void onNewIntent(Intent intent) {
super.onNewIntent(intent);
// 此处要调用,否则App在后台运行时,会无法截获
XInstall.getWakeUpParam(this,intent, wakeUpAdapter);
}
XWakeUpAdapter wakeUpAdapter = new XWakeUpAdapter() {
@Override
public void onWakeUp(XAppData XAppData) {
//获取渠道数据
String channelCode = XAppData.getChannelCode();
//获取数据
Map<String, String> data = XAppData.getExtraData();
//通过链接后面携带的参数或者通过webSdk初始化传入的data值。
String uo = data.get("uo");
//webSdk初始,在buttonId里面定义的按钮点击携带数据
String co = data.get("co");
//获取时间戳
String timeSpan = XAppData.getTimeSpan();
}
};
@Override
protected void onDestroy() {
super.onDestroy();
wakeUpAdapter = null;
}
}
方法二:
// 该方法是getWakeUpParam的补充,调用该方法,一定会回调wakeUpListener里的回调方法,并把相关情况返回。
public static void getWakeUpParamEvenErrorAlsoCallBack(Activity activity, Intent intent, XWakeUpListener wakeUpListener)
class MainActivity extends AppCompatActivity {
@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
//获取唤醒参数
XInstall.getWakeUpParamEvenErrorAlsoCallBack(this,getIntent(), wakeUpAdapter);
}
@Override
protected void onNewIntent(Intent intent) {
super.onNewIntent(intent);
// 此处要调用,否则App在后台运行时,会无法截获
XInstall.getWakeUpParamEvenErrorAlsoCallBack(this,intent, wakeUpAdapter);
}
XWakeUpAdapter wakeUpAdapter = new XWakeUpAdapter() {
@Override
public void onWakeUpFinish(XAppData XAppData,XAppError xAppError) {
if (error == null) {
if (data != null) {
//获取渠道数据
String channelCode = XAppData.getChannelCode();
//获取数据
Map<String, String> data = XAppData.getExtraData();
//通过链接后面携带的参数或者通过webSdk初始化传入的data值。
String uo = data.get("uo");
//webSdk初始,在buttonId里面定义的按钮点击携带数据
String co = data.get("co");
//获取时间戳
String timeSpan = XAppData.getTimeSpan();
}
} else {
String errorCode = error.errorCode;
String errorMsg = error.errorMsg
}
}
};
@Override
protected void onDestroy() {
super.onDestroy();
wakeUpAdapter = null;
}
}
2.3 如果您的应用上架了应用宝,可能需要进行一些额外的配置。配置方法如下:
如果应用的启动页和拉起页面不是同一个 Activity,那么还需要完成以下两点配置:
在启动页 Activity 的
onCreate
和onNewIntent
方法中调用XInstall.saveInfoAndByLauncherActivityAndIntent()
方法:// WelcomeActivity 是启动页 class WelcomeActivity extends AppCompatActivity { @Override protected void onCreate(@Nullable Bundle savedInstanceState) { super.onCreate(savedInstanceState); // 在这里调用 XInstall.saveInfoAndByLauncherActivityAndIntent 方法 XInstall.saveInfoAndByLauncherActivityAndIntent(this, getIntent());; } @Override public void onNewIntent(Intent intent) { super.onNewIntent(intent); XInstall.saveInfoAndByLauncherActivityAndIntent(this, intent); } }
在 AndroidManifest.xml 文件中,将启动页 Activity 的
launchMode
配置为singleTask
类型:<activity android:name=".WelcomeActivity" android:launchMode="singleTask"> <intent-filter> <action android:name="android.intent.action.MAIN"/> <category android:name="android.intent.category.LAUNCHER"/> </intent-filter> </activity>
3.携带参数安装
在 APP 需要安装参数时(由 web 网页中传递过来的,如邀请码、游戏房间号等动态参数),调用XInstall.getInstallParam方法,在回调中获取参数(可重复获取)
XInstall.getInstallParam(new XInstallAdapter() {
@Override
public void onInstall(XAppData XAppData) {
//获取渠道数据
String channelCode = XAppData.getChannelCode();
//获取数据
Map<String, String> data = XAppData.getExtraData();
//通过链接后面携带的参数或者通过webSdk初始化传入的data值。
String uo = data.get("uo");
//webSdk初始,在buttonId里面定义的按钮点击携带数据
String co = data.get("co");
//获取时间戳
String timeSpan = XAppData.getTimeSpan();
// 是否为第一次获取到安装参数
boolean firstFetch = XAppData.isFirstFetch();
}
});
您可以在 Xinstall 管理后台对应的 App 内,看到所有的传递参数以及参数出现的次数,方便你们做运营统计分析,如通过该报表知道哪些页面或代理带来了最多客户,客户最感兴趣的 App 页面是什么等。具体参数名和值,运营人员可以和技术协商定义,或联系 Xinstall 客服咨询。具体效果如下图:
4.高级数据统计
SDK 会自动完成访问量、点击量、安装量、活跃量、留存率等统计工作。
4.1 注册量统计
如需统计每个渠道的注册量(对评估渠道质量很重要),可根据自身的业务规则,在确保用户完成 app 注册的情况下调用以下接口:
//用户注册成功后调用
XInstall.reportRegister();
4.2 事件统计
事件统计可以自定义埋点数据,通过埋点,可以了解到用户使用您应用的后续行为,用于评估渠道效果与价值。如:加购数、下单人数等。使用事件统计,需要先在【事件统计】页面内添加事件统计。只针对iOS和Android客户端。
调用接口时,请使用后台创建的 “事件统计ID” 作为 eventID
// 入参:事件统计ID,事件值
XInstall.reportEvent("eventID",1);
您可以设置不同事件来满足不同的业务场景,如下图所示,您可以设置充值事件,进行上报。就可以统计到总的充值设备数为32个,累积充值金额为364元
4.3 事件明细统计
除了旧有事件业务,我们还开发了事件明细统计,用来统计各个事件具体发生情况
在使用之前要现在后台管理系统中打开该事件明细统计功能,具体如下:
在开启权限之后,我们直接使用Xinstall SDK 的public static void reportEventWhenOpenDetailInfo(String var0, int var1, String var2)
方法上传单个事件的第二个详细值
// 123 为事件值
XInstall.reportEventWhenOpenDetailInfo("事件ID",123,"事件详情值(如用户名)");
最终在事件列表中可以点击查看查阅具体详情的内容
5.场景定制统计
5.1 分享统计
场景业务介绍,可到分享数据统计页面查看
分享统计主要用来统计分享业务相关的数据,例如分享次数、分享查看人数、分享新增用户等。在用户分享操作触发后(注:此处为分享事件触发,非分享完成或成功),可调用如下方法上报一次分享数据:
具体调用如下
// 入参:填写分享人或UID
XInstall.reportShareByXinShareId("填写分享人或UID");
注:分享人或UID 可由您自行定义,只需要用以区分用户即可
您可在 Xinstall 管理后台 对应 App 中查看详细分享数据报表,表中的「分享人/UID」即为调用方法时携带的参数,其余字段含义可将鼠标移到字段右边的小问号上进行查看:
四、导出apk包并上传
- 代码集成完毕后,需要导出安装包上传 XInstall 后台,XInstall 会自动完成所有的应用配置工作。
- 上传完成后即可开始在线模拟测试,体验完整的App安装/拉起流程;待测试无误后,再完善下载配置信息。
下面是apk包的上传界面(后台截图):