微信小程序 DataFlux RUM 数据采集 SDK

通过引入 sdk 文件，监控小程序性能指标，错误 log，以及资源请求情况数据，上报到 DataFlux 平台 datakit

使用方法

在小程序的 app.js 文件以如下方式引入代码

npm 引入(可参考微信官方npm 引入方式)

const { datafluxRum } = require('@cloudcare/rum-miniapp')
// 初始化 Rum
datafluxRum.init({
  datakitOrigin: 'https://datakit.xxx.com/', // 必填，Datakit域名地址 需要在微信小程序管理后台加上域名白名单
  applicationId: 'appid_xxxxxxx', // 必填，dataflux 平台生成的应用ID
  env: 'testing', // 选填，小程序的环境
  version: '1.0.0', // 选填，小程序版本
  trackInteractions: true, // 选填，采集自动 Action；不影响 Session 活跃续期
})

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

将下载文件放到小程序源码目录，例如 utils/dataflux-rum-miniapp.js。该分发文件应随项目一起经过开发者工具的代码转换；如需兼容较低版本客户端，请开启“ES6 转 ES5”，并根据项目设置的最低基础库版本完成真机验证。语法和运行时差异请参考 微信小程序 JavaScript 支持情况。

const { datafluxRum } = require('./utils/dataflux-rum-miniapp.js')
// 初始化 Rum
datafluxRum.init({
  datakitOrigin: 'https://datakit.xxx.com/', // 必填，Datakit域名地址 需要在微信小程序管理后台加上域名白名单
  applicationId: 'appid_xxxxxxx', // 必填，dataflux 平台生成的应用ID
  env: 'testing', // 选填，小程序的环境
  version: '1.0.0', // 选填，小程序版本
  trackInteractions: true, // 选填，采集自动 Action；不影响 Session 活跃续期
})

配置

初始化参数

| 参数 | 类型 | 是否必须 | 默认值 | 描述 | | ----------------------------------------------- | -------- | -------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | applicationId | String | 是 | | 从 dataflux 创建的应用 ID | | datakitOrigin | String | 是 | | datakit 数据上报 Origin;注意：需要在小程序管理后台加上request白名单 | | site | String | 是（公网dataway上报方式 必填） | | （SDK 版本要求 >= 2.1.15 ）公网 DataWay 对应站点的域名 注释: 协议（包括：//），域名（或IP地址）[和端口号] 例如：https://www.datakit.com, http://100.20.34.3:8088 | | clientToken | String | 是 （公网dataway 必填） | | （SDK 版本要求 >= 2.1.15 ）公网 DataWay 上报所需的客户端 token，在观测云控制台创建应用时生成 | | env | String | 否 | | 小程序应用当前环境， 如 prod：线上环境；gray：灰度环境；pre：预发布环境 common：日常环境；local：本地环境； | | service | String | 否 | | 小程序应用 服务名称，可用于 apm 关联 tag | | version | String | 否 | | 小程序 应用的版本号 | | sampleRate | Number | 否 | 100 | 指标数据收集百分比: 100表示全收集，0表示不收集 | | sessionSampleRate | Number | 否 | 100 | sampleRate 的别名，用于兼容 Web Browser SDK 的配置命名。如果同时配置 sampleRate 和 sessionSampleRate，优先使用 sampleRate | | remoteConfiguration | Boolean | 否 | false | 是否开启远程配置。SDK 会先按本地配置同步启动，再异步拉取并热更新支持的配置项 | | remoteConfigration | Boolean | 否 | false | remoteConfiguration 的兼容拼写 | | remoteConfigurationFetchTimeout | Number | 否 | 3000 | 远程配置拉取超时时间，单位 ms。超时后回调返回空配置，SDK 保持本地配置运行 | | traceType $\color{#FF0000}{新增}$ | Enum | 否 | ddtrace | 与 APM 采集工具连接的请求 header 类型，目前兼容的类型包括：ddtrace、zipkin、skywalking_v3、jaeger、zipkin_single_header、w3c_traceparent。注： opentelemetry 支持 zipkin_single_header,w3c_traceparent,zipkin三种类型 | | traceId128Bit $\color{#FF0000}{新增}$ | Boolean | 否 | false | 是否以 128 位的方式生成 traceID，与traceType 对应，目前支持类型 zipkin、jaeger | | allowedTracingOrigins $\color{#FF0000}{新增}$ | Array | 否 | [] | 允许注入 trace 采集器所需 header 头部的所有请求列表。可以是请求的 origin，也可以是是正则，origin: 协议（包括：//），域名（或IP地址）[和端口号] 例如：["https://api.example.com", /https:\/\/.*\.my-api-domain\.com/] | | trackInteractions | Boolean | 否 | false | 是否采集点击、触摸、输入等自动 Action。该配置只控制 Action 事件上报，不影响 Session 活跃状态的识别和续期 | | user_id / userId | String | 否 | | 初始化时设置登录用户 ID。也可以在初始化后使用 setUser({ id }) | | beforeSend | Function | 否 | | 数据进入发送队列前的回调，可直接修改事件；返回 false 可丢弃非 view 事件。回调异常不会中断业务或 SDK | | trackResourceQueryString | Boolean | 否 | false | 是否采集请求 URL 的查询串及 resource_url_query。查询串可能包含 token、用户 ID 等敏感信息，仅在确认安全后开启 | | trackRequestErrorResponseBody | Boolean | 否 | false | 是否把失败请求的响应体写入错误堆栈，最大长度由 requestErrorResponseLengthLimit 控制。响应体可能包含敏感数据 | | requestErrorResponseLengthLimit | Number | 否 | 32768 | 失败请求响应体允许写入错误堆栈的最大字符数，仅在开启 trackRequestErrorResponseBody 后生效。必须是大于等于 0 的有限数字 | | trackLaunchOptions | Boolean | 否 | false | 是否采集小程序启动参数中的 query 和 referrerInfo | | isIntakeUrl | Function | 否 | function(url) {return false} | 自定义方法根据请求资源 url 判断是否需要采集对应资源数据，默认都采集。 返回：false 表示要采集，true 表示不需要采集 该参数 方法返回结果必须为 Boolean 类型， 否则认为是无效参数 |

数据脱敏

SDK 默认移除资源和网络错误 URL 中的查询串与 fragment，不采集失败请求响应体，也不采集启动参数。需要保留这些数据时，应逐项开启对应配置，并使用 beforeSend 做最终脱敏：

datafluxRum.init({
  applicationId: 'appid_xxxxxxx',
  datakitOrigin: 'https://datakit.xxx.com/',
  beforeSend: function (event) {
    if (event.resource) {
      event.resource.url_query = undefined
    }
    return true
  },
})

beforeSend 返回 false 时，action、resource、error 等事件不会发送；view 事件用于维持会话和页面上下文，不能通过该回调丢弃。

Session 存储与续期

Session 按 applicationId 使用独立存储键 datafluxRum:session:{applicationId}，不同 RUM 应用不会复用同一个 session ID 或采样结果。存储内容缺失或格式异常时，SDK 会生成新的 session ID，避免复用无效数据。

页面进入、点击、触摸、输入，以及页面已声明 onPageScroll 时的滚动操作，会被视为 Session 活动。Session 活动识别始终生效，与 trackInteractions 无关；关闭 trackInteractions 只会停止自动 Action 采集，不会导致 SDK 已观察到的用户操作无法续期 Session。SDK 不会为未声明滚动监听的页面注入空 onPageScroll，避免改变小程序的滚动性能路径。

连续 15 分钟没有活动会创建新 Session；有活动时最多每分钟更新一次过期时间，单个 Session 最长为 4 小时。新 Session 会重新执行采样，setForcedSession() 仅强制当前 Session。

远程配置与强制采样

远程配置适用于需要在不发版的情况下调整采样率，或根据远程下发的自定义配置决定是否强制采集某个用户会话的场景。典型场景是：远程配置下发 vip_id，小程序侧读取后判断当前用户是否命中，命中后调用 setForcedSession() 强制当前会话采集。

开启远程配置

初始化时设置 remoteConfiguration: true。如果已有历史代码使用了 remoteConfigration 拼写，SDK 也会兼容，但推荐新代码使用 remoteConfiguration。

小程序 SDK 是同步引入，不需要 Web Browser SDK 的异步脚本 onReady 流程。调用 datafluxRum.init() 时，SDK 会立即按本地配置启动并安装 App、Page 和请求代理，远程配置请求不会阻塞首屏采集。请求返回后，SDK 会热更新支持的配置项；getRemoteConfiguration() 读取的是这次初始化请求的缓存结果，不会再次发起网络请求。

远程配置返回前产生的数据按本地配置处理，不会在配置返回后追溯重算。对于本次初始化新建且尚未强制采样的 Session，远程采样率返回后会重新计算当前 Session 的采样结果；从存储恢复的 Session 保留原有采样决定，后续新 Session 使用最新采样率。

const { datafluxRum } = require('@cloudcare/rum-miniapp')

datafluxRum.init({
  applicationId: 'appid_xxxxxxx',
  site: 'https://rum-openway.guance.com',
  clientToken: 'client_token_xxxxx',
  service: 'miniapp-demo',
  env: 'production',
  version: '1.0.0',

  // Web Browser SDK 命名兼容项。miniapp 内部会按 sampleRate 使用。
  sessionSampleRate: 10,

  remoteConfiguration: true,
  trackInteractions: true,
})

开启后，SDK 会请求：

{datakitOrigin|datakitUrl|site}/v1/env_variable?app_id={applicationId}

如果使用公网 DataWay 上报方式，也会附加：

token={clientToken}&to_headless=true

该域名需要加入微信小程序的 request 合法域名白名单。

远程配置字段

远程配置原始 key 使用 Browser SDK 一致的格式：

R.{applicationId}.{配置名}

SDK 会在 getRemoteConfiguration() 返回时去掉前缀，例如：

{
  "R.appid_xxxxxxx.vip_id": "[\"user-1\", \"user-2\"]",
  "R.appid_xxxxxxx.sessionSampleRate": 20
}

回调中拿到：

{
  "vip_id": "[\"user-1\", \"user-2\"]",
  "sessionSampleRate": 20
}

其中 sessionSampleRate 会作为 sampleRate 热更新生效。vip_id 这类自定义字段不会自动影响 SDK 行为，需要业务代码自行读取并处理。

当前支持远程覆盖的初始化配置项：

sampleRate
sessionSampleRate
service
env
version
trackInteractions
traceType
traceId128Bit
allowedTracingOrigins

getRemoteConfiguration

getRemoteConfiguration(callback) 用于获取本次初始化加载并缓存的远程配置。它应在 datafluxRum.init(config) 后调用；如果远程配置请求尚未完成，callback 会等待请求完成后执行。请求已经完成时，callback 会立即收到缓存结果。每次回调收到的都是独立副本，修改它不会影响 SDK 内部配置；callback 抛出异常也不会中断 SDK 或其他回调。

datafluxRum.getRemoteConfiguration(function (remoteConfig) {
  console.log('remote config:', remoteConfig)
})

如果未开启远程配置，或远程配置请求失败、超时、接口返回非 200、返回内容无法解析，callback 会收到空对象 {}，SDK 保持本地初始化配置运行。

setForcedSession

setForcedSession() 用于强制当前会话进入采集状态。即使初始化时 sampleRate 或 sessionSampleRate 未命中采样，调用后后续 RUM 数据也会继续上报。初始化前调用时，首次创建的 Session 会被强制采样；通常建议在初始化后根据业务用户或远程配置结果调用。

上报数据会带上：

session_is_forced=true

注意：setForcedSession() 只影响调用后的采集行为，调用前已经丢弃或已经发送的数据不会重新采集。强制状态只属于当前 Session；当前 Session 过期后，新 Session 会重新按采样率计算。

该能力只控制 RUM 会话采样，不控制录屏开关。

VIP 用户强制采样示例

下面示例展示如何基于远程配置下发的 vip_id 判断当前用户是否需要强制采样。setUser() 只设置后续 RUM 数据的用户上下文，不会重新请求或改变已经缓存的远程配置。

const { datafluxRum } = require('@cloudcare/rum-miniapp')

datafluxRum.init({
  applicationId: 'appid_xxxxxxx',
  site: 'https://rum-openway.guance.com',
  clientToken: 'client_token_xxxxx',
  service: 'miniapp-demo',
  env: 'production',
  version: '1.0.0',
  sessionSampleRate: 10,
  remoteConfiguration: true,
  trackInteractions: true,
})

function applyVipRemoteControl(userId) {
  var cleanUserId = String(userId || '')
    .trim()
    .replace(/["“”'']/g, '')
    .replace(/\r?\n/g, '')
    .replace(/\u200B/g, '')

  if (!cleanUserId) {
    return
  }

  datafluxRum.setUser({
    id: cleanUserId,
  })

  datafluxRum.getRemoteConfiguration(function (remoteConfig) {
    var vipRaw = remoteConfig && remoteConfig.vip_id
    var vipList = []

    if (Array.isArray(vipRaw)) {
      vipList = vipRaw.map(String)
    } else if (typeof vipRaw === 'string') {
      var trimmed = vipRaw.trim()
      if (trimmed.indexOf('[') === 0) {
        try {
          vipList = JSON.parse(trimmed).map(String)
        } catch (e) {
          vipList = []
        }
      } else if (trimmed) {
        vipList = [trimmed]
      }
    }

    if (vipList.indexOf(cleanUserId) === -1) {
      return
    }

    datafluxRum.setForcedSession()
    datafluxRum.addRumGlobalContext('vip_force_collect', true)
  })
}

applyVipRemoteControl('user-1')

运行时行为与兼容性

• SDK 对 wx.request 和 wx.downloadFile 的代理不会改变业务调用的返回值。请求任务、Promise、数组或其他平台特有返回结构会保持原样，SDK 只包装业务原本传入的回调。
• 开启 trackInteractions 时，自动 Action 会在业务事件处理函数执行前建立，因此处理函数中同步发起的请求能够关联到当前 Action；SDK 不会替换业务处理函数的返回值。
• 首个 View 从页面实际触发 onLoad 或 onShow 时开始，不会使用 SDK 初始化时间提前计算页面耗时。

注意事项

1. datakitOrigin 所对应的 datakit 域名必须在小程序管理后台加上 request 白名单
2. 因为目前微信小程序请求资源 APIwx.request、wx.downloadFile返回数据中profile字段目前 ios 系统不支持返回，所以会导致收集的资源信息中和 timing 相关的数据收集不全。目前暂无解决方案，request, downloadFile ;API 支持情况
3. trackInteractions 用户行为采集开启后，因为微信小程序的限制，无法采集到控件的内容和结构数据，所以在小程序 SDK 里面我们采取的是声明式编程，通过在 wxml 文件里面设置 data-name 属性，可以给 交互元素 添加名称，方便后续统计是定位操作记录， 例如：

<button bindtap="bindSetData" data-name="setData">
  setData
</button>