本文介绍如何在小程序Pro中使用SDK调用API。
全文的client代表的是SDK实例。
调用后开始拉取服务端配置以及监听各个事件。为了确保监听到的信息比较完善,请将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 })
更改通用属性上下文,在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' })
开始上报数据,一般在异步修改通用属性后触发。
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是一个全局维度的上下文,对所有事件生效。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
上报一次PV,重复上报相同PID时也会上报。
说明
程序中有relaunch事件可以重新渲染当前页面。
client.sendPageview(pid: string) => void //类型 client.sendPageview('pid_test') // 调用
对当前的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') // 调用
上报一个自定义事件。
注意
事件格式不符合将会试图转换,无法转换的事件会被上报,但是服务端无法消费。
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", }, })
上报一个自定义日志。
注意
日志格式不符合会试图转换,无法转换的日志会被上报,但是服务端无法消费。
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' } })
手动捕获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' })
添加用户行为栈,不会单独上报,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时,可以使用以下生命周期函数。
监听实例被初始化。
client.on('init',() => { ... })
监听实例开启上报。
client.on('start', () => { ... })
监听实例配置变更之前,可拿到新的配置。
client.on('beforeConfig', (config: Partial<Config>) => { ... })
监听实例配置变更后的瞬间。
client('on', 'config', () => { ... })
监听实例被挂载属性的瞬间,可拿到属性名。
client('on', 'provide', (name: string) => { ... })
监听事件被监控插件发送的瞬间,用于为事件补充上下文,返回Falsy类型则不上报。
type Falsy = false | null | undefined client.on('report', (ev: ReportEvent): ReportEvent | Falsy => { ... return ev })
监听事件被包装上下文之前的瞬间,能够拿到即将被包装的数据,返回Falsy类型则不上报。
type Falsy = false | null | undefined client.on('beforeBuild', (ev: ReportEvent): ReportEvent | Falsy => { ... return ev })
监听事件被包装上下文之后的瞬间,能够拿到即将上报的数据,返回Falsy类型则不上报。
type Falsy = false | null | undefined client.on('build', (ev: SendEvent): SendEvent | Falsy => { ... return ev })
监听事件被发送之前的瞬间,返回Falsy类型则不上报。
type Falsy = false | null | undefined client.on('beforeSend', (ev: SendEvent): SendEvent | Falsy => { ... return ev })
注册事件发送之后的回调。
interface Callback<T> { (arg: T): void } client.on('send', (e: Callback<SendEvent>) => { ... })
注册实例销毁之前的回调。
client('on', 'beforeDestroy', () => { ... })
立即上报数据。默认情况下,SDK会缓存数据至队列并批量发送,也会在小程序关闭前强制上报所有已缓存数据,以此减少网络连接损耗。当用户想要在某个时刻强制上报数据,可以调用以下方法:
// 需要在 client init 后才能调用,所以需要在 init 回调中 client('on', 'init', () => { client.getSender().flush() })