Uni-app SDK集成文档

一、配置安全域名

需要在小程序的安全域名设置中,添加诸葛域名为安全域名,默认域名为:

注意:如果通过load函数修改了默认数据上传地址,则需要将修改后的数据上传地址,设置为安全域名。

二、安装sdk

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

npm install --production zg-sdk-uniapp

三、引用sdk

3.1 在app.js文件头部,引入sdk

import {zhuge, mixins} from 'zg-sdk-uniapp'
Vue.mixin(mixins)
zhuge.load('AppKey', {
// load配置参数,具体见下方
})

3.2 引入成功后,即可在页面代码中,通过this.zhuge调用sdk函数,如:

this.zhuge.track('登录')

四、API列表

load(appkey, config)

  • appkey 您在诸葛申请的APPKEY
  • config 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
  utmMode: 'session', // utm模式:session(会话级控制,即以会话开始时的utm为准)、fresh(就近原则)
  parseScene: true, // 是否自动解析小程序场景值为utm信息
  forwardShare: true, // 是否启用分享采集
  superProperty: { // 全局事件属性,设置后除会话、环境及identify事件外,所有事件都会自动加上该配置所有属性
    propA: 'hello'
  },
  sendLimit: 1, // 批量上传限制,默认为1。即事件即时上传。当该配置大于1时,事件会累计达到limit限制再批量上传,也可调用flush方法手动清空
  shareToUtm: { // 打开分享页面时,分享属性到utm信息的映射配置。当设置该映射后,映射的分享属性会当做对应的utm信息就行setUtm操作
    商品名称: 'utm_content' // 分享打开的「商品名称」属性,映射为utm_content属性
  },
  duration: true, // 自动采集页面停留时长
  beforeDuration: (durationPage) => { // 函数参数为页面对象
    // 时长上报事件之前执行
  },
  afterDuration: (durationPage) => {
    // 时长上报事件之后执行
  },
}

使用示例:

this.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所有请求

track(eventName, props)

  • eventName 事件名称
  • props 事件属性

使用示例:

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

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

setUtm(utm)

  • utm 需要设置的utm信息。utm包括:utm_source, utm_medium, utm_campaign, utm_content, utm_term

使用示例:

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

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

setSuperProperty(superProperty)

  • superProperty 全局事件属性 extendSuperPropertys(property)
  • 合并property到全局事件属性 removeSuperProperty(delList)
  • 移除全局事件属性,函数参数为数组 getSuperProperty
  • 获取全局事件属性 flush() 手动批量上传已缓存的所有事件

五、识别用户

identify(cuid, props)

  • cuid 用户唯一标识
  • props 用户属性

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

使用示例:

this.zhuge.identify('17711111111', {
  '性别': '男',
  '会员级别': '白金'
})

六、收入数据采集

trackRevenue(props)

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

使用示例:

this.zhuge.trackRevenue({
  price: 2000,
  productID: 'product001',
  productQuantity: 2,
  revenueType: '3c'
})

注意:price和productQuantity属性,只能为数值类型。

七、微信识别用户

weixinIdentify()

通过「微信授权」登录小程序,可使用快捷绑定微信用户信息方法,在「微信授权成功」后调用如下方法:

this.zhuge.weixinIdentify()

说明:内置绑定的信息内容如下

{
  'user_id':unionid, // 用户唯一标识
  'name': userInfo.nickName, // 名称
  'avatar': userInfo.avatarUrl, // 头像
  '微信-昵称': userInfo.nickName,
  '微信-性别': gender, 
  '微信-城市': userInfo.city,
  '微信-省': userInfo.province,
  '微信-国家': userInfo.country
}

1.使用使用weixinIdentify()方法,需要提供「AppSecret」给诸葛io技术支持人员,用来获取unionid标识用户;登录「微信公众平台」,在「设置-开发者设置-开发者ID」中生成获取。

2.如可自行获取到unionID,可调用自定义identify方法,绑定微信用户信息

八、记录转发分享

1.如需采集,需要在调用load方法时,设置forwardShare为true

2.需要采集分享数据的页面,需要设置onShareAppMessage方法

export default {
  onShareAppMessage() {
    return this.zhugeShare.onShareAppMessage().call(this, {
      title: '欢迎体验uni-app',
      path: '/pages/tabBar/component/component'
    })
  }
}

注意:转发分享数据默认不采集

常见问题

  1. this.zhuge调用失败 this.zhuge的调用方式中,this指的是Page对象,也就是说这种调用仅限在Page的上下文中,如果其它地方需要调用sdk方法,可以文件中单独引入zhuge,如下所示:
    import {zhuge} from 'zg-sdk-uniapp'
    // 然后文件中即可通过使用zhuge.track、zhuge.identify等进行sdk方法调用
    
  2. 打包成小程序后数据无法上传 小程序的安全域名设置中,需要添加诸葛域名为安全域名,默认域名分别为: https://u.zhugeapi.net https://ubak.zhugeio.com 如果通过load函数修改了默认数据上传地址,则需要将修改后的数据上传地址,设置为安全域名
  3. 安装sdk提示无法找到package.json文件怎么办 这种情况需要通过npm init先生成package.json文件,然后再执行安装命令npm install --production zg-sdk-uniapp即可
©zhugeio.com 京ICP备15049545号            文档更新时间 2020-09-29 11:21:09

results matching ""

    No results matching ""