UniApp 小程序 JavaScript SDK 远程配置¶

本文介绍 UniApp 小程序 JavaScript SDK 2.2.19 及以上版本的远程配置、强制采样与 Session 行为。

本文适用于 rum-uniapp JavaScript SDK，不适用于其他页面介绍的 GCUniPlugin-* 原生模块。

开启远程配置¶

初始化时设置 remoteConfiguration: true。SDK 会立即按本地配置启动，远程配置请求不会阻塞首屏采集；请求返回后，支持的配置项会在运行时更新。

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

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

const rumConfig = {
  applicationId: 'appid_xxxxxxx',
  site: 'https://rum-openway.guance.com',
  clientToken: 'client_token_xxxxx',
  service: 'uniapp-demo',
  env: 'production',
  version: '1.0.0',
  sessionSampleRate: 20,
  remoteConfiguration: true,
  remoteConfigurationFetchTimeout: 3000,
}

// Vue2
datafluxRum.init(Vue, rumConfig)

// Vue3 项目改用：
// datafluxRum.initVue3(rumConfig)

参数	类型	默认值	说明
`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 行为，需要业务代码读取后自行处理。

获取远程配置¶

在 init() 或 initVue3() 后调用 getRemoteConfiguration(callback)：

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

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

强制采集当前 Session¶

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

session_is_forced=true

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

const currentUserId = 'user-1'

datafluxRum.setUser({ id: currentUserId })
datafluxRum.getRemoteConfiguration(function (remoteConfig) {
  let 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 代理 uni.request 和 uni.downloadFile 时会保持业务调用的原始返回值与 Promise 行为。