Android SDK

优质

小牛编辑

135浏览

2023-12-01

如需集成DeepShare，请参考DeepShare Android集成

1. 导入SDK

你可以用下面的方法进行导入：

方法1. 使用AndroidStudio自动导入

在App的 build.gradle文件中添加

dependencies {
    implementation 'com.zhuge.analysis:zhugeioanalytics:latest.integration'
}

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

方法2. ADT

下载SDK
解压文件，将zhugesdk_version.jar添加到工程的libs目录下，重新build工程即可。
在App的build.gradle文件中添加：

dependencies {
     compile files('libs/zhugesdk_version.jar')
}

2. 基本功能集成

2.1. 添加权限与AppKey

诸葛分析所需相关权限：

<!--需要网络权限-->
<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"/>

2.2. 启动统计

2.2.1 通过代码配置AppKey及Channel并启动

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

ZhugeParam param = new ZhugeParam.Builder().appKey("yourAppKey")
                                        .appChannel("yourAppChannel")
                                        .build();

ZhugeSDK.getInstance().initWithParam(context, param);

2.2.2 自定义设备ID

诸葛会给每个设备分配一个设备ID来追踪用户，如果你想自己定义设备ID追踪用户，可以自定义设备ID并传给诸葛。

ZhugeParam param = new ZhugeParam.Builder().appKey("appKey")
                                        .appChannel("channel")
                                        .did("did")
                                        .build();

ZhugeSDK.getInstance(). initWithParam(context, param);

initWithParam() 用来初始化统计SDK，并配置启动参数。

参数说明：

参数	说明
context	应用上下文
appKey	官网申请的AppKey
channel	应用分发渠道
did	自定义设备ID，长度不超过256个字符

2.2.3 延迟采集

Android 请在获取权限后的第一个 Activity 内初始化 SDK

ZhugeParam param = new ZhugeParam.Builder()
                .appKey("2d4a0de5873d427d952e64d888bf9c54")
                .appChannel("zhugeio")
                .build(); 
 ZhugeSDK.getInstance().initWithParam(this,param);

注意：

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

说明： 如果使用DeepShare技术，启动诸葛SDK需参考DeepShare中的介绍。

2.3. 打开日志

在init之前调用如下接口来启动日志输出：

ZhugeSDK.getInstance().openLog();

通过如下接口来设置日志输出的级别：

ZhugeSDK.getInstance().setLogLevel(int level);

参数说明：

level：日志输出的级别，Log.VERBOSE,Log.DEBUG,Log.INFO,Log.WARN,Log.ERROR，默认为Log.INFO。

3. 识别用户

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

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

参数说明：

参数	说明
context	应用上下文
uid	用户唯一标识
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);

4. 自定义事件

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

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

参数说明：

参数	说明
context	应用上下文
eventName	事件名称
pro	事件属性

如果你只希望统计事件的次数，那么可以调用另一个接口:

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

代码示例：

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

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

5. 事件时长统计

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

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一致），单独调用一个接口是无效的。

6. 在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，调用如下方法：

 ZhugeSDK.getInstance().enableJavaScriptBridge();

JS代码统计

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

7. 设置自定义属性

事件自定义属性

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

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

8. 自定义SDK数据上传规则

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

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

可指定的配置有：

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

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

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

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

3.数据上传间隔，此项指定若上传未完成，多少秒后重试上传。整数类型，默认为5秒。

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

4.本地最大记录缓存数，此项指定若无网络或请求失败，本地最大可缓存的记录数。整数类型，默认为500条。

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

5.每日最大上传记录数，为减少用户流量消耗，此项指定每日每设备最大可上传的事件数。整数类型，默认为500条。

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

9. Android 全埋点

全埋点功能默认为关闭，集成SDK后打开全埋点开关，即可采集页面访问、页面点击；调用方法如下：

ZhugeSDK.getInstance().openAutoTrack();

页面点击默认采集内置属性。

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

10. Android 崩溃采集

如果希望采集应用崩溃信息，你需要打开崩溃采集开关，默认为关闭。在SDK初始化之前调用如下方法：

  ZhugeSDK.getInstance().openExceptionTrack();

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

注：

如果你同时使用了Bugly，可以兼容一起使用采集崩溃信息；
如果你同时使用了其他崩溃采集工具或自己采集，请测试兼容性；
如遇到问题，请随时联系我们。

11. Android 视屏数据采集

视屏数据默认为不采集，如需采集某个用户的视屏数据，可在需要采集该用户视屏数据时，调用如下方法：

  ZhugeSDK.getInstance().setZGSeeEnable(true);

如需关闭采集该用户的视屏数据时，调用如下方法：

  ZhugeSDK.getInstance().setZGSeeEnable(false);

注：视屏采集数量有限制，建议仅采集需要观察、分析的用户的视屏数据。

12. 收入数据采集

收入数据采集，需调用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);

13. 页面停留时长采集

你可以通过以下方法来进行页面停留时长的数据采集，调用这个方法后，我们会自动帮您采集应用上的页面停留时长数据。

ZhugeSDK.getInstance().enabelDurationOnPage();

14. 元素曝光采集

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

ZhugeSDK.getInstance().enableExpTrack();

标记需要曝光采集的元素一般而言，在view初始化之后调用如下方法进行标记

ZhugeSDK.getInstance().viewExpTrack(ViewExposeData data)

关于参数ViewExposeData

参数	传参方式	是否必须	说明
view	构造函数传参	必须	需要曝光采集的view
eventName	构造函数传参	必须	事件名称
prop	setProp()	非必须	曝光时对应的事件属性

代码示例：

   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);

15. 其他可选API

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

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

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

实时调试

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

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

ZhugeSDK.getInstance().openDebug();

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