@cloudtrek/wxapp-radar-sdk
TypeScript icon, indicating that this package has built-in type declarations

4.1.0-alpha.8 • Public • Published

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

已支持的功能

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

模式

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

一、安装SDK

1、npm安装

  1. 在小程序package.json目录下执行命令安装sdk。
npm i @cloudtrek/wxapp-radar-sdk --save
  1. 点击开发者工具中的菜单栏:工具 --> 构建 npm。

  2. 勾选“使用 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 '@cloudtrek/wxapp-radar-sdk';

const wxappSDK = require('/libs/index.4.1.0.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上报错误日志
  • 系统自动追踪参数说明
字段 说明
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)

  • 定义:系统事件上报方法;

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

  • 事件表中的页面部分的事件: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 是否标记为云启系统事件
  • 上报示例:
// 进入商品详情页上报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

Package Sidebar

Install

npm i @cloudtrek/wxapp-radar-sdk

Weekly Downloads

8

Version

4.1.0-alpha.8

License

ISC

Unpacked Size

49 kB

Total Files

17

Last publish

Collaborators

  • wginit