Android SDK 集成指南

集成引言

在集成openinstall SDK之前,请您仔细阅读本引言内容。引言内容对您的App上架应用市场参数还原精度等众多方面有很大的帮助!
1、为了保证您这边的App能正常上架各大应用市场,请在App的《隐私政策》中加入openinstall SDK需要获取的数据、用途以及使用范围,详细内容可以参考官网文档中的《合规指南》。确保用户同意App的《隐私政策》之后,再进行openinstall SDK初始化;如果用户不同意,则不进行openinstall SDK初始化。
2、请仅在主进程的UI线程中调用初始化接口,多进程调用将会导致获取参数失败,统计数据异常。
3、在初始化和获取参数接口(getInstall)调用时,尽量保证不要有权限申请或其它可能使应用处于后台不可见状态的操作,否则会影响参数还原的精度。
4、请在调用初始化接口后再调用其他接口,否则会导致早于初始化接口调用的接口执行失败。

一、下载并导入 SDK

下载中心下载 Android 最新版本 SDK
从下载的文件中,将 jar 文件拷贝到项目的libs文件夹中,并使用 gradle 导入

    implementation files('libs/OpenInstall_vX.X.X.jar')

或者导入libs目录中所有 jar 文件

    implementation fileTree(dir: 'libs', include: ['*.jar'])

如果“下载配置”中的下载地址配置的是应用的Google Play地址,则可以添加以下依赖,用于提升 Google Play 商店下载时参数还原精度

implementation "com.android.installreferrer:installreferrer:2.2"

二、初始化

AndroidManifest.xml中添加权限声明

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

AndroidManifest.xmlapplication标签内设置AppKey

<meta-data
    android:name="com.openinstall.APP_KEY"
    android:value="OPENINSTALL_APPKEY"/>

备注:将OPENINSTALL_APPKEY替换成 openinstall 为应用分配的appkey

App 启动时,请调用 SDK 初始化接口进行初始化

/*
 调用初始化时请注意:
 1. 首次启动,确保用户同意《隐私政策》之后,再初始化openinstall SDK;
 2. 仅在主进程的UI线程中调用初始化接口,多进程调用将会导致获取参数失败,统计数据异常;
 3. 初始化调用时,尽量保证应用处于前台可触控状态下,对提升参数还原精度有很大的帮助。
 */
OpenInstall.init(context);

注意:SDK初始化时,默认会读取剪切板,经验证后仅向服务端上传openinstall js SDK写入剪切板的网页参数。剪切板方案能有效地提高参数还原准确率,提高统计精度。如果您确定不使用剪切板方案来提升参数还原准确率,则可以在代码中直接关闭SDK对剪切板的读取(同时推荐使用【Android下载配置】的【高精度安装包】下载方式来保证参数还原准确率)。

OpenInstall.clipBoardEnabled(false); //false为不读取,true为读取
OpenInstall.init(context);

开发者也可以自行获取剪切板数据后使用以下API自行将剪切板内容传入SDK,此时SDK也不会读取剪切板内容(传入前会先判断剪切板内容是否为openinstall js SDK写入的,如果不是则不传入)。

ClipData clipData = clipboardManager.getPrimaryClip();
if (OpenInstallHelper.isTrackData(clipData)) {
    OpenInstall.setTrackData(clipData);
}else {
    OpenInstall.setTrackData(null);
}
OpenInstall.init(context);

三、功能集成

1. 快速安装

如果只需要快速安装功能,无需其它功能(App传参安装、渠道统计、一键拉起),完成初始化即可

2. 一键拉起

2.1 在AndroidManifest.xml的拉起页面activity标签中添加intent-filter(一般为MainActivity),配置scheme,用于浏览器中拉起

<activity
    android:name=".MainActivity"
    android:exported="true"
    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="OPENINSTALL_SCHEME"/>
    </intent-filter>
</activity>

如果拉起页面和启动页是同一Activity,则AndroidManifest.xml的配置如下

<activity
    android:name=".MainActivity"
    android:exported="true"
    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="OPENINSTALL_SCHEME"/>
    </intent-filter>
</activity>

备注:将OPENINSTALL_SCHEME配置成 openinstall 为应用分配的scheme

2.2 在拉起页面中如下调用相关代码,获取 web 端传过来的动态参数

public class MainActivity extends Activity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        //获取唤醒参数
        OpenInstall.getWakeUp(getIntent(), wakeUpAdapter);
    }
    @Override
    protected void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        // 此处要调用,否则App在后台运行时,会无法截获
        OpenInstall.getWakeUp(intent, wakeUpAdapter);
    }
    AppWakeUpAdapter wakeUpAdapter = new AppWakeUpAdapter() {
        @Override
        public void onWakeUp(AppData appData) {
            //获取渠道数据
            String channelCode = appData.getChannel();
            //获取绑定数据
            String bindData = appData.getData();
            Log.d("OpenInstall", "getWakeUp : wakeupData = " + appData.toString());
        }
    };
    @Override
    protected void onDestroy() {
        super.onDestroy();
        wakeUpAdapter = null;
    }
}

2.3 从微信/QQ直接打开App并且还原拉起参数,请启用“集成应用宝”开关(在“Android集成”-“Android下载配置”页面配置),并在申请开通应用宝Applink功能后按照文档内容集成对应的配置

3. App传参安装高级版功能

3.1 在 App 需要安装参数时(由 web 网页中传递过来的,如邀请码、游戏房间号等动态参数),调用OpenInstall.getInstall方法,在回调中获取参数(可重复获取)

/*
  获取安装参数时请注意
  1. 不要在初始化之后,紧接着调用,容易导致获取数据失败;
  2. 在业务需要时再获取数据,保证SDK有充足的时间进行数据还原;
  3. 不要在返回AppData为空时,尝试使用此api进行重试获取数据。
 */
OpenInstall.getInstall(new AppInstallAdapter() {
    @Override
    public void onInstall(AppData appData) {
        //获取渠道数据
        String channelCode = appData.getChannel();
        //获取自定义数据
        String bindData = appData.getData();
        Log.d("OpenInstall", "getInstall : installData = " + appData.toString());
    }
});

此方法获取初始化成功后存储在本地的数据,除非是网络请求超时,否则重复调用返回数据相同

4. 渠道统计高级版功能

SDK 会自动完成访问量、点击量、安装量、活跃量、留存率等统计工作。

4.1 注册量统计
如需统计每个渠道的注册量(对评估渠道质量很重要),可根据自身的业务规则,在确保用户完成 App 注册的情况下调用以下接口:

//用户注册成功后调用
OpenInstall.reportRegister();

4.2 渠道效果统计
效果点建立在渠道基础之上,主要用来统计终端用户对某些特殊业务的使用效果,如充值金额,分享次数等等。

调用接口前,请先进入管理后台“效果点管理”中添加效果点

效果点管理

调用接口时,请使用后台创建的 “效果点ID” 作为pointId

OpenInstall.reportEffectPoint(pointId, pointValue);

调用接口后,可在后台查看效果点统计数据

四、导出apk/ipa包并上传

  • 代码集成完毕后,需要导出安装包上传openinstall后台,openinstall会自动完成所有的应用配置工作。
  • 上传完成后即可开始在线模拟测试,体验完整的App安装/拉起流程;待测试无误后,再完善下载配置信息。

下面是apk包的上传界面(后台截图):

上传安装包