UniApp Mini Program JavaScript SDK Remote Configuration¶

This article introduces the remote configuration, forced sampling, and Session behavior of the UniApp Mini Program JavaScript SDK version 2.2.19 and later.

This article only applies to the rum-uniapp JavaScript SDK, not the GC-JSPlugin + GC-UniPlugin 0.3.0 and later Native RUM integration approach.

Enable Remote Configuration¶

Set remoteConfiguration: true during initialization. The SDK immediately starts with the local configuration, and the remote configuration request does not block first-screen collection. After the request returns, the supported configuration items are updated at runtime.

Older versions used the misspelling remoteConfigration. Version 2.2.19 still supports this parameter, but new projects should use 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,
  allowedTracingOrigins: ['https://api.example.com'],
  allowTraceHeaderWithoutSession: true,
  remoteConfiguration: true,
  remoteConfigurationFetchTimeout: 3000,
}

// Vue2
datafluxRum.init(Vue, rumConfig)

// Vue3 project instead use:
// datafluxRum.initVue3(rumConfig)

When enabled, the SDK requests the following URL:

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

When using a public DataWay, the request also carries the clientToken. You need to add the corresponding domain to the mini program platform's request allowlist.

Configuration Delivery Format¶

Remote configuration keys use the following format:

R.{applicationId}.{configuration name}

For example:

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

The SDK removes the R.{applicationId}. prefix. You can retrieve the configuration via getRemoteConfiguration():

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

The following items currently support remote updates:

sampleRate
sessionSampleRate
service
env
version
trackInteractions
traceType
traceId128Bit
allowedTracingOrigins
allowTraceHeaderWithoutSession

sessionSampleRate is applied as sampleRate. Custom fields such as vip_id do not automatically change SDK behavior; your business code must read and handle them.

Trace Headers for Unsamped Sessions¶

By default, the SDK only injects Trace Headers for requests matching allowedTracingOrigins when the current Session is sampled by RUM.

When allowTraceHeaderWithoutSession: true is set, the SDK injects Trace Headers for eligible requests even if the current Session is not sampled. This configuration does not force sampling, create a new Session, or report RUM data (View, Action, Resource, Error, etc.) for unsampled Sessions.

const rumConfig = {
  sessionSampleRate: 0,
  traceType: 'w3c_traceparent',
  allowedTracingOrigins: ['https://api.example.com'],
  allowTraceHeaderWithoutSession: true,
}

This configuration supports remote updates. The local configuration is used until the remote value is returned; after that, only subsequent requests are affected.

Get Remote Configuration¶

Call getRemoteConfiguration(callback) after init() or initVue3():

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

• If the request has not completed, the callback waits for the current request to finish.
• If the request has completed, the callback immediately receives the cached result, without making a new request.
• Each callback receives an independent copy; modifying the returned object does not change the SDK internal configuration.
• If remote configuration is not enabled, the request fails, times out, or the returned content cannot be parsed, the callback receives an empty object {}.

Force Collection of the Current Session¶

setForcedSession() is used to force collection of the current Session. Even if the local or remote sampling rate is not hit, the RUM data after the call is still reported, with the following attribute:

session_is_forced=true

The following example forces collection based on a VIP user list delivered remotely:

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() only affects data collected after the call; it does not retroactively send data that was already discarded. The forced state belongs only to the current Session. After the Session expires, the decision is recalculated based on the latest sampling rate.

Session and Runtime Behavior¶

• Sessions are stored independently per applicationId. Different RUM applications do not share Session IDs or sampling results.
• A new Session is created after 15 minutes of inactivity; the maximum duration of a single Session is 4 hours.
• Page entry, clicks, touches, inputs, and declared page scrolling extend the Session. Disabling trackInteractions only stops automatic Action collection; it does not affect Session activity detection.
• Data collected before the remote configuration is returned is processed according to the local configuration and is not retroactively recalculated.
• For a newly created Session that has not been force-sampled during this initialization, the sampling result can be recalculated after the remote sampling rate is returned. Sessions restored from storage retain the original sampling decision.
• When the SDK proxies uni.request and uni.downloadFile, the original return values and Promise behavior of the business calls are preserved.