미니프로그램 SDK 원격 구성 및 강제 샘플링¶

미니프로그램 SDK 2.2.16 이상 버전은 미니프로그램을 다시 게시하지 않고 샘플링 속도 등의 런타임 구성을 조정하거나, 원격으로 전달된 비즈니스 필드를 기반으로 지정된 사용자의 현재 세션을 강제로 수집할 수 있습니다.

원격 구성 활성화¶

초기화 시 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,
  allowedTracingOrigins: ['https://api.example.com'],
  allowTraceHeaderWithoutSession: true,
  remoteConfiguration: true,
  remoteConfigurationFetchTimeout: 3000,
})

활성화 후, SDK는 다음 주소로 요청합니다.

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

공용 네트워크 DataWay를 사용하는 경우 요청에 clientToken도 포함됩니다. 해당 도메인을 WeChat 미니프로그램의 request 합법적 도메인 화이트리스트에 추가해야 합니다.

구성 전달 형식¶

원격 구성 키는 다음 형식을 사용합니다.

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
allowTraceHeaderWithoutSession

sessionSampleRate는 sampleRate에 따라 적용됩니다. vip_id와 같은 사용자 정의 필드는 SDK 동작을 자동으로 변경하지 않으며, 비즈니스 코드에서 읽은 후 직접 처리해야 합니다.

샘플링되지 않은 세션의 Trace 헤더¶

기본적으로 현재 세션이 RUM 샘플링에 적중한 경우에만 SDK는 allowedTracingOrigins에 적중한 요청에 Trace 헤더를 주입합니다.

allowTraceHeaderWithoutSession: true를 설정하면 현재 세션이 샘플링에 적중하지 않아도 SDK는 조건에 맞는 요청에 Trace 헤더를 주입합니다. 이 구성은 강제 샘플링이나 새 세션을 생성하지 않으며, 샘플링되지 않은 세션의 View, Action, Resource, Error 등의 RUM 데이터를 보고하지 않습니다.

이 구성은 원격 업데이트를 지원합니다. 원격 값이 반환되기 전에는 로컬 구성에 따라 처리되며, 반환 후에는 후속 요청에만 영향을 미칩니다.

원격 구성 가져오기¶

datafluxRum.init() 후에 getRemoteConfiguration(callback)을 호출합니다.

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

• 요청이 완료되지 않은 경우, 콜백은 이 요청이 완료될 때까지 기다립니다.
• 요청이 이미 완료된 경우, 콜백은 즉시 캐시된 결과를 받으며, 요청을 다시 시작하지 않습니다.
• 각 콜백은 독립적인 복사본을 받으며, 반환 객체를 수정해도 SDK 내부 구성이 변경되지 않습니다.
• 원격 구성이 활성화되지 않았거나, 요청 실패, 시간 초과 또는 반환 내용을 구문 분석할 수 없는 경우, 콜백은 빈 객체 {}를 받습니다.

현재 세션 강제 수집¶

setForcedSession()은 현재 세션을 강제로 수집하는 데 사용됩니다. 로컬 또는 원격 샘플링 속도가 적중하지 않아도 호출 후 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()은 호출 후의 데이터에만 영향을 미치며, 이전에 폐기된 데이터를 다시 보내지 않습니다. 강제 상태는 현재 세션에만 적용됩니다. 세션이 만료되면 최신 샘플링 속도에 따라 다시 계산됩니다.

세션 및 런타임 동작¶

• 세션은 applicationId별로 독립적으로 저장되며, 다른 RUM 애플리케이션은 세션 ID 또는 샘플링 결과를 재사용하지 않습니다.
• 15분 연속 활동이 없으면 새 세션이 생성됩니다. 단일 세션의 최대 길이는 4시간입니다.
• 페이지 진입, 클릭, 터치, 입력 및 선언된 페이지 스크롤은 세션을 갱신합니다. trackInteractions를 비활성화하면 자동 Action 수집만 중지되며, 세션 활동 식별에는 영향을 미치지 않습니다.
• 원격 구성 반환 전의 데이터는 로컬 구성에 따라 처리되며, 소급하여 재계산되지 않습니다.
• 이번 초기화에서 새로 생성되고 아직 강제 샘플링되지 않은 세션의 경우, 원격 샘플링 속도가 반환된 후 샘플링 결과를 다시 계산할 수 있습니다. 저장소에서 복원된 세션은 원래 샘플링 결정을 유지합니다.
• SDK가 wx.request 및 wx.downloadFile을 프록시할 때 비즈니스 호출의 원래 반환 값과 Promise 동작을 유지합니다.