Mini Program SDK Remote Configuration and Forced Sampling¶

Mini Program SDK 2.2.16 and later supports adjusting runtime configurations such as the sampling rate without republishing the mini program. It can also force the collection of the current Session of a specified user based on remotely delivered business fields.

Enabling Remote Configuration¶

Set remoteConfiguration: true during initialization. The SDK starts immediately with the local configuration; the remote configuration request does not block the initial view collection.

Previous versions used the spelling remoteConfigration. Version 2.2.16 still supports this parameter, but new projects should use 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,
  allowedTracingUrls: ['https://api.example.com/v1/'],
  allowTraceHeaderWithoutSession: true,
  remoteConfiguration: true,
  remoteConfigurationFetchTimeout: 3000,
})

When enabled, the SDK requests the following URL:

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

When using the public DataWay, the request also carries clientToken. The corresponding domain must be added to the request whitelist of the WeChat Mini Program.

Configuration Delivery Format¶

Remote configuration keys use the following format:

R.{applicationId}.{配置名}

For example:

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

The SDK removes the R.{applicationId}. prefix. The business code retrieves the configuration via getRemoteConfiguration():

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

The following fields support remote updates:

sampleRate
sessionSampleRate
service
env
version
trackInteractions
traceType
traceId128Bit
allowedTracingUrls
allowedTracingOrigins
allowTraceHeaderWithoutSession

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

Remote configuration uses JSON, so allowedTracingUrls can only accept strings or objects of the form { "match": "https://api.example.com/v1/", "traceType": "w3c_traceparent" }; regex and functions can only be written in the local initialization configuration.

allowedTracingUrls requires @cloudcare/rum-miniapp 2.2.19 or later. Older versions should continue to use allowedTracingOrigins.

Trace Header for Unsampled Sessions¶

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

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

This configuration supports remote updates. Before the remote value is returned, the local configuration is used; after it is returned, it only affects subsequent requests.

Retrieving Remote Configuration¶

Call getRemoteConfiguration(callback) after datafluxRum.init():

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

• If the request is not yet complete, the callback will wait for the request to finish.
• If the request has already 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 affect the SDK's internal configuration.
• When remote configuration is not enabled, the request fails, times out, or the returned content cannot be parsed, the callback receives an empty object {}.

Forcing the Current Session¶

setForcedSession() is used to force the collection of the current Session. Even if the local or remote sampling rate is not hit, RUM data after the call will continue to be reported and will include:

session_is_forced=true

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

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() only affects data after the call; it does not retroactively send data that was previously discarded. The forced state only applies to the current Session; when the Session expires, it will be recalculated based on the latest sampling rate.

Session and Runtime Behavior¶

• Sessions are saved independently by 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 scrolls renew the Session. Disabling trackInteractions only stops automatic Action collection; it does not affect Session activity detection.
• Data before the remote configuration is returned is processed according to the local configuration and is not retroactively recalculated.
• For a Session newly created during this initialization and not yet forcibly sampled, the sampling result can be recalculated after the remote sampling rate is returned; Sessions restored from storage retain their original sampling decision.
• When the SDK proxies wx.request and wx.downloadFile, it preserves the original return values and Promise behavior of the business calls.