0.4.0 • Published 17 days ago
@tingyun-sdk/weex v0.4.0
@tingyun-sdk/weex
tingyun weex sdk
开始
安装
npm install @tingyun-sdk/weex --save使用
- 在weex项目源码目录下，新建
agent目录，并创建init.js文件, 在文件中引入, 初始化探针，并导出探针对象供外部使用
src/agent/init.js
import tingyun from '@tingyun-sdk/weex'
// 启动
tingyun.init({
domain: '<数据上传地址>',
token: '<应用token>',
key: '<应用key>'
// 其他配置
})
export default tingyun- domain: 数据上传地址, 可在控制台获取。如果不指定协议，默认发送https
- token: 应用唯一标识, 可在控制台获取
- key: 应用key，在使用tingyun跨应用追踪时必填
- 打开weex打包app的入口文件, 在文件顶部引入探针初始化文件
// 为了保证探针功能正常，必须在顶部引入
import tingyun from '@/agent/init'注意：
- 如果项目中存在多个入口文件打包出多个Weex页面，每个需要监控的Weex页面的入口文件都需要嵌码。
基本用法
Vue路由监控
调用探针API wrapVueRouter并传入router对象
配置示例：
// 引入探针
import tingyun from '@/agent/init'
import App from '@/App.vue'
import Home from '@/routes/Home.vue'
import About from '@/routes/About.vue'
import VueRouter from 'vue-router'
Vue.use(VueRouter)
const router = new VueRouter({
mode: 'abstract',
routes: [
{ path: '/', redirect: '/home' },
{ path: '/home', component: Home },
{ path: '/about', component: About }
]
})
// 调用wrapVueRouter接口传入路由对象
tingyun.wrapVueRouter(router)
new Vue({
el: '#root',
router: router,
render: (h) => h(App)
})JS错误上报
确认 Vue.config.errorHandler 监控有效
探针默认会对Vue.config.errorHandler的触发进行监控并上报JS错误。
如果项目本身也注册了Vue.config.errorHandler, 当errorHandler在入口文件同步注册时，通常情况下探针可以自动监控。
但当errorHandler注册时机较晚时, 探针自动监控会失效，此时，需要在自定义的errorHandler中使用探针API captureException手动上报:
操作步骤如下:
- 在自定义的errorHandler内上报JS错误
Vue.config.errorHandler = function (err) {
// 上报错误
tingyun.captureException(err)
}- 关闭JS错误自动监控开关，防止重复监控
agent/init.js:
tingyun.init({
// ...
jsError: {
// 关闭JS错误自动监控
enabled: false
}
})手动上报错误
部分JS错误触发后，不会触发Vue.config.errorHandler, 此时可以手动上报JS错误
import tingyun from '@/agent/init'
// ...
try {
// ...
} catch (e) {
tingyun.captureException(e)
}设置用户ID
import tingyun from '@/agent/init'
// ...
tingyun.setUid('<用户id>')高级用法
自定义操作
可以通过API newAction自定义操作
下面示例演示一个提交订单操作
import tingyun from '@/agent/init'
//...
export default {
methods: {
submitOrder(orderId) {
// 创建一个名称为 submitOrder 的操作
const action = tingyun.newAction({
key: 'submitOrder'
})
fetch(
{
url: '...',
method: 'POST',
body: '...'
},
function (response) {
if (response.ok) {
// 提交订单成功, 结束操作
action.end()
} else {
// 提交订单失败, 结束操作，标记操作失败，并上传失败的订单号
action.end({
status: 'fail',
context: {
orderId: orderId
}
})
}
}
)
}
}
}基本使用方式:
- 使用
newAction创建操作，获取操作对象，调用API时操作同时开始 - 使用操作对象
end方法，结束并上报操作。操作会包含操作持续时间内发起的请求 - 在
end方法参数中设置context属性上报自定义数据，设置status属性来设置操作的成功失败状态
更多使用方式参考API说明文档
配置采集参数
探针支持配置采集stream模块fetch接口发送请求的 URL参数，请求头，请求体，返回头和返回体。
配置格式:
tingyun.init({
// ...
common: {
paramCollection: [
{
// number
type: <采集位置类型>
key: '<采集字段名>'
},
...
]
}
})type取值：
- 1: URL
- 2: 请求头
- 3: 请求体, 支持JSON字符串格式的请求体 和 application/x-www-form-urlencoded 格式的请求体，支持配置JSON Path
- 4: 返回头
- 5: 返回体, 支持JSON格式返回体, 支持配置JSON Path
配置示例：
tingyun.init({
// ...
common: {
paramCollection: [
// 从URL参数中获取token参数
{
type: 1,
key: 'token'
},
// 从请求头中获取 content-type 请求头
{
type: 2,
key: 'content-type'
},
// 从请求体中获取delay字段
{
type: 3,
key: 'delay'
},
// 从返回头中获取 Server-Timing 返回头
{
type: 4,
key: 'Server-Timing'
},
// 配置JSON Path从返回体中获取信息
// 假如返回体为：{"code":200,"message":"成功","data":[{"id":1,"name":"xxx","lon":116.43,"lat":39.92}]}
// 下面配置从返回体data字段的数组的第一项中获取name字段
{
type: 5,
key: 'data[0].name'
}
]
}
})API
setUid
tingyun.setUid(username)参数:
- username: 用户名。字符串类型。必须
wrapVueRouter
tingyun.wrapVueRouter(router)参数:
- router VueRouter实例对象
captureException
tingyun.captureException(err[, options])参数:
- err: 错误对象
- message：错误信息 可选
- stack：错误堆栈 可选
- fileName： string 指定错误文件名，可选, 不传自动从stack解析
- lineNumber： number 指定错误行号，可选, 不传自动从stack解析
- columnNumber: number 指定错误列号，可选, 不传自动从stack解析
- options: 额外选项。对象类型。可选
- contexts: 额外附加数据。对象类型。可选
- breadcrumbs: 面包屑数据。数组。可选
数据项类型说明
- timestamp: number 毫秒时间戳，必须
- type: string 类型，必须
- category: string 分类，必须
- level: string 等级， 必须
- message: string 信息，可选
- data: object 附加数据，可选
- category：错误类型。可选。取值： js（JS错误, 默认）或other（其他错误）
newAction
const action = tingyun.newAction(options)参数:
- options 操作配置项对象
- key: 操作名称。字符串类型。必须
- context: 操作包含的附加数据。对象类型。可选
- duration: 设置操作时间, 对于立即发送的操作, 可以设置此配置指定操作时间。number类型。可选
- timeout: 操作超时时间, 默认10分钟, 超时后的操作被丢弃, number类型, 可选
- status: 设置操作状态success或fail, 默认success, 只在立即发送模式的操作有效。字符串类型。可选
- immediate: 是否立即发送此操作, boolean类型, 默认为false。可选
返回:
返回操作对象action, 可以用于结束操作。 action对象包含下列函数。
- end: 结束操作
action.end(options)- options 结束操作配置对象。可选
- context: 操作包含的附加数据。对象类型。可选
- status: 设置操作状态success或fail, 默认success。字符串类型。可选
- options 结束操作配置对象。可选
配置项
// 探针支持的全部配置项
export type ConfigOptions = {
// 数据上传地址 如果不指定协议默认发https
domain: string
// 应用token
token: string
// 应用key, 配置tingyun跨应用追踪时必填
key?: string
// 应用版本
release?: string
// vue router对象
router?: VueRouterInstance
// 日志打印配置
logger?: (tag: string, message: string) => void
// 公共配置
common?: {
// 监控路由加载, 默认true
routerEnabled?: boolean
// 采集参数配置
paramCollection?: ParamCollectConfig[]
// 使用domain原始值作为上传地址 默认false 探针检查domain开头不是http:或https:会强制拼接https协议
// 如果要使用完全自定义的地址发送, 将此选项设为true
useRawDomain?: boolean
}
// JS错误监控配置
jsError?: {
// 自动监控JS错误开关, 默认true
enabled?: boolean
// 接收native监控到js错误后发送的事件, 默认true
nativeErrorEnabled?: boolean
// 上报空文件名的js错误, 默认true
uploadEmptyFileErrors?: boolean
// 使用globalEvent模块时注册的事件名称, 默认tingyunWeexError
nativeErrorEventName?: string
}
// Ajax监控配置
ajax?: {
// Ajax监控总开关, 默认true
enabled?: boolean
}
// 跨应用追踪配置
requestTracing?: {
// trace propagator配置, 默认tingyun, 可选值: tingyun, sw8, w3c-trace-context
propagators?: string[]
// 指定加入propagator头的URL，包含关系
propagationTargets?: string[]
}
}
type VueRouterInstance = {
afterEach: any
[key: string]: any
}
const ParamCollectTypes = {
URL: 1,
REQ_HEADER: 2,
REQ_BODY: 3,
RES_HEADER: 4,
RES_BODY: 5
} as const
type ParamCollectType =
(typeof ParamCollectTypes)[keyof typeof ParamCollectTypes]
// 采集参数配置项
type ParamCollectConfig = {
type: ParamCollectType
key: string
}