Android SDK (>=4.0.0)

Android SDK 从 4.0.0 版本起支持多主体/多实例上报，对 SDK 初始化进行升级，如您对多主体 / 多实例 无需求，可直接使用 Android SDK 老版本(<=v4.0.0) 。

注意：移动端SDK 大于等于 v4.0.0时，H5使用的 js sdk 版需 大于等于 v4.0.0，分析平台版本需升级至 v4.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:4.0.0'
}

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

若您使用为老版本，对多主体/多实例无需求，可直接使用 Android SDK 老版本(<=v4.0.0) ，此处改为如下代码重新打包即可。

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

1.2 手动引入SDK

1. 下载SDK v4.0.0
2. 若您的业务中需使用到广告监测，参考 Android SDK (<4.0.0)集成开发指南，暂不支持多主体 / 多实例特性。
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中。

使用 ZhugeParam 实体类来定义信息，然后使用该参数初始化SDK：

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

参数说明：

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

saas上报域名

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

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

调用 ZhugeSDK.newInstance() 来获得一个新的 SDK 实例。然后针对每一个实例，定义对应的ZhugeParam，然后通过 ZhugeParam 来初始化对应的实例

ZhugeSDK zg_user = ZhugeSDK.newInstance();
ZhugeParam param = new ZhugeParam.Builder()
               .appKey("user app key")
               .appChannel("your app channel")
               .uploadEventUrlAndBackupUrl('上报域名', '备用上报域名')
               .build();
zg_user.initWithParam(param);

3. 延迟采集

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

// 主体1
sdk.initWithParam(context, param);

// 主体2
zg_user.initWithParam(param);

4. ZhugeParam 参数选项

ZhugeParam 是SDK初始化的配置参数载体，各项功能开关及自定义选项均通过该参数来传递，可选配置项有:

4.1 崩溃采集

该功能开启之后，SDK可以采集原生代码的部分崩溃信息，并上报到服务器。 崩溃采集信息包括：异常名称、异常描述、发生时间、应用版本、应用包名等信息。

注：

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

4.2 全埋点采集

全埋点采集功能可以自动采集PV和按钮点击事件，全埋点采集默认采集数据:

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

4.3 页面停留采集

页面停留采集可以自动统计用户在每个 Activity 的停留时长

4.4 设置上传域名

私有部署客户可以通过该参数设置数据上传域名

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

4.5 数据上传加密

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

加密算法

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

ZhugeParam.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'

5. 全局初始化配置

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

注意：此处为全局设置，每个SDK实例都会使用该配置。

5.1 开启日志

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

ZhugeSDK.openLog();

5.2 设置每日上传数量

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

ZhugeSDK.setMaxSendSize(int size)

5.3 设置本地最大事件数

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

ZhugeSDK.setMaxLocalSize(int size);

5.4 自定义设备ID

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

ZhugeSDK.setDid(String did)

6. 主体/实例 初始化配置

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

注意：此处为 对应主体 / 实例配置，仅对配置的对应主体 / 实例生效。

6.1 可视化埋点

6.1.1 可视化埋点开启

在 init 之前针对ZhugeParam开启该功能：

ZhugeParam param = new ZhugeParam.Builder()
               .appKey("app key")
               .appChannel("your app channel")
               .uploadEventUrlAndBackupUrl('上报域名', '备用上报域名')
               .enableVisual(true)
               .build();

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

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

//设置可视化设置时的服务器域名，注意格式
String editorUrl = "wss://xxx.zhugeio.com";
//设置获取可视化事件时的服务器域名
String eventUrl = "https://xxx.zhugeio.com";
ZhugeParam param = new ZhugeParam.Builder()
               .appKey("app key")
               .appChannel("your app channel")
               .uploadEventUrlAndBackupUrl('上报域名', '备用上报域名')
               .enableVisual(true)
               .codelessEventUrl(eventUrl)
               .codelessEditorUrl(editorUrl)
               .build();

6.1.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
            <!--替换下方schem里zgio后面的字符-->
                android:scheme="zgio123456" 
                android:host="visualized" />
            </intent-filter>
</activity>

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

6.2 其他设置

诸葛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"/>

7. 埋点采集

以下接口，对应的SDK实例，均需初始化过才可使用.

注意：下面调用方法是基于 sdk.xxx 进行调用，其中 sdk 为初始化后的SDK实例对象，参考 2.3 章节。

7.1 识别用户

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

sdk.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);
//标识用户
sdk.identify(getApplicationContext(),userid, personObject);

7.2 自定义事件

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

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

参数说明：

代码示例：

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

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

7.3 事件时长统计

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

sdk.startTrack(String eventName);

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

sdk.endTrack(String eventName,JSONObject pro);

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

代码示例：

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

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

7.4 设置自定义属性

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

sdk.setSuperProperty(JSONObject pro);

7.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","手环");
sdk.trackRevenue(this,revenuePro);

7.6 在WebView中统计

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

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

Java代码集成

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

WebView webView = (WebView) findViewById(R.id.web); 
webView.getSettings().setJavaScriptEnabled(true); 
// 注意，此处需使用 ZhugeSDK.ZhugeJS 而不是 sdk.ZhugeJS
webView.addJavascriptInterface(new ZhugeSDK.ZhugeJS(),"zhugeTracker");

JS代码统计

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

7.7 元素曝光采集

曝光采集功能默认关闭，需要在 SDK初始化之前设置ZhugeParam进行开启

标记需要曝光采集的元素

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

sdk.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);
sdk.viewExpTrack(exposeData);

7.8 获取会话ID

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

7.9 立即上传本地所有数据

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

7.10 其他API

注意：此处调用的是ZhugeSDK类的接口，而非 sdk对象 的接口，以下信息各主体均为一致信息。

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

8. 权限说明

标准版

配置如下：

<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"/>

9. 常见问题

9.1 v4.0.0和老版本SDK使用区别

初始化

所有原通过 ZhugeSDK.getInstance().xxx 调用的方法改为 ZhugeParam.xxx 使用。

以 setUploadURL 为例：

v4.0.0之前版本：

ZhugeParam param = new ZhugeParam.Builder()
               .appKey("app key")
               .appChannel("your app channel")
               .build();
ZhugeSDK.getInstance().setUploadURL('上报域名', '备用上报域名');// 此处为老方式
ZhugeSDK.getInstance().initWithParam(context, param);

v4.0.0及之后版本：

ZhugeParam param = new ZhugeParam.Builder()
               .appKey("app key")
               .appChannel("your app channel")
               .uploadEventUrlAndBackupUrl('上报域名', '备用上报域名')// 此处为新方式
               .build();
ZhugeSDK sdk = ZhugeSDK.getInstance();
sdk.initWithParam(context, param);

具体变化如下：

ZhugeSDK.getInstance().openDebug();// 是否开启实时调试    
ZhugeSDK.getInstance().openExceptionTrack();// 是否开启崩溃采集
ZhugeSDK.getInstance().openAutoTrack();// 是否开启全埋点    
ZhugeSDK.getInstance().openVisual();// 是否开启可视化采集    
ZhugeSDK.getInstance().enabelDurationOnPage();// 是否开启页面停留时长采集    
ZhugeSDK.getInstance().enableExpTrack();// 是否开启曝光采集
ZhugeSDK.getInstance().setupCodelessUrl(String url);// 设置可视化埋点的 Websocket 域名
ZhugeSDK.getInstance().setupCodelessGetEventsUrl(String url);// 设置可视化埋点的远程事件获取 URL 域名
ZhugeSDK.getInstance().setUploadURL(String url ,String backupUrl);// 设置数据上传域名
ZhugeSDK.getInstance().setZGSeeEnable(boolean enable);// 注意：此方法已经废弃
ZhugeSDK.getInstance().setEncryptionEnable(boolean enable);// 开启数据上传加密
ZhugeSDK.getInstance().setEncryptionType(ZGEncryptType type);// 设置数据加密类型
ZhugeSDK.getInstance().setRSAPubKey(String key);// 设置数据加密rsa公钥

变更为

ZhugeParam params = new ZhugeParam.Builder()
        //设置appKey
        .appKey("appkey")
        //设置appChannel
        .appChannel("zhugeio-demo")
        //对该实例启用实时调制
        .enableDebug(true)
        //启用页面时长统计，启用全埋点
        .enableDurationOnPage(true).enableAutoTrack(true)
        //设置事件上传域名
        .uploadEventUrl("https://zhugeio.com")
        //设置业务ID，每个appKey对应一个业务ID
        .businessKey("业务1")
        //开启数据加密上传
        .enableEncryption(true)
        //设置数据加密类型，默认为AES_RSA
        .setEncryptionType(ZGEncryptType.AES_RSA).build();
//通过上述配置初始化默认SDK实例
ZhugeSDK.getInstance().initWithParam(context, params);

具体方法含义参照 第4节 文档。

移除内容

ZhugeSDK.getInstance().setEncryptionType(int type);
ZhugeSDK.getInstance().setLogLevel(int level);
ZhugeSDK.getInstance().setPersistenceStorage(boolean enable);
ZhugeSDK.getInstance().cacheDataEncode();
ZhugeSDK.getInstance().isEnableCacheDataEnacode();

调用方法升级（兼容之前的调用方法）

之前为 ZhugeSDK.getInstance().xxx()方式调用，现同时支持如下方法调用：

ZhugeSDK.setMaxLocalSize(int size);
ZhugeSDK.setMaxSendSize(int size);
ZhugeSDK.openLog();
ZhugeSDK.setDid(String did);
ZhugeSDK.getDid();

9.2 移动端使用v4.0.0及以上版本 和 低于v4.0.0的js sdk做h5打通的兼容问题

H5上报数据数据均会上报至默认主体/实例，即通过ZhugeSDK.getInstance()初始化主体/实例。

9.3 移动端使用v4.0.0及以下（之前）版本，js sdk使用v4.0.0以上版本的H5打通兼容问题

• 若 不使用多主体/多实例场景，无影响。
• 若 使用多主体/多实例场景，H5上报数据均会上报至默认主体/实例，即通过ZhugeSDK.getInstance()初始化主体/实例。