本文介绍如何在小程序Pro中使用SDK调用API。

使用说明

全文的client代表的是SDK实例。

初始化

init

调用后开始拉取服务端配置以及监听各个事件。为了确保监听到的信息比较完善，请将init放到最前面。推荐在App初始化前调用该方法，随后在start调用后开始上报。

interface InitConfig  {
  aid: number // 项目唯一标识，必传
  token: string // 项目 token，必传
  userId?: string // 用户id，
  deviceId?: string // 设备id  
  useLocalConfig?: boolean // 是否只使用本地配置，默认为false，则会和平台配置的规则进行merge操作
  // 采样配置 和 插件配置 的具体配置可在详细配置中查看
  sample?: SampleConfig // 采样配置
  plugins?: { ... } // 插件配置,详情见 「插件配置」 页面
  domain?: string// 上报域名。中国发布的应用：上报到中国大陆服务器，域名为https://apmplus.volces.com。海外发布的应用：上报到马来西亚柔佛服务器，域名为https://apmplus.ap-southeast-1.volces.com。如不配置，默认上报到中国大陆服务器。
}
client.init(c: InitConfig) =>  void // 类型

// 调用
client.init({
   aid: 66, // 替换成您的aid 
   token:'xxx-xxx' // 替换成您的token
})

config

更改通用属性上下文，在start之前调用可用于异步设置userId和deviceId。

interface MiniProgramUserConfig {
  pid: string
  userId: string
  deviceId: string,
}
client.config(config: MiniProgramUserConfig) =>  void // 类型

// 调用：用于异步修改通用属性: userId & deviceId
client.config({
    userId: 'userId_test',
    deviceId: 'deviceId_test'
})

start

开始上报数据，一般在异步修改通用属性后触发。

client.start()

举个例子：如果您需要等代码某个接口下发后拿到UserId后再上报，可以像如下伪代码方式接入：

// 开始收集监控数据
client.init({
   aid: 123, // 替换成您的aid 
   token:'xxx-xxx' // 替换成您的token
})
App({
  onLaunch() {},
  onShow() {
    getUserId().then(res => {
      // 设置 userId
      client.config({
        userId: res.userId
      })
      // 开始上报数据
      client.start()
    })
  },
})

更改通用上下文

context.set

设置自定义维度，context是一个全局维度的上下文，对所有事件生效。context更新后，只对之后包装的事件生效。
因为init时会发送一些事件，比如pageview。如果要设置一些初始化的上下文，需要在init之前设置context。

interface ContextAgent {
  set: (k: string, v: any) => ContextAgent
  merge: (ctx: Record<string, any>) => ContextAgent
  delete: (k: string) => ContextAgent
  clear: () => ContextAgent
  get: (k: string) => string
  toString: () => Record<string, string>
}

client.context.set('key', 'value') // 设置context中的单个key
client.context.merge({ key: 'value' })  // 将context 和 传入的对象合并，生成新的context
client.context.delete('key')  // 删除context中的某个key
client.context.clear() // 清空context

主动上报

sendPageview

上报一次PV，重复上报相同PID时也会上报。

client.sendPageview(pid: string) =>  void //类型

client.sendPageview('pid_test') // 调用

sendPageviewWithHide

对当前的PID进行结算停留时长，调用一次就会消费掉当前PID，多次调用时，只会上报一次。

const enum PageviewSourceType {
  init = 'init',
  history = 'history',
  user_set = 'user_set',
  hide = 'hide',
  unload = 'unload',
}
client.sendPageviewWithHide(source = PageviewSourceType.hide) =>  void // 类型

client.sendPageviewWithHide('hide') // 调用

sendEvent

上报一个自定义事件。

interface CustomEventPayload {
  /** 自定义事件名称 */
  name: string
  /** metrics 上报的是可以被度量的值，也就是数值 */
  metrics?: { [key: string]: number }
  /** categories 上报的是分类，维度，用来做筛选，分组 */
  categories?: { [key: string]: string }
}
client.sendEvent(data:CustomEventPayload) =>  void // 类型

// 调用
client.sendEvent({
  name:  "name_test",
  metrics: {
    count:  1,
    },
  categories: {
    user:  "user_x",
    pathname:  "xxxxx",
    },

})

sendLog

上报一个自定义日志。

export  interface  CustomLogPayload  {
  /** 额外的附加信息， 在上报的时候 number会被分流到metric string会被分流到categories */
    extra?: { [key: string]: string | number }  //    /** 自定义事件内容，可以是日志或者对象的 JSON 表示 */
  content: string
  /** 自定义事件级别，默认是 info, 可枚举项 debug | info | warn | error */
    level?:  'debug'  |  'info'  |  'warn'  |  'error'
}

client.sendLog(data:  CustomLogPayload) =>  void // 类型
// 调用
client.sendLog({
  level:  'debug',
  content:  'function `test` was invoked',
  extra: {
    num:  1,
    country:  'SomeCountry'
    }

})

captureException

手动捕获JS异常，传入错误的name、message、stack即可。

export interface JsError {
  /** 错误名称 */
  name?: string
  /** 错误信息 */
  message: string
  /** 堆栈 */
  stack?: string
  /** 错误文件名 */
  filename?: string
  lineno?: string
  colno?: string
}
client.captureException(error: JsError, extra?: { [key: string]: string }) => void // 类型

// 调用
client.captureException({
   name: 'Error',
   message: 'Test Error'
})

addBreadcrumb

添加用户行为栈，不会单独上报，JS Error上报时携带该上报信息。

interface Breadcrumb {
  /** route | http */
  type: string
  /** methodName | url */
  message: string
  /** errMsg | post,get | tap */
  category: string
  /** route {url} | http {mehtod,url,status_code} */
  data?: { [key: string]: string }
 }
client.addBreadcrumb(breadcrumb: Breadcrumb) => void // 类型

client.addBreadcrumb({
    type: 'route',
    message: 'navigateTo',
    category: 'ok',
    data: 'pages/index/index'
})

生命周期

您需要了解Client中做了什么或需要调试Client时，可以使用以下生命周期函数。

init

监听实例被初始化。

client.on('init',() => {
  ...
})

start

监听实例开启上报。

client.on('start', () => {
   ...
})

beforeConfig

监听实例配置变更之前，可拿到新的配置。

client.on('beforeConfig', (config: Partial<Config>) => {
    ...
})

config

监听实例配置变更后的瞬间。

client('on', 'config', () => {
    ...
})

provide

监听实例被挂载属性的瞬间，可拿到属性名。

client('on', 'provide', (name: string) => {
   ...
})

report

监听事件被监控插件发送的瞬间，用于为事件补充上下文，返回Falsy类型则不上报。

type Falsy = false | null | undefined
client.on('report', (ev: ReportEvent): ReportEvent | Falsy => {
    ...
    return ev
})

beforeBuild

监听事件被包装上下文之前的瞬间，能够拿到即将被包装的数据，返回Falsy类型则不上报。

type Falsy = false | null | undefined
client.on('beforeBuild', (ev: ReportEvent): ReportEvent | Falsy => {
    ...
    return ev
})

build

监听事件被包装上下文之后的瞬间，能够拿到即将上报的数据，返回Falsy类型则不上报。

type Falsy = false | null | undefined
client.on('build', (ev: SendEvent): SendEvent | Falsy => {
    ...
    return ev
})

beforeSend

监听事件被发送之前的瞬间，返回Falsy类型则不上报。

type Falsy = false | null | undefined
client.on('beforeSend', (ev: SendEvent): SendEvent | Falsy => {
    ...
    return ev
})

send

注册事件发送之后的回调。

interface Callback<T> {
  (arg: T): void
}
client.on('send', (e: Callback<SendEvent>) => {
    ...
})

beforeDestroy

注册实例销毁之前的回调。

client('on', 'beforeDestroy', () => {
   ...
})

主动触发

getSender().flush()

立即上报数据。默认情况下，SDK会缓存数据至队列并批量发送，也会在小程序关闭前强制上报所有已缓存数据，以此减少网络连接损耗。当用户想要在某个时刻强制上报数据，可以调用以下方法：

// 需要在 client init 后才能调用，所以需要在 init 回调中
client('on', 'init', () => {
   client.getSender().flush()
})