@wise-group/tracking-jssdk/README.md

前端埋点sdk

# Feature
-[x] 支持小程序原生
-[x] 支持uniapp
-[x] 支持 vue web端（无路由模式） (无路由不触发自动页面访问上报)
-[x] 支持 vue web端（history路由模式）
-[ ] 支持 vue web端（hash路由模式）

# 快速入门
```bash
$ npm i @wise-group/tracking-jssdk
```

## 引用SDK
```js
// 在入口文件
// 小程序原生开发 app.js
const wTracker = require('@wise-group/tracking-jssdk')

// 第三方框架，如uniapp
// src/main.js
import wTracker from "@wise-group/tracking-jssdk";
```

## 初始化SDK
### 小程序原生
```js
// app.js
const wTracker = require('@wise-group/tracking-jssdk')
wTracker.init({
  apiUrl: 'xxx',
  keyCode: 'xxx',
})

// 针对小程序端，需要将apiUrl的域名加入小程序的Request合法域名中
App({
  ...
})
```
### Uniapp
#### vue2
```js
// src/main.js
//...
wTracker.init({
  apiUrl: 'xxx',
  keyCode: 'xxx',
  framework: {
    uni: Vue
  }
})
//...
```
#### vue3
```js
// src/main.js
export function createApp() {
  //...
  // const app = xxxx;
  wTracker.init({
    apiUrl: 'xxx',
    keyCode: 'xxx',
    framework: {
      uni: app
    }
  });
  // return xxxx
  //...
}

```

### Web(H5)端
#### 多页面（传统html，一页一个html文件）
```js
// todo
```

#### SPA
##### Vue (History 路由)
```js
/**
 * src/main.js
 */
//...
import router from './router';
//...
const app = createApp(App);
//...
wTracker.init({
  apiUrl: 'xxx',
  keyCode: 'xxx',
  framework: {
    Vue: {
      router,
    },
    webMode: 'spa',
  },
});
//...
```

## 方法
### init(Object)
初始化SDK

#### 参数 Object

| 字段                   | 必填 | 类型      | 默认值   | 说明                                                                            |
|----------------------|:--:|---------|-------|-------------------------------------------------------------------------------|
| keyCode              | Y  | string  | null  | 固定值，随项目变动，像服务端索要                                                              |
| apiUrl               | Y  | string  | null  | 服务端接口地址   <br/> <strong><i>针对小程序端，需要将apiUrl的域名加入小程序的Request合法域名中</i></strong> |
| appId                | N  | string  | -     | 小程序AppId，如果是小程序则必填                                                            |
| agentId              | N  | string  | -     | 企微应用 agentid                                                                  |
| debug                | N  | boolean | false | debug模式                                                                       |
| platform             | N  | string  | -     | 当前平台，默认系统会自动判断<br/>如有特殊情况可手动指定平台；<br/>可选值：`mp-wx` \| `web`                    |
| manual               | N  | boolean | false | 是否全手动提交<br/>默认为`false`，sdk会自动上报程序和页面级的`进入` `离开` 行为                            |
| framework            | N  | Object  | -     | 框架信息                                                                          |
| framework.uni        | N  | -       |       | uni实例(如果使用uni app框架则必填，否则无法自动抓取页面访问行为) <br/>  [使用方法](#Uniapp)                 |
| framework.Vue        | N  | Object  | -     |                                                                               |
| framework.Vue.router | N  | -       |       | Vue路由实例，当使用场景是Web并且框架为Vue + Vue Router时，要使用自动上报时必填                            |
| framework.webMode    | N  | string  | spa   | 该配置仅针对Web端；可选值：`spa` ｜ `mpa`; 多页面应用（即传统一页一个html）请指定为`mpa`                     |

### track(action, param, eventCode)
事件上报

#### 参数
| 字段        | 必填 | 类型     | 说明                                                                                                       |
|-----------|:--:|--------|----------------------------------------------------------------------------------------------------------|
| action    | Y  | string | 上报行为: <br/>launch: 应用启动 <br/> enter: 进入页面 <br/> leave: 离开页面 <br/> click: 点击 <br/> ${actionName}: 自定义行为名称 |
| param     | N  | object | 附加参数，格式 {key: value}                                                                                     |
| eventCode | N  | string | eventCode                                                                                                |

### insert(Object)
追加字段
> 部分字段在初始化时无法获取，例如用户的unionId，因此加入数据插入机制，在获取后进行补偿插入

#### 参数
| 字段                | 必填 | 类型     | 说明           |
|-------------------|:--:|--------|--------------|
| unionId           | N  | string | 用户uid        |
| openId            | N  | string | 用户oid        |
| agentId           | N  | string | 企微应用 agentid |
| wechatWorkUserId  | N  | string | 企微用户id       |
| wechatWorkEUserId | N  | string | 企微外部联系人id    |