Mini Program SDK Remote Configuration and Forced Sampling¶

Mini Program SDK 2.2.16 and above supports adjusting runtime configurations such as the sampling rate without republishing the Mini Program, and can also forcibly collect the current Session of a specified user based on business fields delivered remotely.

Enable Remote Configuration¶

Set remoteConfiguration: true during initialization. The SDK will start immediately with the local configuration, and the remote configuration request will not block the first screen collection.

Earlier versions used the spelling remoteConfigration, which is still compatible in 2.2.16, 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,
  remoteConfiguration: true,
  remoteConfigurationFetchTimeout: 3000,
})

After enabling, the SDK requests the following address:

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

When using a public DataWay, the request will also carry the clientToken. The corresponding domain must be added to the WeChat Mini Program's request whitelist.

Configuration Delivery Format¶

Remote configuration keys use the following format:

R.{applicationId}.{configurationName}

For example:

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

The SDK will remove the R.{applicationId}. prefix. The business code can retrieve it via getRemoteConfiguration():

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

Currently supported remote updates:

sampleRate
sessionSampleRate
service
env
version
trackInteractions
traceType
traceId128Bit
allowedTracingOrigins

sessionSampleRate will be applied as sampleRate. Custom fields like vip_id will not automatically change the SDK behavior; the business code needs to read and handle them itself.

Get Remote Configuration¶

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

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

• If the request is not completed, the callback will wait for the current request to finish.
• If the request has already completed, the callback will immediately receive the cached result without making another request.
• Each callback receives an independent copy; modifying the returned object will 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 will receive an empty object {}.

Forced Collection of Current Session¶

setForcedSession() is used to forcibly collect the current Session. Even if the local or remote sampling rate is not hit, the RUM data after the call will continue to be reported, with:

session_is_forced=true

The following example forcibly collects based on the VIP user list delivered remotely:

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

Session and Runtime Behavior¶

• Sessions are saved independently per applicationId; different RUM applications will not share Session IDs or sampling results.
• A new Session is created after 15 minutes of inactivity; the maximum duration for a single Session is 4 hours.
• Page entry, clicks, touches, inputs, and declared page scrolls will extend the Session. Disabling trackInteractions only stops automatic Action collection, but does not affect Session activity recognition.
• Data before the remote configuration is returned is processed according to the local configuration and will not be recalculated retroactively.
• For a newly created Session during this initialization that has not yet been forcibly sampled, 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 wx.request and wx.downloadFile, it preserves the original return values and Promise behavior of the business calls.