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

已支持的功能

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

模式

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

一、安装SDK

1、npm安装

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

npm i wxapp-amazing-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

二选一安装即可

二、引用SDK

1、npm引用

在app.js 中引入sdk。

import wxappSDK from 'wxapp-amazing-radar-sdk';
或
const wxappSDK = require('/libs/index.min.js')

三、初始化

// 初始化
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上报错误日志 | | timeout | number | 否 | 60000 | API请求超时时间 |

• 系统自动追踪参数说明

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

• 示例

// 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, success, fail)

• 定义：系统事件上报方法；

• 需要上报的系统事件：参考云启系统事件上报事件定义表

• 事件表中的页面部分的事件：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 | 是否标记为云启系统事件 |

• success: 上报成功回调

• fail: 上报失败回调

• 上报示例：

// 进入商品详情页上报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是通过外部传入获取的。则可通过以下方式处理：

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

4、getRadarParam

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

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

5、disableSDK

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

getApp().wxappSDK.disableSDK()

6、enableSDK

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

getApp().wxappSDK.enableSDK()

7、destroy

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

getApp().wxappSDK.destroy()

8、getSdkStatus

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

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

9、usePlugin(name, options)

• 定义：使用插件。

• SDK已支持插件：

• autoTrack: 参数自动追踪

• shareLongTrack：分享链接长链路跟踪

• 例子：

// 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://sentry.c2star.com