Android SDK (<4.0.0)

1. 集成SDK

1.1 使用AndroidStudio自动导入

1.1.1 引入仓库

集成 ZhugeIO SDK 时需要注意是否已经添加 mavenCentral() 仓库地址。

• AGP7及以上

// 在Project中的settings.gradle文件中添加代码仓库地址。
dependencyResolutionManagement {
    repositories {
        // 添加sdk依赖的 maven 仓库地址
        mavenCentral()
    }
}

• AGP 7.0以下

// 在 project 中的 build.gradle 文件中添加代码仓库地址。
buildscript {
    repositories {
        mavenCentral()
    }
}

allprojects {
    repositories {
        // 添加maven仓库
        mavenCentral()
    }
}

1.1.2 引入SDK

在App的 build.gradle 文件中添加

dependencies {
    implementation 'io.github.zhugefe:zhugeio-analytics:3.7.1'
}

添加完毕之后重新build工程即可。

1.2 手动引入SDK

1. 下载SDK v3.7.2
2. 若您的业务中需使用到广告监测，则需下载SDK v3.7.2_imei
3. 解压文件，将下载的SDK添加到工程的libs目录下，重新build工程即可。

在App的build.gradle文件中添加：

dependencies {
    implementation files('libs/下载文件名')
}

2. 初始化SDK

说明

建议您在用户同意您App中的隐私政策后，再进行 SDK 初始化。

2.1 获取 APPKEY

在开始集成前，首先拥有一个应用/主体，进行SDK集成前，您需要获取对应应用/主体的App Key信息。

您可以在「应用管理」->「主体管理」->「设置」中可查看您的App Key

2.2 获取数据上送地址

私有化部署版本需要获取数据上送地址。 如您不清楚此地址，请联系您的项目经理或技术支持。

2.3 初始化 SDK

将SDK的初始化代码放入Application的onCreate中。

若你希望通过代码传递appKey及渠道信息,请使用 ZhugeParam 实体类来定义信息，然后使用该参数初始化SDK：

ZhugeParam param = new ZhugeParam.Builder()
               .appKey("app key")
               .appChannel("your app channel")
               .build();
// 私有化部署: 设置私有化部署数据上送地址，参考 2.2节 获取，例如 https://yourdomain.com，注意域名后不要加“/”
ZhugeSDK.getInstance().setUploadURL('上报地址', '备用上报地址');
ZhugeSDK.getInstance().initWithParam(context, param);

参数说明：

上述三个参数为SDK必须的参数，不能为空。

saas上报地址

• 首选地址：https://su.zhugeio.com
• 备用上报地址：https://subak.zhugeio.com

2.4 多实例初始化（可选，多主体/多实例 场景）

Android SDK 版本需 大于等于 v4.0.0，JS SDK版本需 大于等于 v4.0.0 才支持多实例初始化。

具体参考如下文档:

• Web SDK 集成 - 多实例/多主体 相关使用说明
• [新] Android SDK (>=4.0.0)集成开发指南

3. 延迟采集

Android 请在获取权限后初始化 SDK

ZhugeParam param = new ZhugeParam.Builder()
                .appKey("app key")
                .appChannel("your app channel")
                .build(); 
ZhugeSDK.getInstance().initWithParam(context, param);

注意：

1. init() 与 initWithParam() 方法只能调用一个，同时调用会以第一个执行到的为准；因此，请保证只调用了一个 init() 方法；
2. 调用 initWithParam() 时，如果第二个参数 ZhugeParam 中没有设置 appKey 与 appChannel 。则会从从应用的 Manifest 中获取 AppKey 及 Channel 。

4. 初始化配置

在初始化SDK之前，你可以调用各种设置接口，自定义SDK功能，下列接口均需在SDK初始化之前调用。

4.1 开启日志

在SDK初始化之前，调用如下接口开启日志

ZhugeSDK.getInstance().openLog();

4.2 开启实时调试

你可以使用诸葛io提供的实时调试功能，实时监测数据是否正确上传，调试完成后请关闭debug。

使用方法：在SDK初始化之前调用如下代码以开启实时调试，建议仅在测试设备上开启。

ZhugeSDK.getInstance().openDebug();

在诸葛io中打开实时调试页面，即可实时查看上传的数据.

4.3 设置每日上传数量

为了节约用户流量，SDK通过每日上传事件数量限制流量消耗，默认为 50000 事件。你可以根据需要调用如下接口设置该数量

ZhugeSDK.getInstance().setMaxSendSize(int size)

4.4 设置本地最大事件数

SDK在数据上传到服务端之前，会在本地缓存用户的事件。以防止无网或者上传失败时数据丢失，但本地最大保存数量有限制，默认为3000条事件，你也可以调用如下接口自定义该数量

ZhugeSDK.getInstance().setMaxLocalSize(int size);

4.5 开启崩溃采集

在SDK初始化之前，调用如下代码开启崩溃采集功能。该功能开启之后，SDK可以采集原生代码的部分崩溃信息，并上报到服务器。

ZhugeSDK.getInstance().openExceptionTrack();

崩溃采集信息包括：异常名称、异常描述、发生时间、应用版本、应用包名等信息。

注：

1. 如果你同时使用了其他崩溃采集工具或自己采集，请测试兼容性；
2. 如遇到问题，请随时联系我们。

4.6 开启全埋点采集

全埋点采集功能可以自动采集PV和按钮点击事件，要开启该功能，请在SDK初始化之前调用如下接口

ZhugeSDK.getInstance().openAutoTrack();

全埋点采集默认采集数据:

$page_title：页面标题
$eid"：全埋点类型 click / pv
$element_content：控件的文本内容
$element_type：控件的类型
$element_selector：控件的选择器

4.7 开启页面停留采集

页面停留采集可以自动统计用户在每个Activity的停留时长，要开启该功能，请在 SDK 初始化之前调用如下接口

ZhugeSDK.getInstance().enabelDurationOnPage();

4.8 设置上传地址

私有部署客户可以通过该接口设置数据发送的服务器地址

String url = "https://yourdomain.com/path";
ZhugeSDK.getInstance().setUploadURL(url, backupUrl);

url为服务器端数据采集接口所在路径，具体参考2.2节获取。 backupUrl为主接口失效时的备份地址，没有可以为空。注意url需包含协议名称，即http还是https。

4.9 开启数据上传加密

注：此功能需要联系我们开通，仅支持私有化部署

开启加密

SDK的数据上传时进行了编码，若您有数据加密需求，可以调用如下接口开启数据加密传输

ZhugeSDK.getInstance().setEncryptionEnable(boolean enable);

加密算法

当开启数据加密上传时，默认采用的加密算法为国密SM4，你也可以设置SDK采用传统的RSA+AES加密。通过如下接口设置SDK所采用的数据加密算法：

ZhugeSDK.getInstance().setEncryptionType(ZGEncryptType type)

ZGEncryptType为SDK内部定义的一个枚举类，包含AES_RSA与SM4_SM2，默认为SM4_SM2。

注意，使用国密算法，应用还需在应用的依赖中添加国密算法的SDK，即在引用zhuge的地方添加如下依赖:

implementation 'org.bouncycastle:bcprov-jdk15on:1.69'
implementation 'org.bouncycastle:bcpkix-jdk15on:1.69'

4.10 自定义设备ID

SDK默认采用uuid作为设备ID，如果你有自己的设备ID标识方案，可以在初始化时传入，作为设备ID使用

ZhugeParam param = new ZhugeParam.Builder().appKey("appKey")
                                        .appChannel("channel")
                                        .did("did")
                                        .build();
ZhugeSDK.getInstance(). initWithParam(context, param);

4.11 广告监测 (可选)

若您需使用广告监测功能，需在调用Init之前，调用这行代码开启广告功能，ZhugeSDK.getInstance().enableImeiCollect();

在广告监测场景中，若您自有产品获取的设备信息不能满足用户精确匹配，我们建议您使用oaid来解决此问题；安卓获取oaid前置条件，需集成移动安全联盟 (http://www.msa-alliance.cn/col.jsp?id=120) ，申请后集成oaid sdk，集成后诸葛安卓sdk会自动采集设备oaid。

4.12 可视化埋点

4.12.1 可视化埋点开启

在 init 之前调用如下接口来开启可视化埋点功能：

ZhugeSDK.getInstance().openVisual();

打开开关之后，诸葛SDK启动时会拉取所配置的事件列表，并进行绑定。为保证不遗漏事件，建议在application的onCreate生命周期中初始化SDK。

私有化需结合部署情况设置可视化服务的地址，请在sdk初始化之前，调用如下代码：

//设置可视化设置时的服务器地址，注意格式
String socketUrl = "wss://xxx.zhugeio.com";
ZhugeSDK.getInstance().setupCodelessUrl(socketUrl);
//设置获取可视化事件时的服务器地址
String url = "https://xxx.zhugeio.com";
ZhugeSDK.getInstance().setupCodelessGetEventsUrl(url);

4.12.2 设置可视化埋点

要配置应用的可视化埋点事件，需要你连接诸葛后台的可视化配置界面。要做到这点，需要你在手机上安装开启了可视化埋点的应用，然后用手机扫描页面上的二维码，在下方输入框输入SDK在应用端对应的scheme，默认为123456。然后点击下方的打开应用，即可开始可视化配置。

若你想更改这个默认的scheme，请在应用的manifest文件的application标签下，添加如下代码

<activity
    android:name="com.zhuge.analysis.stat.ZhugeVisualActivity"
    android:configChanges="orientation|screenSize"
    android:exported="true"
    android:launchMode="singleTask"
    tools:node="replace">
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />

            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />

            <data
            <!--替换下方 scheme 里zgio后面的字符-->
                android:scheme="zgio123456" 
                android:host="visualized" />
            </intent-filter>
</activity>

将 scheme 中zgio123456里的数字部分替换为任何你们确定的字符，例如替换为zgioabcdefg，然后打包安装至手机。 然后，在输入appId的地方，输入你自定义的字符，例如abcdefg，然后点击去开启按钮，即可打开应用。

4.13 其他设置

诸葛io支持自己定义SDK数据上传规则，例如：两次会话之间的时间间隔，即在多长时间内重新回到应用算作同一个会话；以及SDK生成的数据达到多少条后开始上传。具体的可定义信息及定义方式如下：

用户通过在Manifest中 <application\> 节点下添加 <meta-data\> 来指定配置。

可指定的配置有：

1.会话间隔，此项指定应用在多长时间内回到应用算作同一个会话。以秒为单位，整数类型，默认为30秒。

<meta-data 
        android:name="com.zhuge.config.SessionInterval" 
        android:value="30"/>

2.触发上传记录数，此项指定本地达到多少条数据时可上传。整数类型，默认为1条。

<meta-data 
        android:name="com.zhuge.config.UploadLimit" 
        android:value="1"/>

3.数据上传间隔，此项指定若待上传数据未全部上传完成，每个批次间隔N秒上传。整数类型，默认为5秒。

<meta-data 
        android:name="com.zhuge.config.FlushInterval" 
        android:value="5"/>

5. 埋点采集

5.1 识别用户

为了保持对用户的跟踪，你需要为他们记录一个识别码，你可以使用用户id、email等唯一值来作为用户的识别码。另外，你可以在跟踪用户的时候， 记录用户更多的属性信息，便于你更了解你的用户：

ZhugeSDK.getInstance().identify(Context context, String uid,JSONObject pro);

参数说明：

代码示例：

//定义用户识别码
String userid = user.getUserId();
//定义用户属性
JSONObject personObject = new JSONObject();
personObject.put("avatar", "http://tp4.sinaimg.cn/5716173917/1");
personObject.put("name", "张三");personObject.put("gender", "男");
personObject.put("等级", 90);
//标识用户
ZhugeSDK.getInstance().identify(getApplicationContext(),userid, personObject);

5.2 自定义事件

在你希望记录用户行为的位置，自定义事件，调用如下代码：

ZhugeSDK.getInstance().track(Context context,String eventName,JSONObject pro);

参数说明：

代码示例：

//定义与事件相关的属性信息  
JSONObject eventObject = new JSONObject();
eventObject.put("分类", "手机");
eventObject.put("名称", "iPhone6 plus 64g");  
eventObject.put("价格",  5888); //数值型属性不要带引号
//记录事件
ZhugeSDK.getInstance().track(getApplicationContext(), "购买",  eventObject);

注意： 在添加事件属性时，需注意事件属性类型。如果事件属性类型为「数值型属性」，需要在上传数据时修改数据类型为「数值型」，并且在诸葛io后台埋点管理中修改为「数值型」。

5.3 事件时长统计

若你希望统计一个事件发生的时长，比如视频的播放，页面的停留，那么可以调用如下接口来进行：

ZhugeSDK.getInstance().startTrack(String eventName);

说明：调用startTrack()来开始一个事件的统计，eventName为一个事件的名称

ZhugeSDK.getInstance().endTrack(String eventName,JSONObject pro);

说明：调用endTrack()来记录事件的持续时长。调用endTrack()之前，相同eventName的事件必须已经调用过startTrack()，否则这个接口并不会产生任何事件。

代码示例：

//视频播放开始
ZhugeSDK.getInstance().startTrack("观看视频");
//视频观看结束
JSONObject pro = new JSONObject();
pro.put("名称","非诚勿扰");
pro.put("期数","2016-11-02");
ZhugeSDK.getInstance().endTrack("观看视频",pro);

注意： startTrack()与endTrack()必须成对出现（eventName一致），单独调用一个接口是无效的。

5.4 设置自定义属性

若有一些属性，每一个事件都要拥有，你可以调用 setSuperProperty() 传入；之后，每一个经过track(), endTrack() 传入的事件，都将自动获得这些属性。

ZhugeSDK.getInstance().setSuperProperty(JSONObject pro);

5.5 收入数据采集

收入数据采集，需调用trackRevenue()方法，自动记录收入事件以及事件属性；price(商品价格)、productID(商品ID)、productQuantity(商品数量)、revenueType(收入类型)为收入事件内置属性，必传项。

具体使用方法如下：

JSONObject revenuePro = new JSONObject();
revenuePro.put("price",229);  //数值型属性不要带引号
revenuePro.put("productID","小米NFC手环");
revenuePro.put("productQuantity",2); //数值型属性不要带引号
revenuePro.put("revenueType","手环");
ZhugeSDK.getInstance().trackRevenue(this,revenuePro);

5.5 在WebView中统计

如果你的页面中使用了WebView嵌入HTML,JS的代码，并且希望统计HTML中的事件，可以通过下面的文档来进行跨平台的统计。

注意： 如果你的HTML是运行在浏览器的，还是无法进行统计的，以下仅针对使用WebView加载网页的情况。

Java代码集成

首先要找到你的WebView对象，并做如下处理：

WebView webView = (WebView) findViewById(R.id.web); 
webView.getSettings().setJavaScriptEnabled(true); 
webView.addJavascriptInterface(new ZhugeSDK.ZhugeJS(),"zhugeTracker");

3.4.16 版本之后支持自动打通 H5，需集成 zhuge 插件：

在项目的根build.gradle中，添加classpath:

classpath 'io.github.zhugefe:android-gradle-plugin:1.0.0'

在应用的build.gradle中，启用zhuge插件：

apply plugin: "com.zhugeioanalytics.android"

然后在调用init方法之前，调用如下代码:

ZhugeSDK.getInstance().enableJavaScriptBridge();

JS代码统计

Native 端配置好之后，即可在 html 页面中通过 js 进行移动端的打点，具体统计方式请参照 JS 集成文档，JS 的 sdk 会自动判断页面来自浏览器或 APP，区分事件所属平台。

5.6 元素曝光采集

曝光采集功能默认关闭，需要在 SDK 调用 Init 之前进行开启

ZhugeSDK.getInstance().enableExpTrack();

标记需要曝光采集的元素

一般而言，在view初始化之后调用如下方法进行标记

ZhugeSDK.getInstance().viewExpTrack(ViewExposeData data)

关于参数ViewExposeData

代码示例：

View view = findViewById(R.id.view);
ViewExposeData exposeData = new ViewExposeData(view, "view曝光");
JSONObject prop = new JSONObject();
prop.put("prop","value");
exposeData.setProp(prop);
ZhugeSDK.getInstance().viewExpTrack(exposeData);

5.7 其他API

ZhugeSDK.getInstance().getDid() 你可以通过这个接口来获取当前设备在诸葛体系下的设备标识。

ZhugeSDK.getInstance().getSid() 你可以通过这个接口来获得当前应用所属的会话ID。

ZhugeSDK.getInstance().flush() 应用通过诸葛统计的数据，都是先存储在设备上。当应用启动或者设备上存储的事件大于等于5条时，会尝试进行上传。若你想尽快的发送数据，那么可以调用flush()来进行一次数据发送。

6. 权限说明

标准版

配置如下：

<uses-permission  
  android:name="android.permission.INTERNET"/>
<!--需要获取网络状态-->
<uses-permission  
  android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission
  android:name="android.permission.ACCESS_WIFI_STATE"/>

广告版

配置如下：

<uses-permission  
  android:name="android.permission.INTERNET"/>
<!--需要获取网络状态-->
<uses-permission  
  android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission  
  android:name="android.permission.ACCESS_WIFI_STATE"/>
<!--需要获取设备信息-->
<uses-permission  
  android:name="android.permission.READ_PHONE_STATE"/>