微信小程序 SDK 使用指南

配置 sdk 安全域名

登录「微信公众平台」在「开发-开发设置-服务器域名」的「request 合法域名」中,增加诸葛域名:

https://u.zhugeapi.net

https://ubak.zhugeio.com

安装 sdk

1.在小程序中执行命令安装 sdk 包

npm install --production zg-sdk-wechart

2.点击开发者工具中的菜单栏：工具 --> 构建 npm 3.勾选“使用 npm 模块”选项

引用 sdk

1.在 app.js 文件头部，引入 sdk

import "zg-sdk-wechart";
App.zhuge.load("AppKey", {
  // load配置参数，具体见下方
});

mpvue 引入方式见下方 在yourProject/src/main.js文件顶部，引入 SDK 文件。

import zhuge from "zg-sdk-wechart"; // sdk的引用，需要在Vue和App之前
import Vue from "vue";
import App from "./App";

zhuge.load("此处填写您在诸葛申请的APP KEY", {
  // load方法具体参数，参见下面的接口说明
  pv: true,
});

Vue.config.productionTip = false;
App.mpType = "app";

const app = new Vue(App);
app.$mount();

wepy 引入方式见下方 在 yourProject/app.wpy 文件 script 标签中引入 sdk 文件

// app.wpy
import "zg-sdk-wechart";

App.zhuge.load("此处填写您在诸葛申请的APP KEY", {
  pv: true,
});

//.eslintrc.js eslint配置增加App全局忽略
module.exports = {
  globals: { App: true },
};

2.引入成功后，即可在全局任意地方，通过 App.zhuge 调用 sdk 函数，如：App.zhuge.track('登录')

API 列表

load(appkey, config)

• appkey <string> 您在诸葛申请的 APP KEY
• config <object> sdk 配置信息。不需要自定义的参数可忽略 完整默认配置如下：

{
  debug: false, // 开启实时调试
  serverUrl: { // 事件上报地址。使用的上报地址，应在微信开发设置中，注册为合法域名
    normal: 'https://u.zhugeapi.net', // 主地址
    bac: 'https://ubak.zhugeio.com' // 备用地址
  },
  timeout: 1800000, // 会话超时时间（默认30分钟）,单位：毫秒
  did: '', // 自定义设备id，默认首次加载sdk时，sdk会自动为当前设备生成唯一的did（uuid）
  vn: '1.0', // 小程序版本（小程序项目本身的版本）
  pv: false, // 是否自动上报pv
  click: false, // 是否采集tap事件 默认关闭
  utmMode: 'session', // utm模式：session（会话级控制，即以会话开始时的utm为准）、fresh（就近原则）
  parseScene: true, // 是否自动解析小程序场景值为utm信息
  forwardShare: true, // 是否启用分享采集
  superProperty: { // 全局事件属性，设置后除会话、环境及identify事件外，所有事件都会自动加上该配置所有属性
    propA: 'hello'
  },
  requestTimeout: 60000, // 请求超时时间，单位毫秒。微信基础库最低版本要求为2.10.0。默认与最大值为60秒
  sendLimit: 1, // 批量上传限制，默认为1。即事件即时上传。当该配置大于1时，事件会累计达到limit限制再批量上传，也可调用flush方法手动清空
  shareToUtm: { // 打开分享页面时，分享属性到utm信息的映射配置。当设置该映射后，映射的分享属性会当做对应的utm信息就行setUtm操作
    商品名称: 'utm_content' // 分享打开的「商品名称」属性，映射为utm_content属性
  },
  duration: true, // 自动采集页面停留时长
  beforeDuration: (durationPage) => { // 函数参数为页面对象
    // 时长上报事件之前执行
  },
  afterDuration: (durationPage) => {
    // 时长上报事件之后执行
  },
  countDuration: 3000, // countDuration配置是trackCount函数连续触发的动作停止之后等待的时间，单位毫秒默认值为3000ms。超过等待时间会上传定义的事件和属性包含函数执行的次数和连续触发持续的时间
  exposure: false // 是否启动元素曝光采集 详细请看下文
}

使用示例：

App.zhuge.load("AppKey", {
  pv: true,
});

1. utm 就近原则：每次打开小程序时，sdk 即会再应用的 onShow 声明周期中，解析并更新 utm 信息。如果 onShow 时没有获取到有效 utm 信息，则 utm 信息保持不变。
2. parseScene 为 true 时，打开小程序时，sdk 会自动根据小程序场景值生成 utm_source 与 utm_medium，如果启动参数中包含有这两个 utm 信息，则以启动参数中的 utm 信息为准
3. 当 superProperty 属性与上传事件时指定的属性冲突，则 superProperty 被覆盖
4. 当页面 onHide 时，sdk 会自动 flush 所有请求

identify(cuid, props)

• cuid <string> 用户唯一标识
• props <object> 用户属性

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

App.zhuge.identify("17711111111", {
  性别: "男",
  会员级别: "白金",
});

track(eventName, props)

• eventName <string> 事件名称
• props <object> 事件属性 使用示例：

App.zhuge.track("加入购物车", {
  商品名称: "华为P30",
  商品分类: "3C",
});

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

trackCount

• eventName <string> 事件名称
• props <object> 事件属性

App.zhuge.trackCount("like", {
  商品名称: "华为P30",
  商品分类: "3C",
});

trackCount 是用来记录事件触发的次数，适用于频繁触发事件的场景比如视频直播点赞。

函数连续触发时会记录执行的次数，当函数停止执行会等待集成 sdk 设置的 countDuration 时间，超时后会上传事件和事件属性，通过 trackCount 函数上传的事件会附带两个自定义属性 count 和 countTime，分别代表执行的次数和连续触发持续的时间。

注意 函数执行的过程中如果事件名称和事件属性发生变化 trackCount 函数会立刻上传上次的事件和属性，然后重新开始计数。

setUtm(utm)

• utm <object> 需要设置的 utm 信息。utm 包括：utm_source, utm_medium, utm_campaign, utm_content, utm_term 使用示例：

App.zhuge.setUtm({
  utm_source: "扫码",
  utm_medium: "长按图片识别二维码",
});

调用 setUtm 方法时，utm 信息会强制更新，不会受 utmMode 限制。设置后的 utm 信息，会在后续事件上传中生效。该方法本身不会上传任何事件。

setSuperProperty(superProperty)

• superProperty <object> 全局事件属性

extendSuperPropertys(property)

• 合并 property 到全局事件属性

removeSuperProperty(delList)

• 移除全局事件属性，函数参数为数组

getSuperProperty

• 获取全局事件属性

flush()

手动批量上传已缓存的所有事件

trackRevenue(props)

• props <object> 收入数据属性

{
  price: 0, // <number>价格
  productID: null, // <string>商品id
  productQuantity: 0, // <number>商品数量
  revenueType: null // <string>收入类别
}

收入数据采集 使用示例：

App.zhuge.trackRevenue({
  price: 2000,
  productID: "product001",
  productQuantity: 2,
  revenueType: "3c",
});

price 和 productQuantity 属性，只能为数值类型。

记录转发分享

转发分享数据默认不采集，如需采集，需要在调用 load 方法时，设置forwardShare为 true

启动元素曝光采集

用户使用约定的规则标记元素，元素由不可见变为可见时（页面滚动，显示隐藏）sdk 会自动采集配置在元素上的自定义事件名称和事件属性，会以自定义事件的方式采上传数据。

将 sdk 配置exposure设置为 true，在小程序元素中增加zhuge-expo-track类名，使用data-expo-xxx="yyy"的形式设置自定义事件名称和事件属性，其中data-expo-name="evt"会被识别为事件名其他标记会识别为事件属性。

zhuge.load("test-appkey", {
  exposure: true,
});

<view
  class="zhuge-expo-track"
  data-expo-name="首页banner曝光" // 事件名称 “首页banner曝光”
  data-expo-pos="页头" // 事件属性 pos: "页头"
  data-expo-type="商品" // 事件属性 type: "商品"
>
  xxxx
</view>

setPushClient(clientId: string, channel: string)

推送id上报

• clientId <string> 客户端id
• channel <string> 推送渠道。默认个推

推送渠道支持：jpush(极光推送), umeng(友盟), xiaomi(小米), baidu(百度), xinge(信鸽), getui(个推)

zhuge.setPushClient('xxx', 'getui')

常见问题

1. 接入微信插件的小程序，集成方式有什么变化？

新版的 sdk 不再区分插件版与标准版，按照当前文档集成即可。

2. 老版本 sdk 升级（插件版与标准版通用）

按照现有方式，使用 npm 安装并且编译完成后，将下载到项目中的老版本 sdk 文件内容替换为下方代码,即可完成升级。

const zg = require("zg-sdk-wechart");

module.exports = {
  App: zg.default.App,
  Page: zg.default.Page,
};

3. 集成 sdk 后，小程序开发工具提示报错

需要检查小程序开发工具是否为最新版，如果不是的话一般更新后就可以正常运行。

4. 集成后报错：Uncaught ReferenceError: regeneratorRuntime is not defined

检查小程序开发工具是否开启增强编译，没开启的话，开启后即可避免报错。如果由于生产环境原因， 不能开启增强编译，可以使用 es5 版本的 sdk：

npm install --production zg-sdk-wechart@es5

es5 版本的 sdk 文件会略大于 latest 版本

5. 页面事件无法上传，或 duration 无法监听

这类问题通常是一些小程序框架集成中，sdk 无法有效监听页面生命周期导致的，如 taro1.x、2.x 版本, 此时可以手动在各个页面组件中，对生命周期进行监听，示例代码如下：

import { Component } from "@tarojs/taro";
import { View } from "@tarojs/components";
class Index extends Component {
  constructor(props) {
    super(props);
  }

  componentDidShow() {
    App.zhuge.lifecycle.Page.onShow();
  }

  componentDidHide() {
    App.zhuge.lifecycle.Page.onHide();
  }

  componentDidMount() {
    App.zhuge.lifecycle.Page.onLoad(this.$router.params);
  }

  componentWillUnmount() {
    App.zhuge.lifecycle.Page.onUnLoad();
  }

  render() {
    return <View>首页</View>;
  }
}

export default Index;

6. sendLimit 批量上传时，上传时机是什么时候？

当设置了 sendLimit 时，触发的所有埋点请求，会达到 limit 指定数量时，将所有埋点数据合并为一个请求进行上传。另外为避免数据丢失的可能性，当页面触发 Page 的 onHide、onUnload 生命周期时，不管请求数量是否达到 limit 限制，都会将已缓存数据进行上传。

7. 如何启动小程序可视化埋点？

可视化埋点启动的前提是开启全埋点（即 config 中的 pv 和 click 设置为true），同时 config 中的 visual 也设置为 true 时，小程序sdk会启动可视化埋点，每次点击或浏览行为发生后，会把行为数据与可视化埋点规则中的数据进行比较，如果能匹配上，侧进行全埋点的同时，会进行可视化埋点上报。

8. 如何新增或修改小程序可视化规则？

登录诸葛分析平台 - 顶部导航 - 数据管理 - 数据接入 - 微信小程序 - 可视化埋点 - 授权对应的小程序 - 启动可视化埋点 - 手机扫码小程序二维码 - 小程序通过scoket与分析平台进行连接 - 手机端进行点击或浏览操作 - 分析平台新增或修改可视化规则。（注：开发者在扫码后，需要在手机端打开小程序调试模式，这样避免微信官方的域名校验导致sckoet连接失败的问题。）通过 socketUrl 可配置私有化的scoket连接。