小程序 SDK 远程配置与强制采样¶

小程序 SDK 2.2.16 及以上版本支持在不重新发布小程序的情况下调整采样率等运行时配置，也可以根据远程下发的业务字段强制采集指定用户的当前 Session。

开启远程配置¶

初始化时设置 remoteConfiguration: true。SDK 会立即按本地配置启动，远程配置请求不会阻塞首屏采集。

历史版本曾使用 remoteConfigration 拼写，2.2.16 仍然兼容该参数，但新项目应使用 remoteConfiguration。

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: 20,
  remoteConfiguration: true,
  remoteConfigurationFetchTimeout: 3000,
})

参数	类型	默认值	说明
`sessionSampleRate`	number	`100`	`sampleRate` 的兼容别名，范围为 `0` 到 `100`。两者同时设置时优先使用 `sampleRate`
`remoteConfiguration`	boolean	`false`	是否异步拉取并应用远程配置
`remoteConfigration`	boolean	`false`	旧拼写兼容项，不建议新项目使用
`remoteConfigurationFetchTimeout`	number	`3000`	远程配置请求超时时间，单位为毫秒；请求失败或超时后继续使用本地配置

开启后，SDK 请求以下地址：

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

使用公网 DataWay 时，请求还会携带 clientToken。需要将对应域名加入微信小程序的 request 合法域名白名单。

配置下发格式¶

远程配置 key 使用以下格式：

R.{applicationId}.{配置名}

例如：

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

SDK 会移除 R.{applicationId}. 前缀。业务通过 getRemoteConfiguration() 获取：

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

当前支持远程更新：

sampleRate
sessionSampleRate
service
env
version
trackInteractions
traceType
traceId128Bit
allowedTracingOrigins

sessionSampleRate 会按 sampleRate 应用。vip_id 等自定义字段不会自动改变 SDK 行为，需要业务代码读取后自行处理。

获取远程配置¶

在 datafluxRum.init() 后调用 getRemoteConfiguration(callback)：

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

请求未完成时，回调会等待本次请求完成。
请求已经完成时，回调会立即收到缓存结果，不会再次发起请求。
每个回调收到独立副本，修改返回对象不会改变 SDK 内部配置。
未开启远程配置、请求失败、超时或返回内容无法解析时，回调收到空对象 {}。

强制采集当前 Session¶

setForcedSession() 用于强制采集当前 Session。即使本地或远程采样率未命中，调用后的 RUM 数据仍会继续上报，并带有：

session_is_forced=true

下面示例根据远程下发的 VIP 用户列表强制采集：

var currentUserId = 'user-1'

datafluxRum.setUser({ id: currentUserId })
datafluxRum.getRemoteConfiguration(function (remoteConfig) {
  var vipIds = remoteConfig && remoteConfig.vip_id

  if (typeof vipIds === 'string') {
    try {
      vipIds = JSON.parse(vipIds)
    } catch (error) {
      vipIds = []
    }
  }

  if (Array.isArray(vipIds) && vipIds.map(String).indexOf(currentUserId) !== -1) {
    datafluxRum.setForcedSession()
    datafluxRum.addRumGlobalContext('vip_force_collect', true)
  }
})

setForcedSession() 只影响调用后的数据，不会补发此前已丢弃的数据。强制状态只属于当前 Session；Session 过期后会重新按最新采样率计算。

Session 与运行时行为¶

Session 按 applicationId 独立保存，不同 RUM 应用不会复用 Session ID 或采样结果。
连续 15 分钟没有活动会创建新 Session；单个 Session 最长为 4 小时。
页面进入、点击、触摸、输入和已声明的页面滚动会续期 Session。关闭 trackInteractions 只停止自动 Action 采集，不影响 Session 活动识别。
远程配置返回前的数据按本地配置处理，不会追溯重算。
对本次初始化新建且尚未强制采样的 Session，远程采样率返回后可以重新计算采样结果；从存储恢复的 Session 保留原采样决定。
SDK 代理 wx.request 和 wx.downloadFile 时会保持业务调用的原始返回值与 Promise 行为。