# @cloudtrek/wxapp-radar-sdk

> 小程序雷达SDK

Latest version **4.1.0-alpha.8** (published 2023-02-13) · ISC license · 0 weekly downloads

## Install

```sh
npm install @cloudtrek/wxapp-radar-sdk
pnpm add @cloudtrek/wxapp-radar-sdk
yarn add @cloudtrek/wxapp-radar-sdk
bun add @cloudtrek/wxapp-radar-sdk
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.1.0-alpha.8 |
| Published | 2023-02-13 |
| First published | 2023-02-08 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 47.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | wginit |
| Maintainers | wginit |
| Keywords | cloudtrek, wxapp-radar-sdk |

## Links

- npm: https://www.npmjs.com/package/@cloudtrek/wxapp-radar-sdk
- npm.io page: https://npm.io/package/@cloudtrek/wxapp-radar-sdk

## Recent versions

- 4.1.0-alpha.8 (latest) — 2023-02-13
- 4.1.0-08-beta — 2023-02-10
- 4.1.0-07-alpha — 2023-02-10
- 4.1.0-06-alpha — 2023-02-09
- 4.1.0-05-alpha — 2023-02-09
- 4.0.16-02-alpha — 2023-02-08
- 4.0.16-01-alpha — 2023-02-08

## README

# 云启雷达-小程序SDK开发文档

### 已支持的功能

- 自动收集小程序Pv，浏览页面时长， 分享页面统计
- 设备信息及小程序基础信息收集
- 自定义事件上报(track方法)
- 异步参数追加(trace方法)
- 参数自动跟踪(系统参数+自定义参数)插件
- 接入sentry监控sdk稳定性
- 分享长链路跟踪(ct_link_id)插件
- TypeScript 支持

## 模式

因业务扩展，后续会采用 SDK = CORE + plugin(插件) 模式，即CORE只保留系统内置事件上报，所有的业务需求都用插件来实现。plugin分系统插件和开发者自定义插件，系统插件目前有参数自动追踪，分享长链路跟踪插件。

## 一、安装SDK

#### 1、npm安装

1. 在小程序package.json目录下执行命令安装sdk。

```javascript
npm i @cloudtrek/wxapp-radar-sdk --save
```

2. 点击开发者工具中的菜单栏：工具 --> 构建 npm。

3. 勾选“使用 npm 模块”选项。

#### 2、下载本地文件

云启SDK下载地址：[https://arch-1255455723.cos.ap-guangzhou.myqcloud.com/SDK/@cloudtrek/wxapp-radar-sdk/v4/index.4.1.0.min.js](https://arch-1255455723.cos.ap-guangzhou.myqcloud.com/SDK/@cloudtrek/wxapp-radar-sdk/v4/index.4.1.0.min.js)

> 二选一安装即可

## 二、引用SDK

#### 1、npm引用

在app.js 中引入sdk。

```javascript
import wxappSDK from '@cloudtrek/wxapp-radar-sdk';
或
const wxappSDK = require('/libs/index.4.1.0.min.js')
```

## 三、初始化

```javascript
// 初始化
wxappSDK.init({
    serviceUrl: 'https://arch-st.c2star.com/api/v3/collect', // 数据上报地址
    origin: 'cloudtrek',  // 当前小程序name简称
    customer: wx.getStorageSync('unionid') || '', // 用户unionid，可以拿到就需要上报
    openid: wx.getStorageSync('openid') || ''  // 用户openid, 可以拿到就需要上报
});

App({
  ...,
  wxappSDK,  // 全局注册wxappSDK, 后续通过此实例方法上报事件
})

```

> 查看当前SDK版本：wxappSDK.version
>
## 四、API

#### 1、init(config)

- 定义：SDK初始化配置方法；
- config 的完整配置如下：

| 参数名 |  类型 | 是否必填 | 默认值 | 说明 |
| :----: | :---: | :----: | :---: |:---: |
| serviceUrl | string | 是 | 'https://arch-st.c2star.com/api/v3/radar/collect' | 数据上报地址 |
| sentryUrl | string | 否 | - | sentry错误日志收集 |
| origin | string | 是 | 'unknow' | 数据来源标识([0-9a-z\.]{4,16}), 小程序名称英文简写 |
| customer | string | -  | - | 顾客唯一标识(unionid)，有则必传 |
| openid | string | - | - | 顾客微信openid，有则必传 |
| guider | string | 是 | - | 导购/店员唯一标识(导购qy_user_id) |
| debug | boolean | 否 | false | 是否开启调试 |
| allowSystem | boolean | 否 | true | 是否收集设备信息 |
| autoPageRadar | object | 否 | - | 页面采集配置 |
| isForbidPv | boolean | 否 | false | 是否禁止sdk自动pv采集 |
| allowSdkErrorReport | boolean | 否 | false | 是否支持收集SDK上报错误日志 |

- 系统自动追踪参数说明

|  字段 | 说明|
|:--: | :--: |
| ct_sid | 导购id |
| ct_gid | 商品id |
| ct_tid | 任务id |
| ct_mid | 素材id |
| ct_source | 场景值 |
| ct_link_id | 链路id |

- 示例

 ```javascript
 // app.js文件
wxappSDK.init({
    debug: false,
    serviceUrl: 'https://arch-st.c2star.com/api/v3/collect',
    origin: 'cloudtrek',  // 当前小程序name简称
    customer: wx.getStorageSync('unionid') || '', // 用户unionid，可以拿到就需要上报
    openid: wx.getStorageSync('openid') || '',  // 用户openid, 可以拿到就需要上报
    guider: '',  // 导购/店员唯一标识(导购qy_user_id)
});
 ```

#### 2、track(params)

- 定义：系统事件上报方法；
- 需要上报的系统事件：参考云启系统事件上报[事件定义表](https://docs.qq.com/sheet/DY0ZLdWh3c2JqQ0hy?tab=BB08J2&c=A1A0P0)
- 事件表中的页面部分的事件：view_page、exit_page、share_page事件SDK会自动收集上报，开发者无需再上报
- 其中商品模块中的share_goods 和share_goodsposter 为用户端(个人微信端)场景上报, send_goods 和send_goodsposter 为导购端(企业微信端)场景上报，开发者可通过wx.getSystemInfoSync() 来判断当前的运行环境。

- params参数说明

| 参数名 |  类型 | 是否必填 | 默认值 | 说明 |
| :----: | :---: | :----: | :---: |:---: |
| event | string | 是 | - |  事件名称 |
| resource | array | 是 | [] | 事件相关资源唯一标识数组。 例如: 商品ID |
| extra | object | 否  | {} | 扩展字段 |
| isStandardEvent | boolean | 否 | false | 是否标记为云启系统事件 |

- 上报示例：

```javascript
// 进入商品详情页上报view_goods事件
getApp().wxappSDK.track({
  event: 'view_goods', // 事件名称
  resource: ['1232'], // 商品ID(模号)
  extra: {
    room_id: '32432',
    share_openid: '32432'
  }
})

// 在支付成功回调里上报pay_oder事件
getApp().wxappSDK.track({
  event: 'pay_order', // 事件名称
  resource: ['412325454543432432432'], // 订单号
  extra: {
    goods: ['213421', '21321', '214213'],
    skus: [{
      id: '324',
      amount: 2,
      price: 32132
    }],
    order_type: 0,
    total_fee: 23432
  }
})
```

#### 3、trace(config)

- 定义：公共参数追加事件方法

- 调用场景：参数值是异步获取或是变量获取的参数值，可以通过此方法追加到所有事件的公共参数中。

- config 配置参数说明：

| 参数名 |  类型 | 是否必填 | 默认值 | 说明 |
| :----: | :---: | :----: | :---: |:---: |
| customer | string | 否  | - | 顾客唯一标识(unionid)，有则必传 |
| openid | string | 否 | - | 顾客微信openid，有则必传 |
| guider | string | 否 | - | 导购/店员唯一标识(导购qy_user_id) |
| ... | ... | ... | ...| ...|

- 示例场景：1、小程序登录成功后才可拿到用户的unionid，openid。2、导购id是通过外部传入获取的。则可通过以下方式处理：

```javascript
  getApp().wxappSDK.trace({
    customer: 'asdsadrqwew12321321wqe',
    openid: 'arrewfd214324322334',
    guider: 'wginit'
  });
```

#### 4、getRadarParam

- 定义：查看当前完整上报参数
- 例子：

```javascript
const reportParams = getApp().wxappSDK.getRadarParam()
console.log(reportParams)
```

#### 5、disableSDK

- 定义：禁用SDK API, 从禁用之后，sdk不会再上报数据.
- 例子：

```javascript
getApp().wxappSDK.disableSDK()
```

#### 6、enableSDK

- 定义：恢复SDK API
- 例子：

```javascript
getApp().wxappSDK.enableSDK()
```

#### 7、destroy

- 定义：销毁SDK，调用该方法后，sdk本身会释放所占用内存，sdk上报方法均失效。
- 例子：

```javascript
getApp().wxappSDK.destroy()
```

#### 8、getSdkStatus

- 定义：获取sdk当前状态，状态值分 enable 正常、disabled 已禁用、distroy 已销毁。
- 例子：

```javascript
const status = getApp().wxappSDK.getSdkStatus()
console.log(status)  // enable
```

#### 9、usePlugin(name, options)

- 定义：使用插件。
- SDK已支持插件：

- autoTrack: 参数自动追踪
- shareLongTrack：分享链接长链路跟踪

- 例子：

```javascript
// app.ts
// 参数自动追踪
import { autoTrack } from '@cloudtrek/wxapp-plugins'

getApp().wxappSDK.usePlugin(autoTrack, {
    sdkBusinessFields: [], // 自定义追踪参数
    isBusinessFieldsPersistentSave: true, // 是否缓存最近的一次链路跟踪参数到wx.storage中
    businessFieldsExpireAt: 1676000923620   // 缓存过期时间， 格式为时间戳, 精确到ms
})

// 分享链接长链路跟踪
import { shareLongTrack} from '@cloudtrek/wxapp-plugins'

getApp().wxappSDK.usePlugin(shareLongTrack)
```

备注：usePlugin 需在init初始化后调用，name 为插件名，options为插件配置，非必填

## 五、sdk上报错误监控

1. 在初始化时，需设置 sdkErrorReport 为true；
2. 配置小程序安全域名

- 登录[小程序后台](https://mp.weixin.qq.com), 在开发设置里配置以下域名

```javascript
https://sentry.c2star.com
```

---
_Source: https://npm.io/package/@cloudtrek/wxapp-radar-sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._