本文适用于直接火山引擎平台上的产品及服务。支持的原生小程序包括微信、字节、支付宝和百度小程序，但不支持 taro 或者 uniapp 之类的框架。

使用限制

目前SDK仅限中国大陆应用使用（不包括港澳台地区）。

快速接入

NPM

npm install 之后要执行"构建 npm"指令。

https://www.npmjs.com/package/@apm-insight-web/rangers-mini-sdk

npm install @apm-insight-web/rangers-mini-sdk

// 必须在 App.js 中，配置 App 之前调用 vemars.init 方法进行初始化

const vemars = require('@apm-insight-web/rangers-mini-sdk').default
// 或者
import vemars from '@apm-insight-web/rangers-mini-sdk'

vemars.init({ // init 方法只能调用一次
  aid: '你的app_id', // 必填，这里写入在平台上注册的aid
  userId: 'xxx' // 选填，可以写入用户 UUID，不填将生成一个随机 ID
})

App({
    onLaunch: function() {
        userLogin().then(userId => {
            vemars.config({ // 也可以在登录成功之后再设置 userId
                userId: userId
            })
        })
    },
    ...
})

CDN

// 必须在 App.js 中，配置 App 之前调用 vemars.init 方法进行初始化

// 源文件使用，假设放在 vendors/rangers-mini-sdk/ 目录下，则在 app.js 中通过相对路径引用
const vemars = require('./vendors/rangers-mini-sdk/index.0.0.22.cn.js').default
// 如果你的小程序编译环境支持ES6语法，可以使用
import vemars from './vendors/rangers-mini-sdk/index.0.0.22.cn.js'

vemars.init({ // init 方法只能调用一次
  aid: '你的app_id', // 必填，这里写入在平台上注册的aid
  userId: 'xxx' // 选填，可以写入用户 UUID，不填将生成一个随机 ID
})

App({
    onLaunch: function() {
        userLogin().then(userId => {
            vemars.config({ // 也可以在登录成功之后再设置 userId
                userId: userId
            })
        })
    },
    ...
})

配置上报域名白名单

请在小程序管理后台的 request 合法域名列表中添加你的上报域名，否则上报请求会被拦截。

目前 SDK 内置上报域名为 https://tbm.snssdk.com。

集成DataFinder

如果您同时购买了DataFinder的产品，需要打通UserID，可使用以下方式：

import vemars from './vendors/data-finder/rangers'
... // 配置 Finder 实例

vemars.init({ // init 方法只能调用一次
  aid: '你的app_id', // 必填，这里写入在平台上注册的aid
  finderInstance: $$Ranger // 将 DataFinder 实例传入，则会从 DataFinder 获取 UUID，无需设置userId
})

App({
    onLaunch: function() {
        userLogin().then(userId => {
            vemars.config({ // 也可以在登录成功之后再设置 userId
                userId: userId
            })
        })
    },
    ...
})

详细配置

在上文示例中只配置了 aid 和 userId， 除了这两个配置项以外，还有多个配置项。所有支持的配置项字段名和字段意义如下：

export type UserOptions = {
  aid: number
  // 采样类 自0.1.1开始支持  
  sampleRate?: number
  // 开关类
  hookPath?: boolean // 是否监听页面路由变化
  hookRequest?: boolean // 是否监听网络请求
  enableCapture?: boolean // 是否捕获异常
  // 上下文
  context?: Record<string, any>
  // 上报相关
  maxBatchReportLength?: number // 最大聚合条数，默认10
  batchReportWait?: number // 聚合等待时间，默认1000，单位ms
  // 用户相关
  userId?: string
  sessionId?: string
  reportDomain?: string // 私有化上报域名
  reportPath?: string // 私有化上报路径
  pid?: string // 页面标识
  maxBreadcrumbs?: number // 最大面包屑长度
  // finder
  finderInstance?: FinderInstance
}

验证上报

调用 init 之后，SDK 会调用 getSystemInfo 与 getNetworkType 收集一些环境信息，并在首页的 Page.onShow 触发时上报 PV 事件，可以在调试器控制台看到 /monitor_microapp/collect 的请求。

功能介绍

• 错误收集：SDK 会监控 App.onError 与 App.onUnhandledRejection 事件，并收集上报错误信息，也可以尝试主动触发
• PV统计：onShow 获取页面路由变化，发送PV
• 性能监控： 监听page生命周期，上报页面性能
• setData 性能： 通过 hook setData 监听性能
• 请求监控： 通过hook request 监控请求

API

以下是引入的监控实例暴露的所有接口 以及 接口的功能解释，可按需调用。

vemars.init(config?: UserConfig) => void

初始化监控实例， UserConfig 同上文 详细配置中的类型。

vemars.config(config?: Partial) => void

配置监控实例， UserOptions 同上文 详细配置中的类型。

interface MutableConfig {
  context: Record<string, any>
}

vemars.capture(error: Error) => void

主动捕获错误。

vemars.report(event: ReportEvent) => void

自定义上报各种类型的事件, 各种上报类型不在此赘述。

type ReportEvent =
  | PageviewReportEvent
  | JsErrorReportEvent
  | RequestReportEvent
  | SetDataReportEvent
  | PageFirstLoadReportEvent
  | PageOnReadyReportEvent

vemars.addBreadcrumb(type: BreadcrumbType, payload: any) => void

自定义上报面包屑， payload 会被解构到面包屑中。

enum BreadcrumbType {
  DOM = 'dom',
  HTTP = 'http',
}

vemars.sendNow() => void

为了减少每秒请求数，SDK 采取批量合并上报策略，每收集 10 个上报事件或距离上个发送请求间隔 1 秒才会发送上报请求， 调用此方法可以立刻上报。