Android SDK 使用说明

1. 集成SDK

导入SDK有以下两种方法，选择其中一种即可 。

1.1 Gradle 编译环境（Android Studio）

在Gradle依赖中添加：

    // 添加依赖
    dependencies {
        ......
        // 云图SDK，选择release分支
        compile "com.nd.android:cloud-atlas:1.3.4.11.release"
        ......
    }

如果无法正常集成请添加如下代码 ：

allprojects {
    repositories {
            mavenCentral()     
    }
}

SDK数据上报规则

  • 应用退到后台，超过15s后回到前台时触发

  • 用户登录/注销时上传（相同用户重复登录是不会触发上传的）

  • 每采集5/100条数据（包括事件，错误）则上传

  • 定时120s默认上传本地所有数据（后台可配置上传时间）

  • 应用退到后台时则立即触发上数

上述上报规则任意一个条件达到即会立即上传数据

1.2 SDK手动集成（采用aar文件方式）

1.2.1 SDK下载

下载统计SDK 并解压缩。

1.2.2 集成SDK

将下载包中的libs 文件夹合并到本地工程libs子目录下；在Eclipse中右键工程根目录，选择Properties -> Java Build Path -> Libraries，然后点击Add External JARs... 选择指向jar的路径，点击OK，即导入成功。（ADT17及以上不需要手动导入）

注意：必须配置混淆方式 
-keep classcom.nd.cloudatlas.* {*;}

2. 基本功能集成

2.1 配置基础属性

2.1.1 配置manifest

manifest的配置主要包括添加权限，以下权限缺一不可，填写Appkey和填写渠道id三部分，代码示例如下：

<manifest……>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.VIBRATE" />
<application ……>
……
<activity ……/>
<meta-data android:value="YOUR_APP_KEY" android:name="CLOUD_ATLAS_APP_KEY"></meta-data>
<meta-data android:value="YOUR_CHANNEL_ID" android:name="CLOUD_ATLAS_CHANNEL_ID"></meta-data>
</application>    
</manifest>

2.1.2 权限说明

权限 用途
ACCESS_NETWORK_STATE 检测联网方式，区分用户设备使用的是2G、3G或是WiFi
INTERNET 允许应用程序联网，以便向我们的服务器端发送数据
VIBRATE 允许程序振动，用于可视化埋点采集屏幕快照信息

2.1.3 填写AppKey

将 <meta-data android:value="YOUR_APP_KEY " android:name="CLOUD_ATLAS_APP_KEY"></meta-data> 中的YOUR_APP_KEY 替换为您在云图项目组中申请的应用AppKey。（Appkey可在统计后台的 设置->基本信息 页面查看），其他部分均不需改动。

2.1.4 填写ChannelId

特别注意：当前云图Android端渠道配置统一已应用工厂的多渠道配置工具为主，如在云图的业务组件上已有渠道配置将以云图业务组件配置的渠道优先使用。请各位配置、开发同学注意此问题。

选填项,默认为Default

将 <meta-data android:value="YOUR_CHANNEL_ID" android:name="CLOUD_ATLAS_CHANNEL_ID"></meta-data> 中的YOUR_CHANNEL_ID 替换为您定义的渠道ID。

ChannelId的命名规则：

1.首尾字符不可以为空格，当首尾出现空格时将会自动过滤空格

2.不要使用纯数字或者纯数字和空格混合的字符作为渠道ID

3.最多200个字符，当渠道ID多于200字符时将自动截断

4."unknown" 和"app store" 及其各种大小写形式，作为云图保留的字段，不可以作为渠道名

2. 接入SDK

2.1 SDK初始化

在应用初始化时（如 Application 中），调用 CloudAtlas.init(Context, boolean) 方法初始化云图SDK。 初始化时，可以指定是否使用调试模式。在调试模式下,云图出现异常时会抛出。

public class CustomApplication extends Application {
    @Override
    public void onCreate() {
       super.onCreate();
        ...
        //CloudAtlas.switchEnv(FORMAL); // 设置云图的数据上传环境，环境参数：生产环境（FORMAL），：预生产环境（PRE_FORMAL），集成环境（INTEGRATION），默认生产环境(FORMAL)
        CloudAtlas.setLogEnabled(true); // 输出云图日志
        CloudAtlas.setUploadStrategy(UploadStrategy.UPLOAD_BY_INTERVAL);//设置数据上传策略，默认为启动时上传
        CloudAtlas.setFlushBulkSize(50); // 设置本地缓存日志的最大条目数，当达到这个值会触发上传数据
        CloudAtlas.setFlushInterval(30*1000);//定时上传数据的间隔，仅策略为定时上传时有效
        CloudAtlas.init(this, false);
        ...
    }
}

2.2 带有Appkey的初始化

在某些情况下不能在manifest配置Appkey，SDK（1.2.24版本之后）提供带有Appkey的初始化接口。

    /**
     * 初始化
     *
     * @param context     上下文对象
     * @param appkey      应用appkey
     * @param isDebugMode true-调试模式，false-非调试模式
     */
    public static void initWithAppkey(Context context, String appkey, boolean isDebugMode){...}

如果同时在manifest中配置Appkey并且调用接口initWithAppkey，优先使用manifest中配置的Appkey。

2.3 会话的统计

在每个Activity的onResume方法中调用 CloudAtlas.onResume(Activity)，onPause方法中调用 CloudAtlas.onPause(Activity)。

如果您的Activity之间有继承或者控制关系请不要同时在父和子Activity中重复添加onPause和onResume方法，否则会造成重复统计，导致启动次数异常增高。(eg.使用TabHost、TabActivity、ActivityGroup时)。

public void onResume() {
    super.onResume();
    CloudAtlas.onResume(this);
}

public void onPause() {
    super.onPause();
    CloudAtlas.onPause(this);
}

Android 4.0以上版本

我们的SDK会自动监听每个Activity的onResume与onPause，并回调相应方法。 这样，只需要一行代码，免去了在所有Activity中加代码的麻烦。建议在Application中初始化完毕后调用。

当应用在后台运行超过15秒（默认）再回到前端，将被认为是两个独立的会话(启动)，例如用户回到home，或进入其他程序，经过一段时间后再返回之前的应用。可通过接口：CloudAtlas.setSessionContinueMillis(long interval) 来自定义这个间隔（参数单位为毫秒）。

注意：该间隔有上下限，不能小于15000（15秒），或大于3600000（1小时）


CloudAtlas.setSessionContinueMillis(20000);

2.4 账号的统计

云图在统计时，默认支持设备粒度。

如果需要统计应用自身的账号，请使用CloudAtlas.onProfileSignIn(String id)接口（目前只支持整数格式的id）：


//目前只支持整数格式的id
CloudAtlas.onProfileSignIn("89757");

当账号登出时，请使用 CloudAtlas.onProfileSignOff() 接口：


CloudAtlas.onProfileSignOff();

3. 高级功能接入

以下功能可根据项目的情况进行接入，如无详细的接入要求可暂时不接入以下功能

3.1 自定义事件的统计

自定义事件，目前支持以下四种多态方法，分别应用于不同的场景：

 /**
    * 用户定义事件
    *
    * @param id 事件Id
    */
   public static void onEvent(String id)

   /**
    * 用户定义事件
    *
    * @param id    事件Id
    * @param label 事件属性
    */
   public static void onEvent(String id, String label)

   /**
    * 用户定义事件
    *
    * @param id   事件Id
    * @param info 事件属性集
    */
   public static void onEvent(String id, Map<String, String> info)

   /**
    * 用户定义事件
    *
    * @param id    事件Id
    * @param info  事件属性集
    * @param value 特殊属性值
    */
   public static void onEvent(String id, Map<String, String> info, int value)

如果只需要统计某个事件发生的次数，可以只传一个事件id，如：


CloudAtlas.onEvent("eventShowXX");

如果事件除了需要统计次数，还有不同的属性，如购买事件，可能有买苹果、买梨子、买香蕉等，而且需要对每种类型的水果的购买次数分别统计，则可以使用以下方式：


CloudAtlas.onEvent("eventBuy", "apple");
CloudAtlas.onEvent("eventBuy", "banana");

考虑到某些情况下，对于一个事件，我们不止有一个维度的属性要统计。如购买事件，除了水果的类型，有时还可能需要统计门店，可以使用带Map的接口：


Map<String, String> info = new HashMap<String, String>();
info.put("type", "apple");
info.put("store", "0AD056SDSD00AS"); // 门店标识
CloudAtlas.onEvent("eventBuy", info);

而在此基础上，如果还要扩展统计购买的金额，同时需要对金额做一些数值上的计算分析，则需要调用带int类型value的接口：


Map<String, String> info = new HashMap<String, String>();
info.put("type", "apple");
info.put("store", "0AD056SDSD00AS"); // 门店标识
CloudAtlas.onEvent("eventBuy", info, 2);

注意：ca开头的字符串是保留字，不能作为key。

4. 功能配置

4.1 环境切换

调用接口切换上传数据的环境，目前支持的环境，环境参数：生产环境（FORMAL）、预生产环境（PRE_FORMAL），默认生产环境(FORMAL)


CloudAtlas.switchEnv(FORMAL);

4.2 测试过程中的日志查看

在集成云图SDK的过程中，为了测试云图SDK是否运行正常，可以通过打开日志输出来使得云图SDK输出运行过程中产生的一些日志。 目前的日志包括但不限于：底层初始化结果、AppKey解析失败、调用参数无效、调用顺序错乱、采集数据发送内容与结果等。


CloudAtlas.setLogEnabled(true);

5. 可视化埋点(1.3.3.5.release新增)

5.1 介绍

可视化埋点指的是，用户通过app上传界面视图快照到web可视化埋点后台，然后对web后台的视图快照界面上的可点击控件添加埋点后，当app再次启动时即可对这些控件的点击事件进行埋点的过程。

可视化埋点添加的事件属于自定义事件的埋点。

通过可视化埋点，可以动态添加和删除埋点事件，不需要重新发新版本即可动态生效，解决了代码埋点流程复杂，发布成本高的问题；

5.2 版本支持

app集成的云图组件或云图sdk的版本必须大于等于1.3.3.5.release，低于此版本不支持可视化埋点功能。

5.3 配置流程

第1步 选择埋点应用

登录云图后台，选择需要进行可视化埋点的android应用，点击进入

第2步 进入可视化埋点后台

点击左侧菜单栏下的"可视化埋点"选项，进入可视化埋点后台

第3步 选择app版本

如果是首次添加埋点，请点击右侧"可视化埋点配置工具下载"按钮下载可视化埋点配置工具Apk，

下载完成安装后，开启可视化配置开关，

然后打开需要埋点的app(注意:打开前此app不能处于后台运行，同时可视化埋点配置工具app必须在后台保持运行，否则可能会导致App开启埋点配置失败，无法上传界面快照从而导致无法添加埋点)；

App开启配置后，摇一摇移动设备(连续摇动5次(设备会震动))，即可触发上传app当前的界面视图快照；再点击可视化埋点后台的“刷新列表”即可选择app版本；

如果不是首次添加埋点，直接选择需要埋点的app版本即可；

选择app版本，点击“开启可视化埋点”按钮进入配置界面，

第4步 选择屏幕快照

用户切换移动设备上的app界面，摇一摇(连续摇动5次(设备会震动))上传界面视图快照；

web后台点击"刷新"，选择新增的屏幕视图快照，即可对界面上的可点击控件添加点击事件的埋点，具体操作流程如下图所示：

第5步 添加埋点

web后台点击控件，添加埋点事件，点击“部署生效”让埋点事件正式生效；

部署生效后，所有设备上的app下次启动时，都会获取到最新的埋点事件列表，并绑定到对应的控件，当用户点击控件时，就会触发采集事件日志；

5.4 特别说明

  1. 集成云图sdk的应用支持的最低Android版本必须在4.0以上(包含4.0)，即minSdkVersion >= 14;

  2. 目前只支持一个云图appkey对应一个应用的应用的可视化埋点，不支持在多个应用中使用同一个云图appkey的应用的可视化埋点；

  3. 指定版本添加和部署的埋点事件后只能针对该版本生效，不能跨版本生效(如用户在v1.0版本上添加的埋点事件只能在v1.0版本的app中生效，v1.0以外版本的app是不会生效的)，所以可视化埋点适用于已发布且运行稳定的线上版本；

  4. 如果存在多个activity界面一起显示的情况(如Activity嵌套)，则只能对最先显示的activity界面进行埋点；

  5. 只能对Activity界面上的可点击的原生控件的点击事件埋点，不支持通过H5等实现的非原生控件的埋点；

如有疑问，请联系李永均（621955）

© Appfactory Team all right reserved，powered by Gitbook最后修订时间： 2021-05-13 11:17:07

results matching ""

    No results matching ""