量江湖 SDK Android 集成文档

概要

量江湖 SDK是移动应用推广效果跟踪工具，主要用于App推广过程中的新增(激活)用户统计，结合后端的防作弊平台，给开发者提供正常与异常激活用户的反馈。

请仔细对照文档集成，如有疑问请联系：

技术支持：QQ群 475600268，邮件 userclear@lbadvisor.net

更新说明

2017-03-28 优化数据存储，修复了已知 bug
2016-11-21 修复已知问题，性能优化，增强稳定性
2016-06-03 提高网络传输效率，修复已知bug
2016-04-29 Android6.0支持：替换 Apache的HttpClient为java.net.URLConnection及解决6.0设备信息采集问题，修复 bug
2016–03-09 修复了个别机型或特定场景下因应用权限导致的BUG，增强稳定性
2015-12-30 增加集成测试，修复bug，增强稳定性
2015-11-02 完善SDK,增加稳定性
2015-10-14 增加自定义页面和自定义事件统计，bug修复，增加稳定性
2015-07-28 增加调试模式，开发者自助检测是否成功集成SDK
2015-07-13 发布Beta版本

1. 获取AppKey

集成量江湖 SDK之前，请首先到量江湖官网注册并添加新应用，获取AppKey

2. 下载SDK

请联系量江湖技术支持

3. 集成步骤

3.1导入SDK

3.1.1 Eclipse

将下载包解压后的userclearX.X.X.jar文件拷贝到本地工程libs子目录下；在Eclipse中右键工程根目录，选择Properties -> Java Build Path -> Libraries，然后点击Add External JARs... 选择指向jar的路径，点击OK，即导入成功。

3.1.2 Android Studio

将下载包解压后的userclearX.X.X.jar文件拷贝到$PROJECT/app/libs目录下，并且在$PROJECT/app/build.gradle 文件中有如下定义：

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
}

3.2 配置清单AndroidManifest.xml

3.2.1示例代码

manifest的配置主要包括添加权限、填写Appkey和填写渠道id三部分

<uses-permission android:name="android.permission.INTERNET" />    
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.GET_TASKS" />
<--注：如果想统计设备更多准确信息，建议加入以下权限-->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<--量江湖渠道统计-->
<application ...>
    <meta-data android:name="USERCLEAR_APPKEY" android:value="Your_App_KEY" />
    <meta-data android:name="USERCLEAR_CHANNEL" android:value="Channel_ID"/>
</application>

3.2.2 填写AppKey

将上面示例代码中"Your_App_KEY" 替换为您应用真实的APPKEY(通过第一步获取)

3.2.3 填写渠道

将上面示例代码中"Channel_ID"替换成您想统计的渠道，Channel_ID可自定义

渠道命名规范

1.可以由英文字母、阿拉伯数字、下划线组成，禁止使用中文命名

2.不要使用纯数字作为渠道ID

3.首尾字符不可以为空格

4.最多100个字符

示例代码：

<meta-data android:name="USERCLEAR_APPKEY" android:value="567a83cb67e58e67fe000"/>
<meta-data android:name="USERCLEAR_CHANNEL" android:value="WANDOUJIA" />

以上这种清单文件配置的方式适合多渠道打包。您可以使用 Gradle实现多渠道打包，点击这里。

如果不想在清单文件中配置APPKEY与CHANNEL,可通过代码配置

UserClear.init(final Context context,String appkey,String channel)

只需在程序入口处调用即可，强烈建议在Application的onCreate里调用,以免发生崩溃

非常重要：每台设备仅记录首次安装激活的渠道，如果该设备再次安装其他渠道包，则数据仍会被记录在初始的安装渠道上。所以在测试不同的渠道时，请使用不同的设备来分别测试

3.3 代码集成

3.3.1 session的统计

正确集成如下代码，才能够保证获取正确的新增激活用户数据。

在每个Activity的onResume方法中调用 UserClear.onResume(Context), onPause方法中调用 UserClear.onPause(Context)

注意:如果你的Activity之间有继承关系，请不要同时在父Activity和子Activity中重复调用onResume和onPause方法，可能会造成重复统计，造成启动次数异常

    import com.lbadvisor.userclear.UserClear;
    public class MainActivity ... {
        public void onResume() {
            super.onResume();
            UserClear.onResume(this);
        }
        public void onPause() {
            super.onPause();
            UserClear.onPause(this);
        }    
    }

当应用在后台运行超过30S再回到前端时，例如打开应用返回桌面，再进入另一个应用超过30S返回本应用时，默认是两个独立的session启动，相当于应用第二次启动，如果想自定义间隔，可通过如下代码

UserClear.setSessionContinueMillis(long interval)//单位为毫秒

3.3.2 代码混淆

如果你的应用使用了混淆，请添加

-keep public class com.lbadvisor.userclear.engine.UserClear { *;}

使得混淆的时候不会影响统计SDK的命名空间

4. 测试与调试

4.1 确认如下内容

确认已添加所需权限：INTERNET, READ_PHONE_STATE,ACCESS_WIFI_STATE 等
确认在 AndroidManifest.xml 已正确配置 USERCLEAR_APPKEY
确认入口的 Activity 中调用了 onResume 和 onPause 方法
确认手机或模拟器的网络连接正常

4.2 调试模式

使用调试模式，请在程序入口添加以下代码：

UserClear.setDebugMode(true);

启动App后，请确保在logcat日志中看到“Send msg success!”的字样，说明SDK成功集成。

正式打包时请关闭调试模式。

4.3 集成测试(推荐使用)

什么是集成测试？集成测试是通过收集和展示已注册测试设备发送的日志，来检验SDK集成有效性和完整性的一个服务。所有由注册设备发送的应用日志将实时地进行展示，提升集成与调试的工作效率。

注意：使用集成测试之后，所有测试数据不会进入应用正式的统计后台，只能通过API查看，您不必再担心因为测试而导致的数据污染问题，让数据更加真实有效的反应用户使用情况。

4.3.1 添加一个测试设备

Unix系统

export APPKEY=567a83cb78e58e67fe000996
export DEVICE_ID=a7da092187a80320439d5383740e300bfb69891d
curl -XPOST https://sdk.lbadvisor.com/debug/v2/config/android/$APPKEY/$DEVICE_ID

Windows系统

请从以下地址下载curl，解压到本地目录 C:\PATH\TO\CURL http://winampplugins.co.uk/curl/

cd C:\PATH\TO\CURL
set APPKEY=567a83cb78e58e67fe000996
set DEVICE_ID=a7da092187a80320439d5383740e300bfb69891d
curl -XPOST https://sdk.lbadvisor.com/debug/v2/config/android/%APPKEY%/%DEVICE_ID%

其中：

APPKEY通过第一步获取的APPKEY替换

DEVICE_ID的获取需打开调试模式，会输出以下日志

12-31 20:32:03.150 11877-11877/com.lbadvisor.userclear.sample I/UserClear: UserClear_Device_id a7da092187a80320439d5383740e300bfb69891d

将UserClear_Device_id后面字符串拷贝，然后替换上面的DEVICE_ID

4.3.2 删除一个测试设备

Unix系统

curl -XPOST https://sdk.lbadvisor.com/debug/v2/config/android/$APPKEY/$DEVICE_ID?delete=true

Windows系统

curl -XPOST https://sdk.lbadvisor.com/debug/v2/config/android/%APPKEY%/%DEVICE_ID%?delete=true

其中appkey与device_id同添加一个设备的接口一致，唯一的区别是增加了delete参数，如果要删除该设备请将该参数置为true

4.3.3 如何查询DEBUG日志

Unix系统

export OFFSET=0
export LIMIT=10
curl "https://sdk.lbadvisor.com/debug/v2/log_list?appkey=$APPKEY&device_id=$DEVICE_ID&from=$OFFSET&size=$LIMIT"

# 也可以把URL打印出来，粘贴到浏览器中访问
echo "https://sdk.lbadvisor.com/debug/v2/log_list?appkey=$APPKEY&device_id=$DEVICE_ID&from=$OFFSET&size=$LIMIT"

Windows系统

set OFFSET=0
set LIMIT=10
curl "https://sdk.lbadvisor.com/debug/v2/log_list?appkey=%APPKEY%&device_id=%DEVICE_ID%&from=%OFFSET%&size=%LIMIT%"
# 也可以把URL打印出来，粘贴到浏览器中访问
echo "https://sdk.lbadvisor.com/debug/v2/log_list?appkey=%APPKEY%&device_id=%DEVICE_ID%&from=%OFFSET%&size=%LIMIT%"

其中appkey与device_id同添加一个设备的接口一致，增加的是from和size两个参数，默认值分别为0，10，按时间倒序进行排序。