基于 Uniapp 开发框架的小程序接入¶

更新日志

2026.8.25：

@cloudcare/rum-uniapp 2.2.22：新增 allowedTracingUrls，按完整请求 URL 匹配；allowedTracingOrigins 调整为废弃兼容配置；修复抖音 navigation 和页面栈暂时为空时的页面归属问题。

2026.8.20：

@cloudcare/rum-uniapp 2.2.21：新增页面首次渲染、FP、FCP、LCP、Ready 状态、页面退出原因、setData 分段耗时和平台能力字段，可用于统计慢渲染和白屏候选。

2026.8.11：

@cloudcare/rum-uniapp：新增 allowTraceHeaderWithoutSession 配置，默认值为 false；开启后，当前 Session 未命中 RUM 采样时，命中 allowedTracingOrigins 的请求仍会注入 Trace Header，但不会因此强制采样或上报该 Session 的 RUM 数据。

2022.9.29：初始化参数新增 isIntakeUrl 配置，用于根据请求资源 url 判断是否需要采集对应资源数据，默认都采集。

2022.3.29：

新增 traceType 配置，配置链路追踪工具类型，如果不配置默认为 ddtrace。目前支持 ddtrace、zipkin、skywalking_v3、jaeger、zipkin_single_header、w3c_traceparent 6 种数据类型。
新增 allowedTracingOrigins 允许注入 trace 采集器所需 header 头部的所有请求列表。可以是请求的origin，也可以是正则。

前置条件¶

安装 DataKit。

应用接入¶

登录观测云控制台，进入用户访问监测页面，点击左上角新建应用，即可开始创建一个新的应用。

在右侧，选择安装配置的接入方式，点击右侧的参数配置，填入相关配置参数后，即可复制到项目中使用。

使用方法¶

在 Uniapp 项目入口文件 main.js 头部位置以如下方式引入代码：

NPM¶

VUE 2VUE 3

引入(可参考 uniapp 官方npm 引入方式)

...
import Vue from 'vue'
//#ifndef H5 || APP-PLUS || APP-NVUE || APP-PLUS-NVUE
const { datafluxRum } = require('@cloudcare/rum-uniapp')
// 初始化 Rum
datafluxRum.init(Vue, {
  datakitOrigin: '<DATAKIT ORIGIN>',// 必填，Datakit域名地址 需要在微信小程序管理后台加上域名白名单
  applicationId: '<应用 ID>', // 必填，dataflux 平台生成的应用ID
  env: 'testing', // 选填，小程序的环境
  version: '1.0.0', // 选填，小程序版本
  service: 'miniapp', //当前应用的服务名称
  trackInteractions: true, // 用户行为数据
  sampleRate: 100, //指标数据收集的百分比，100 表示全收集，0 表示不收集
  allowedTracingUrls: ['https://api.example.com/v1/', /https:\/\/.*\.my-api-domain\.com\/v2\//], // 按完整请求 URL 匹配
})
//#endif
....

引入(可参考 uniapp 官方npm 引入方式)

...
//#ifndef H5 || APP-PLUS || APP-NVUE || APP-PLUS-NVUE
import { datafluxRum } from '@cloudcare/rum-uniapp'
// 初始化 Rum
datafluxRum.initVue3({
  datakitOrigin: '<DATAKIT ORIGIN>',// 必填，Datakit域名地址 需要在微信小程序管理后台加上域名白名单
  applicationId: '<应用 ID>', // 必填，dataflux 平台生成的应用ID
  env: 'testing', // 选填，小程序的环境
  version: '1.0.0', // 选填，小程序版本
  service: 'miniapp', //当前应用的服务名称
  trackInteractions: true, // 用户行为数据
  sampleRate: 100, //指标数据收集的百分比，100 表示全收集，0 表示不收集
  allowedTracingUrls: ['https://api.example.com/v1/', /https:\/\/.*\.my-api-domain\.com\/v2\//], // 按完整请求 URL 匹配
})
//#endif
....

CDN¶

VUE 2VUE 3

下载文件本地方式引入(下载地址)

...
import Vue from 'vue'
//#ifndef H5 || APP-PLUS || APP-NVUE || APP-PLUS-NVUE
const { datafluxRum } = require('./dataflux-rum-uniapp.js'); // js文件本地路径
// 初始化 Rum
datafluxRum.init(Vue, {
  datakitOrigin: '<DATAKIT ORIGIN>',// 必填，Datakit域名地址 需要在微信小程序管理后台加上域名白名单
  applicationId: '<应用 ID>', // 必填，dataflux 平台生成的应用ID
  env: 'testing', // 选填，小程序的环境
  version: '1.0.0', // 选填，小程序版本
  service: 'miniapp', //当前应用的服务名称
  trackInteractions: true, // 用户行为数据
  sampleRate: 100, //指标数据收集的百分比，100 表示全收集，0 表示不收集
  allowedTracingUrls: ['https://api.example.com/v1/', /https:\/\/.*\.my-api-domain\.com\/v2\//], // 按完整请求 URL 匹配
})
//#endif
....

下载文件本地方式引入(下载地址)

...
//#ifndef H5 || APP-PLUS || APP-NVUE || APP-PLUS-NVUE
import { datafluxRum } from './dataflux-rum-uniapp.js'; // js文件本地路径
// 初始化 Rum
datafluxRum.initVue3({
  datakitOrigin: '<DATAKIT ORIGIN>',// 必填，Datakit域名地址 需要在微信小程序管理后台加上域名白名单
  applicationId: '<应用 ID>', // 必填，dataflux 平台生成的应用ID
  env: 'testing', // 选填，小程序的环境
  version: '1.0.0', // 选填，小程序版本
  service: 'miniapp', //当前应用的服务名称
  trackInteractions: true, // 用户行为数据
  sampleRate: 100, //指标数据收集的百分比，100 表示全收集，0 表示不收集
  allowedTracingUrls: ['https://api.example.com/v1/', /https:\/\/.*\.my-api-domain\.com\/v2\//], // 按完整请求 URL 匹配
})
//#endif
....

配置¶

初始化参数¶

参数	类型	是否必须	默认值	描述
`applicationId`	String	是		从观测云创建的应用 ID。
`datakitOrigin`	String	是		DataKit 数据上报 Origin； ❗️ 需要在小程序管理后台加上 request 白名单。
`env`	String	否		小程序应用当前环境，如 prod：线上环境；gray：灰度环境；pre：预发布环境；common：日常环境；local：本地环境。
`version`	String	否		小程序应用的版本号。
`service`	String	否		当前应用的服务名称，默认为 `miniapp`，支持自定义配置。
`sampleRate`	Number	否	`100`	指标数据收集百分比，`100` 表示全收集，`0` 表示不收集。
`trackInteractions`	Boolean	否	`false`	是否开启用户行为采集。
`traceType`	Enum	否	`ddtrace`	配置链路追踪工具类型，如果不配置默认为 `ddtrace`。目前支持 `ddtrace`、`zipkin`、`skywalking_v3`、`jaeger`、`zipkin_single_header`、`w3c_traceparent` 6 种数据类型。 ❗️ 1. `opentelemetry` 支持 `zipkin_single_header`、`w3c_traceparent`、`zipkin`、`jaeger`4 种类型。 2. 配置相应类型的 traceType 需要对相应的 API 服务设置不同的 `Access-Control-Allow-Headers`，可参考 APM 如何关联 RUM。
`traceId128Bit`	Boolean	否	`false`	是否生成 128 位 `traceID`，与 `traceType` 对应，目前支持 `zipkin`、`jaeger`。
`allowedTracingUrls`	Array	否	`[]`	允许注入 Trace Header 的完整请求 URL 匹配列表。字符串按 URL 前缀匹配；正则和函数接收完整 URL；对象使用 `{ match, traceType }` 为单条规则指定传播类型。版本要求为 2.2.22 及以上。
`allowedTracingOrigins`	Array	否		已废弃的兼容配置，仅按请求 Origin 匹配；新项目使用 `allowedTracingUrls`。两者同时设置时优先使用 `allowedTracingUrls`。
`allowTraceHeaderWithoutSession`	Boolean	否	`false`	当前 Session 未命中采样时，是否仍为命中 `allowedTracingUrls` 的请求注入 Trace Header。开启后不会强制采样或上报该 Session 的 RUM 数据。
`isIntakeUrl`	Function	否	`function(url) {return false}`	自定义方法根据请求资源 url 判断是否需要采集对应资源数据，默认都采集。返回：`false` 表示要采集，`true` 表示不需要采集。 ❗️ 1. 该参数方法返回结果必须为 Boolean 类型，否则认为是无效参数。 2. 版本要求为 2.1.13 及以上。

Trace Header URL 匹配¶

allowedTracingUrls 使用完整请求 URL 匹配。String 按 URL 前缀匹配，RegExp 和 Function 接收完整 URL；单条规则需要使用不同的传播类型时，可以使用 { match, traceType }：

allowedTracingUrls: [
  'https://api.example.com/v1/',
  /https:\/\/.*\.my-api-domain\.com\/v2\//,
  function (url) {
    return url.indexOf('https://internal.example.com/') === 0
  },
  { match: 'https://otel.example.com/', traceType: 'w3c_traceparent' },
]

通过远程配置下发时，只能使用 JSON 可表示的 String 或 { match: String, traceType }，不能下发 RegExp 和 Function。allowedTracingOrigins 仅用于兼容旧配置；如果两个参数同时存在，SDK 只使用 allowedTracingUrls。

页面性能与白屏候选¶

@cloudcare/rum-uniapp 2.2.21 及以上版本会采集页面生命周期、平台 Performance entry 和 setData 耗时。所有耗时字段上报到观测云后统一为纳秒（ns）。

SDK 不采集屏幕截图，也无法确认骨架屏后的业务内容是否可用。因此，指标只能用于识别性能异常和白屏候选，不能单独证明页面发生了视觉白屏。

平台能力与生命周期¶

字段	类型	说明
`performance_supported`	Boolean	当前平台 Performance Observer 是否订阅成功
`first_render_supported`	Boolean	当前平台是否存在 SDK 可用的首次渲染信号
`view_start_reason`	String	`page_load`、`page_show` 或 `session_renewal`
`view_end_reason`	String	`onHide`、`onUnload` 或 `session_renewal`
`ready_reached`	Boolean	当前页面生命周期是否到达 `onReady`
`first_render_reached`	Boolean	当前页面是否已收到平台首次渲染信号
`ended_before_ready`	Boolean	`page_load` View 结束时是否仍未到达 `onReady`
`ended_before_render`	Boolean	支持首次渲染信号时，`page_load` View 是否在首次渲染前结束
`view_is_active`	Boolean	View 是否仍处于活动状态

ended_before_render 只在 first_render_supported=true 时有统计意义。Session 续期只拆分 RUM View，不表示页面重新加载，因此不会生成页面提前退出结论。

渲染与 setData 指标¶

字段	说明
`loading_time`	页面 navigation 与生命周期观测到的最大加载耗时
`page_ready_time`	View 开始到 `onReady` 的耗时
`first_render_time`	微信 `firstRender.duration`；抖音为 `first-paint - navigationStart`
`page_fp`	FP 相对当前页面 navigationStart 的耗时
`page_fcp`	FCP 相对当前页面 navigationStart 的耗时
`page_lcp`	当前页面最近一次 LCP 相对 navigationStart 的耗时
`view_setdata_count`	有效 `setData` 更新样本数
`view_setdata_duration`	所有有效更新的累计耗时
`view_setdata_max_duration`	单次更新最大耗时
`view_setdata_pending_duration`	从进入队列到开始更新的累计等待耗时
`view_setdata_update_duration`	从开始更新到结束的累计执行耗时
`view_setdata_merged_count`	被平台合并处理的更新次数

SDK 会按 route、pageId 和最新 navigationStart 将平台 entry 归属到页面实例，避免快速切页、同路由重建和延迟回调造成跨页面污染。隐藏页、已卸载页面或旧组件的延迟 setData 回调不会计入当前 View。

问题	推荐条件	说明
慢首次渲染	`first_render_time` 大于业务阈值	统计 P75、P95 与超阈值比例
退出前未首次渲染	`ended_before_render=true`	高置信度白屏候选，但用户主动快速返回也会命中
长时间未 Ready	`page_ready_time` 大于业务阈值	反映生命周期或初始化阻塞，不等同于视觉白屏
退出前未 Ready	`ended_before_ready=true`	结合 `view_end_reason` 与停留时长排除快速离开
FCP/LCP 慢	`page_fcp` 或 `page_lcp` 大于业务阈值	用于观察内容出现和主要内容稳定速度

基于 Uniapp 开发框架的小程序接入¶

前置条件¶

应用接入¶

使用方法¶

NPM¶

CDN¶

配置¶

初始化参数¶

Trace Header URL 匹配¶

页面性能与白屏候选¶

平台能力与生命周期¶

渲染与 setData 指标¶

推荐统计口径¶

文档内容是否对您有帮助？

基于 Uniapp 开发框架的小程序接入¶

前置条件¶

应用接入¶

使用方法¶

NPM¶

CDN¶

配置¶

初始化参数¶

Trace Header URL 匹配¶

页面性能与白屏候选¶

平台能力与生命周期¶

渲染与 setData 指标¶

推荐统计口径¶

文档内容是否对您有帮助？ ×

文档内容是否对您有帮助？