小程序应用接入¶

通过引入 SDK，收集微信小程序应用的性能指标、错误日志和资源请求数据，并上报到观测云，以可视化方式分析应用性能。

创建小程序应用¶

1. 进入「用户访问监测 > 应用列表」，点击「新建应用」，应用类型选择「小程序」。
2. 在「定义应用」中填写应用名称、应用 ID，并创建应用。控制台会生成此应用的 Client Token。
3. 创建成功后，在「选择接入方式」中选择 Agent 自动接入或手动接入，再按照「接入配置」完成配置。已有小程序应用可进入其配置页面继续接入。

小程序应用应使用本页的小程序 SDK。即使与 Web 应用使用同一套业务代码，也需要按实际应用类型分别接入。

选择接入方式¶

Agent 自动接入¶

1. 在小程序应用配置页面选择「Agent 自动接入」。
2. 复制「接入配置」中的完整提示词，在小程序代码仓库中打开编程助手并粘贴。提示词应来自当前小程序应用，使用该应用的 ID。
3. 按 Agent 的接入指引完成配置，再按验证接入确认小程序数据上报和入库。

若页面提示个人 API Key 或临时授权码未就绪，请按提示生成个人 API Key、联系管理员开通权限或补齐信息后重新复制提示词。

手动接入¶

通常优先选择「使用公网 DataWay」，无需自行部署 DataKit。需要自行管理数据接收端，或当前工作空间未提供公网 DataWay 地址时，可选择「本地环境部署」。

NPM 和 CDN 是 SDK 的引入方式，与上报到公网 DataWay 或本地 DataKit 是两项独立选择。

使用公网 DataWay¶

1. 在「手动接入」下选择「使用公网 DataWay」。
2. 从当前应用的接入配置中复制 applicationId、site 和 clientToken。请使用控制台提供的当前站点地址，不要将控制台登录地址或其他站点的地址作为 site。
3. 将 site 对应域名加入微信小程序管理后台的 request 合法域名，再按集成 SDK完成代码配置。此方式无需安装 DataKit 或另行配置 RUM 采集器。

本地环境部署¶

1. 安装 DataKit，并启用 RUM 采集器。
2. 确保小程序所在网络可以访问 DataKit 的数据上报地址，并按需安装 IP 地理信息库，以解析用户 IP 对应的地理信息。
3. 在「手动接入」下选择「本地环境部署」，将 datakitOrigin 配置为实际的 DataKit 接收地址，并将对应域名加入小程序管理后台的 request 合法域名。
4. 按集成 SDK中的本地环境部署示例初始化，不要同时填写 site 和 clientToken。

集成 SDK¶

先选择一种 SDK 引入方式，再按照所选的数据上报方式初始化。SDK 需要在 app.js 中、App() 调用之前初始化，并且只初始化一次。

引入 SDK¶

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

const { datafluxRum } = require('./lib/dataflux-rum-miniapp.js')

初始化 SDK¶

以下两种配置只选一种。公网 DataWay 使用 site 和 clientToken，本地环境部署使用 datakitOrigin，不要在同一份初始化配置中同时填写两套上报参数。

datafluxRum.init({
  applicationId: '<APPLICATION_ID>',
  site: '<PUBLIC_DATAWAY_URL>',
  clientToken: '<CLIENT_TOKEN>',
  env: 'production',
  version: '1.0.0',
  service: 'miniapp',
  sampleRate: 100,
  trackInteractions: true,
  traceType: 'ddtrace',
  allowedTracingUrls: ['https://api.example.com/v1/'],
})

datafluxRum.init({
  applicationId: '<APPLICATION_ID>',
  datakitOrigin: '<DATAKIT_ORIGIN>',
  env: 'production',
  version: '1.0.0',
  service: 'miniapp',
  sampleRate: 100,
  trackInteractions: true,
  traceType: 'ddtrace',
  allowedTracingUrls: ['https://api.example.com/v1/'],
})

将占位符替换为当前应用的实际配置；allowedTracingUrls 只填写需要关联链路的业务 API 地址，不需要链路追踪时可移除。

验证接入¶

1. 检查所选上报地址对应的域名已经加入微信小程序的 request 合法域名。
2. 打开小程序，触发页面访问、按钮点击和业务请求，在开发者工具中确认存在成功的 RUM 上报请求，且没有域名校验或 SDK 初始化错误。
3. 进入「用户访问监测 > 应用列表」，打开对应小程序应用，确认查看器中有 View、Resource 或 Action 等数据。
4. 发布前使用真机验证网络连通和数据上报，避免仅依赖开发者工具中的调试配置。

如果没有数据，先确认 applicationId 与当前小程序应用一致，再检查所选上报方式的参数、request 合法域名和 sampleRate。

配置¶

初始化参数¶

Trace Header URL 匹配¶

allowedTracingUrls 使用完整请求 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' },
]

allowedTracingOrigins 仅用于兼容旧配置：字符串和正则都针对请求 Origin 匹配。若同时配置两个参数，SDK 只使用 allowedTracingUrls。

未采样 Session 的 Trace Header¶

allowTraceHeaderWithoutSession 默认为 false。设置为 true 后，即使当前 Session 未命中 RUM 采样，SDK 仍会为命中 allowedTracingUrls 的请求注入 Trace Header。该配置不会强制采样或创建新的 Session，也不会上报未采样 Session 的 View、Action、Resource、Error 等 RUM 数据。

注意¶

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

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