You need to enable JavaScript to run this app.
导航

小程序SDK接入

最近更新时间2022.09.26 10:18:39

首次发布时间2021.06.17 20:53:29

本文适用于直接火山引擎平台上的产品及服务。支持的原生小程序包括微信、字节、支付宝和百度小程序,但不支持 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 会调用 getSystemInfogetNetworkType 收集一些环境信息,并在首页的 Page.onShow 触发时上报 PV 事件,可以在调试器控制台看到 /monitor_microapp/collect 的请求。

image.png

功能介绍

  • 错误收集:SDK 会监控 App.onErrorApp.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 秒才会发送上报请求, 调用此方法可以立刻上报。