扫一扫,手机查看更快捷

LOTUSEED帮助文档

Android & iOS & WinPhone & Html5 SDK集成指南

  • Android
  • iOS WinPhone Html5

    Lotuseed Android SDK 集成指南

    一、综述

    Lotuseed Analytics帮助移动应用开发者解决用户/终端数据收集至数据标准化分析的全部繁琐问题,以可视化数据报表的形式辅助开发者更好的精细化运营移动应用产品。

    1.适用范围:

    SDK适用于Native方式开发的Android1.6(API Level4)及以上的设备应用。
    Unity 3D & Cocos2D-x请自行二次封装或使用Lotuseed的专用插件版本。

    2.统计标准:

    新增用户:
    新用户是指启动了手机应用的用户,而不是仅仅安装了应用的用户。
    应用启动:
    用户从打开应用界面至离开应用界面的完整过程,如果用户在离开应用界面后30 秒内重新回到应用中,将被认为是上次应用被打扰后的延续,记为一次完整启动。
    活跃用户:
    活跃用户是指在指定时间段至少启动了应用一次的用户。
    留存用户:
    指新增用户在指定时间段且单位时间内连续访问的用户比例。
    回访用户:
    指新增用户在指定时间段某单位时间内有访问过的用户比例。

    二、接入流程

    STEP 1、为应用申请 APP KEY

    进入http://www.lotuseed.com网站,使用您的注册账号登录后,请预先创建一款Android(应用)产品,您将获得一串编码后的APP KEY,用于唯一标识您的一款应用。

    STEP 2、向工程中导入追踪SDK

    1.登录Lotuseed Web下载SDK,带apk更新功能SDK请注意勾选"App更新升级功能"后提交下载;

    2.解压SDK,并将其中的libs目录和res目录(如存在)一并解压到Adnroid工程目录下;
    3.Eclipse用户右键您的工程根目录,按F5刷新工程,然后再选择 Properties --> Java Build Path --> Libraries → 点击Add External JARs...找到本地目录下的Lotuseed SDK jar 文件,点击 打开按钮即可成功导入。

    STEP 3、配置AndroidManifest.xml

    SDK需要获取适当的权限才可以正常工作,开发者需要在AndroidManifest.xml里边添加下表列举出来的权限申明。另外,SDK会读取application的meta-data来获取当前应用的标识 LOTUSEED_APPKEY 和分包渠道标识 LOTUSEED_CHANNEL,对应的meta-data的名字也见下表。

    注:如果开发者不希望通过AndroidManifest.xml配置LOTUSEED_APPKEY和LOTUSEED_CHANNEL,也可以通过"STEP 4、添加SDK初始化代码(可选)"步骤描述的方法来通过API调用来传入这些信息。

    所需权限 用途说明
    android.permission.INTERNET 允许SDK联网和发送统计数据的权限。
    android.permission.ACCESS_NETWORK_STATE 允许SDK检测网络连接状态,在网络异常状态时避免数据发送,节省电量。
    android.permission.READ_PHONE_STATE(建议) 允许SDK获取IMEI和运营商信息。
    android.permission.WRITE_EXTERNAL_STORAGE(可选) 使用应用更新辅助功能时,添加该权限可使apk保存到SD卡。
    Meta-data 用途说明
    LOTUSEED_APPKEY 该值为您在Lotuseed WEB上创建应用时获得的APPKEY,用于在LOTUSEED统计平台上唯一标识您的app。
    LOTUSEED_CHANNEL 用于标注app的推广渠道,区分app的获取来源。
    Receiver(可选) 用途说明
    <receiver
    android:name="com.lotuseed.android.PackageReceiver"
    <intent-filter>
    <action android:name="android.intent.action.PACKAGE_REMOVED" />
    <action android:name="android.intent.action.PACKAGE_REPLACED" />
    <data android:scheme="package" />
    </intent-filter></receiver>
    该Receiver用于获取app更新标志,此标志可区分出新激活设备与导入设备。
    其他配置(可选) 用途说明
    <activity
    android:label="@string/app_name"
    android:name="com.lotuseed.android.UpdateNotifyActivity"
    android:theme="@android:style/Theme.Translucent" />
    使用应用更新辅助功能时,添加的activity用于更新提醒。

    最终的AndroidManifest.xml 示例如下:

    <?xml version="1.0" encoding="utf-8"?>

    <manifest ......>

    ......

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

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

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

    <application ......>

    <activity ....../>

    <receiver

    android:name="com.lotuseed.android.PackageReceiver"

    <intent-filter>

    <action android:name="android.intent.action.PACKAGE_REMOVED" />

    <action android:name="android.intent.action.PACKAGE_REPLACED" />

    <data android:scheme="package" />

    </intent-filter>

    </receiver>

    <meta-data android:name="LOTUSEED_APPKEY" android:value="Your_APPKEY" />

    <meta-data android:name="LOTUSEED_CHANNEL" android:value="Your_CHANNEL" />

    </application>

    </manifest> 

    STEP 4、添加SDK初始化代码(可选)

    接口定义

    //可选,为SDK设置Context,并立即产生激活设备的数据

    public static void init(final Context context);

    //可选,代码设置APPKEY &CHANNEL,同时在AndroidManifest.xml设置APPKEY &CHANNEL时,则已代码中设置的值为准

    public static void startWithAppKey(final String appKey, final String channel);

    参数说明

    参数 类型 描述
    context Context 当前app的Context对象实例。
    appKey String Lotuseed Web上获取的APPKEY
    channel String 自定义的分包渠道标识 。

    实例代码

    @Override protect void onCreate (){

    super.onCreate();

    Lotuseed.init(this);

    Lotuseed.startWithAppKey(YOUR_APPKEY, YOUR_CHANNEL);

    }

    注:
    1.初始化代码需添加在应用主入口Activity的onCreate方法内;(请勿添加在Application子类内,防止多进程时产生多Lotuseed实例而影响启动次数的准确性)
    2.如果未调用init接口,SDK有可能无法获取到Context对象,此时应注意Logcat错误日志提示。

    STEP 5、添加调用方法

    参见"添加方法"一节。

    STEP 6、进行数据测试

    集成完毕并打包后,请以真机测试并查验Lotuseed WEB输出报表,以确保SDK集成的正确。

    三、添加方法

    所有方法请勿添加在Application子类内,防止多进程时产生多Lotuseed实例而影响启动次数和启动时长的准确性;
    所有方法请在SDK初始化代码后进行调用(如果存在SDK初始化代码);

    1.应用启动和关闭

    接口说明
    用于准确跟踪应用的打开次数,使用时长等信息;
    您需要在app的每个Activity的onResume和onPause方法里添加对于Lotuseed API的调用;
    如果所有Activity都继承同一个基类,只需要在基类中添加调用,子 Activity;
    注意:添加onResume, onPause是应用次数/时长控制的关键,未正确添加会影响到多数统计数据,所以务必需要正确添加。
    接口定义

    public static void onResume(final Context context);

    public static void onPause(final Context context);

    参数说明

    参数 类型 描述
    context Context 当前Activity的对象示例。

    示例代码

    @Override protect void onResume (){

    super.onResume();

    Lotuseed.onResume (this);

    }

    @Override protect void onPause (){

    super.onPause();

    Lotuseed.onPause(this);

    }

    2.使用错误报告

    接口说明
    用于捕捉应用程序内未导致crash的错误日志,辅助开发者进行错误定位;
    应用程序存在多个MAIN入口Activity时,请在每个入口Activity的onCreate方法内添加Lotuseed.onCrashLog()方法;
    接口定义

    //自动提交错误

    public static void onCrashLog();

    //手动提交错误

    public static void onCustomLog(String logmsg);

    参数说明

    参数 类型 描述
    logmsg String 提交的调试日志信息

    实例代码
    1.自动提交onCrash Log :

    @Override protect void onCreate (){

    super.onCreate();

    Lotuseed.init(this); //可选

    Lotuseed.startWithAppKey(YOUR_APPKEY, YOUR_CHANNEL);  //可选

    Lotuseed.onCrashLog(); //使用自动提交错误报告

    }

    2.手动提交onCustomLog:

    Lotuseed.onCustomLog("我的错误信息");

    3.统计自定义页面

    接口说明
    1.onResume和onPause接口用于统计Activity的起停,如需统计webView或其他中间件(如PhoneGap、WRP等)则可以通过onPageViewBegin和onPageViewEnd进行统计;
    这两个api需配对使用,参数pageName用于标识页面名称;另外下一个onPageViewBegin需在前一个onPageViewEnd后调用。
    接口定义

    //页面起始
    public static void onPageViewBegin(final String pageName);
    //页面结束
    public static void onPageViewEnd(final String pageName);

    参数说明

    参数 类型 描述
    pageName String 提交的调试日志信息

    4.发送自定义事件

    接口说明
    除了基本统计分析功能外,我们还支持您自定义的事件分析,例如您可以统计游戏中通过不同关卡的人数,广告的点击次数或者视频被播放的次数等等。
    事件数量统计
    接口定义

    //默认使用智能发送策略模式接口

    Lotuseed.onEvent(String eventID);

    Lotuseed.onEvent(String eventID, long count);

    Lotuseed.onEvent(String eventID, String label);

    Lotuseed.onEvent(String eventID, String label,long count);

    Lotuseed.onEvent(String eventID, Map<String, String> map);

    Lotuseed.onEvent(String eventID, Map<String, String> map, long count);

    //带实时发送参数immediately接口

    Lotuseed.onEvent(String eventID, boolean immediately);

    Lotuseed.onEvent(String eventID, long count, boolean immediately);

    Lotuseed.onEvent(String eventID, String label, boolean immediately);

    Lotuseed.onEvent(String eventID, String label, long count, boolean immediately);

    Lotuseed.onEvent(String eventID, Map<String, String> map, boolean immediately);

    Lotuseed.onEvent(String eventID, Map<String, String> map, long count, boolean immediately);

    参数说明

    参数 类型 描述
    eventID String Lotuseed Web上获取的APPKEY
    count long 事件本地累计数。 当大量重复事件发生时,为减少网络流量,建议程序中先本地计算累计数count值。
    label String 事件的一个属性描述 。
    map Map<String, String> 为当前事件的属性和取值集合(key-value)。
    immediately boolean 实时发送开关,true为实时发送。
    channel String 自定义的分包渠道标识 。

    事件时长统计
    接口定义

    //默认使用智能发送策略模式接口

     

    Lotuseed.onEventDuration(String eventID, long duration);

    Lotuseed.onEventDuration(String eventID, String label, long duration);

    Lotuseed.onEventDuration(String eventID, Map<String, String> map, long duration);

     

    //带实时发送参数immediately接口

    Lotuseed.onEventDuration(String eventID, long duration, boolean immediately);

    Lotuseed.onEventDuration(String eventID, String label, long duration, boolean immediately);

    Lotuseed.onEventDuration(String eventID, Map<String, String> map, long duration, boolean immediately);

    参数说明

    参数 类型 描述
    eventID String 为当前统计的事件ID。
    duration long 时长,单位:毫秒。
    label String 事件的一个属性描述。
    map Map<String, String> 为当前事件的属性和取值集合(key-value)。
    immediately boolean 实时发送开关,true为实时发送。

    注意:lotuseed除激活和app启动事件外,其他所有事件默认采用智能批量发送策略。

    四、辅助功能

    添加apk智能更新功能
    接口说明
    Lotuseed独有的智能增量更新算法,保障终端用户在更新您的应用软件时最大程度节约流量,减少下载等待时间(优化幅度平均达到原来apk包体大小的10-20%,极限情况下可以节约流量95%以上),推荐使用。
    接口定义

    //自动更新提醒

    public static void tryUpdateSlient();

    //手动尝试更新

    public static void tryUpdateManual();

    示例代码
    自动更新提醒

    @Override protect void onCreate (){

    super.onCreate();

    Lotuseed.init(this); //可选

    Lotuseed.startWithAppKey(YOUR_APPKEY, YOUR_CHANNEL);  //可选

    Lotuseed.tryUpdateSlient(); //使用自动更新提醒

    }

    手动尝试更新

    代码中调用Lotuseed.tryUpdateManual();

    备注说明

    配置AndroidManifest.xml:

    <activity

                android:label="@string/app_name"

                android:name="com.lotuseed.android.UpdateNotifyActivity"

                android:theme="@android:style/Theme.Translucent" >

       </activity>

    在线参数配置功能
    接口说明
    1.在线参数配置功能主要用于解决在不更新升级apk的情况下通过云端下发参数值而改变app的逻辑,如彩蛋功能;
    2.通过Lotuseed Web云端配置key-value键值对。 value可以是一个字符串,也可以是一个文件下载URL;key,value支持中文字符编码;如果参数是一个文件,SDK负责自动文件下载实现;
    3.updateOnlineConfig()更新在线参数,getConfigParams()获取在线参数。

    接口定义

    //更新在线参数

    public static void updateOnlineConfig();

    //通过key获取在线参数

    public static void getConfigParams(final String key, String defaultValue);

    参数说明

    参数 类型 描述
    key String 获取参数的key
    defaultValue String 未获取到时的默认值 。

    如何使用
    在SDK初始化代码后添加:
    Lotuseed.updateOnlineConfig();
    程序内获取参数方法如下:
    String param = Lotuseed.getConfigParams("key", "defaultValue"); //如果是文件参数,则该方法返回本地文件名;

    五、集成检查列表

    1.AndroidManifest.xml里申明了必要的权限,并检查是否填入了正确的LOTUSEED_APPKEY和LOTUSEED_CHANNEL;
    2.确保全部Activity页面中调用了onResume、onPause接口;
    3.检查应用日志中是否有"请确保APP初始化时首先在UI主线程调用了SDK的init()接口,然后再调用其他接口!"之类的信息,有则说明SDK没有正确初始化;
    4.如果使用了带有更新升级功能的SDK,请确保libs/armeabi/libpatch-jni.so和res目录正确的解压到android工程目录下;

    六、特别说明

    1.所有方法请勿添加在Application子类内,防止多进程时产生多Lotuseed实例而影响启动次数和启动时长的准确性;
    2.Lotuseed SDK默认为RELEASE模式,如果调试则请在SDK初始化代码后调用:Lotuseed. setDebugMode(true);
    3.SDK默认统计数据发送策略:
    a.debug模式时实时发送数据;
    b.realease模式时session启动事件数据实时发送(包括历史session所有缓存数据);
    d.缓存数据量达上限时会触发发送统计数据;
    e.SDK会尽可能尝试在当前session超时时发送所有缓存数据;
    4.SDK默认获取位置信息,但LBE等安全防护软件会自动拦截告警,若需关闭则在程序入口Activity的onCreate方法内添加以下语句:
      Lotuseed.setReportLocation(false);
    5.Lotuseed SDK更新升级时默认使用应用内的缓存空间,若需使用TCard空间,则请:
    a.需要配置android.permission.WRITE_EXTERNAL_STORAGE权限;
    b.SDK初始化代码后调用 Lotuseed. setUpdateUseCache(false);

    七、FAQ

    1.为何安装了好几次应用,设备激活量没有变化?
    答:同一台设备反复卸载和安装应用不会记录多次设备激活;如果是在多个设备上打开的应用,请稍后刷新一下页面,查看激活数据是否变化。
    2.为何测试渠道包时,渠道数据报表中没有任何数据?
    答:请确认是否是在同一台设备上在卸载和安装渠道包进行测试,每台设备只被记录到初装渠道,更换渠道包不会产生新的激活量; 测试每个渠道包时请使用一台没测试过的设备进行。

    八、渠道打包工具

    1.环境要求
    eclipse3.X以上版本,安装有android SDK和android ADT较新版本;
    2.下载插件
    首先登录www.lotuseed.com 下载eclipse多渠道打包插件,文件名类如:com.lotuseed.multi-channels_1.0.0.201208031844.jar
    3.安装插件
    拷贝下载到的jar文件到eclipse的plugins目录下,如有旧版本则先删除,然后重启eclipse即可;
    4.渠道打包


    如上图,在anroid工程上右键选择Lotuseed Tools-->Export Signed Multi-channel Application package...,点击进入多渠道打包


    向导操作过程前面几步与Android Tools-->Export Signed Application package...过程一致,而在最后一步进行渠道选择后进行批量打包,向导界面如下:


    上图示例上点击Finish后打包生成Astro_01.apk, Astro_02.apk, Astro_03.apk, Astro_05.apk, Astro_17.
    apk;每个文件分别对应一个渠道;选择的渠道列表会登记到工程目录下的"lotuseed.channels" 文件内,下次打包时会自动导入历史记录;示例工程Astro lotuseed.channels格式如下:
    01, 02, 03, 05, 17
    也可按格式要求手工编辑该文件进行渠道选择操作。

    九、技术支持

    QQ:835371627
    email:support@lotuseed.com
    我们会尽快回复您的意见或建议。

    • 帮助中心

      查阅文档、提交问题工单、搜索故障的解决方案,都可以前往帮助中心

      前往帮助中心 >
    • 销售咨询

      销售经理为您解答企业版 LOTUSEED 报价、部署实施方案的各种问题。

      support@lotuseed.com
    • 技术支持

      使用 LOTUSEED 时,遇到任何技术上的问题,都可以发送邮件给我们。

      support@lotuseed.com