@tingyun-sdk/weex

tingyun weex sdk

开始

安装

npm install @tingyun-sdk/weex --save

使用

1. 在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跨应用追踪时必填

2. 打开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手动上报:

操作步骤如下:

1. 在自定义的errorHandler内上报JS错误

Vue.config.errorHandler = function (err) {
  // 上报错误
  tingyun.captureException(err)
}

2. 关闭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。字符串类型。可选

配置项

// 探针支持的全部配置项
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
}