zg-sdk-uniapp/README.md

诸葛io小程序uniapp数据采集sdk

# uniapp SDK使用指南

### 安装sdk
1.在小程序中执行命令安装sdk包
  ```bash
  npm install --production zg-sdk-uniapp
  ```
### 引用sdk
1.在main.js文件头部，引入sdk进行初始化
  ```js
  import {zhuge, mixins} from 'zg-sdk-uniapp'
  Vue.mixin(mixins)
  zhuge.load('AppKey', {
  // load配置参数，具体见下方
  })
  ```
2.sdk调用
需要调用sdk的页面，在引入zhuge对象后即可进行调用：
```js
import {zhuge} from 'zg-sdk-uniapp'
zhuge.track('购买商品')
```
### Vue3支持

```js
import { createSSRApp } from 'vue'
import {zhuge, mixins} from 'zg-sdk-uniapp'

export function createApp() {
  const app = createSSRApp(App)
  
  app.mixin(mixins)
  zhuge.load('appKey', {
    // load配置参数，具体见下方
  })
  return {
    app
  }
}
```
#### 注意事项
由于nvue格式的页面，无法有效监听到页面的声明周期，因此该格式的文件，需要单独引入sdk，并手动mixin
示例代码如下：
```
  import {zhuge, mixins} from '@/zhuge.min.js'
  export default {
    data() {
      return {
        title: 'Hello'
      }
    },
    mixins: [mixins],
    onShow() {
      zhuge.track('访问首页');
    },
    onLoad() {

    },
    methods: {

    }
  }
```
> uni-app项目中，一个页面就是一个符合Vue SFC规范的.vue文件或.nvue文件。
> .vue页面和.nvue页面，均全平台支持，差异在于当uni-app发行到App平台时，.vue文件会使用webview进行渲染，.nvue会使用原生进行渲染，详见：nvue原生渲染。


### API列表
#### load(appkey, config)
* appkey \<string\>
您在诸葛申请的APP KEY
* config \<object\>
sdk配置信息。不需要自定义的参数可忽略
完整默认配置如下：
```js
{
  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) => {
    // 时长上报事件之后执行
  },
}
```
使用示例：
```js
zhuge.load('AppKey', {
  pv: true
})
```
> 1. utm就近原则：每次打开小程序时，sdk即会再应用的onShow声明周期中，解析并更新utm信息。如果onShow时没有获取到有效utm信息，则utm信息保持不变。  
> 2. parseScene为true时，打开小程序时，sdk会自动根据[小程序场景值](https://developers.weixin.qq.com/miniprogram/dev/reference/scene-list.html)生成utm_source与utm_medium，如果启动参数中包含有这两个utm信息，则以启动参数中的utm信息为准
> 3. 当superProperty属性与上传事件时指定的属性冲突，则superProperty被覆盖
> 4. 当页面onHide时，sdk会自动flush所有请求  

#### identify(cuid, props)
* cuid \<string\>
用户唯一标识
* props \<object\>
用户属性

> 为了保持对用户的跟踪，你需要为他们记录一个识别码，可以使用手机号、email等唯一值来作为用户的识别码。另外，也可以在跟踪用户的时候， 记录用户更多的属性信息，便于你更了解你的用户  
使用示例：
```js
zhuge.identify('17711111111', {
  '性别': '男',
  '会员级别': '白金'
})
```

#### track(eventName, props)
* eventName \<string\>
事件名称
* props \<object\>
事件属性
使用示例：
```js
zhuge.track('加入购物车', {
  '商品名称': '华为P30',
  '商品分类': '3C'
})
```
> 注意：在添加事件属性时，需注意事件属性类型。如果事件属性类型为「数值型属性」，需要在上传数据时修改数据类型为「数值型」，并且在诸葛io后台埋点管理中修改为「数值型」。  

#### setUtm(utm)
* utm \<object\>
需要设置的utm信息。utm包括：utm_source, utm_medium, utm_campaign, utm_content, utm_term 
使用示例：
```js
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\>
  收入数据属性
```js
{
  price: 0, // <number>价格
  productID: null, // <string>商品id
  productQuantity: 0, // <number>商品数量
  revenueType: null // <string>收入类别
}
```
收入数据采集
使用示例：
```js
zhuge.trackRevenue({
  price: 2000,
  productID: 'product001',
  productQuantity: 2,
  revenueType: '3c'
})
```
> price和productQuantity属性，只能为数值类型。

#### 记录转发分享(仅在打包为小程序时支持)
1. 如需采集，需要在调用load方法时，设置**forwardShare**为true
2. 需要采集分享数据的页面，需要设置onShareAppMessage方法
```
export default {
  onShareAppMessage() {
    return this.zhugeShare.onShareAppMessage().call(this, {
      title: '欢迎体验uni-app',
      path: '/pages/tabBar/component/component'
    })
  }
}
```
> 转发分享数据默认不采集

#### setPushClient(clientId: string, channel: string)
推送id上报
- clientId \<string\>
  客户端id
- channel \<string\>
  推送渠道。默认个推
> 推送渠道支持：jpush(极光推送), umeng(友盟), xiaomi(小米), baidu(百度), xinge(信鸽), getui(个推)

```
zhuge.setPushClient('xxx', 'getui')
```
### 常见问题
1. this.zhuge调用失败
`this.zhuge`的调用方式中，this指的是Page对象，也就是说这种调用仅限在Page的上下文中，如果其它地方需要调用sdk方法，可以文件中单独引入zhuge，如下所示：
``` js
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`即可