UniApp 미니 프로그램 JavaScript SDK 원격 설정¶

이 문서에서는 UniApp 미니 프로그램 JavaScript SDK 2.2.19 이상 버전의 원격 설정, 강제 샘플링 및 Session 동작에 대해 설명합니다.

이 문서는 rum-uniapp JavaScript SDK에만 적용되며, GC-JSPlugin + GC-UniPlugin의 0.3.0 이상 Native RUM 연동 방식에는 적용되지 않습니다.

원격 설정 활성화¶

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

// Vue2
datafluxRum.init(Vue, rumConfig)

// Vue3 프로젝트는 다음 대신 사용:
// datafluxRum.initVue3(rumConfig)

활성화 후 SDK는 다음 주소로 요청을 전송합니다:

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

공용 DataWay를 사용하는 경우 요청에 clientToken도 포함됩니다. 해당 도메인을 미니 프로그램 플랫폼의 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 동작을 자동으로 변경하지 않으며, 비즈니스 코드에서 읽어서 직접 처리해야 합니다.

샘플링되지 않은 Session의 Trace Header¶

기본적으로 현재 Session이 RUM 샘플링에 포함된 경우에만 SDK가 allowedTracingOrigins에 해당하는 요청에 Trace Header를 주입합니다.

allowTraceHeaderWithoutSession: true로 설정하면 현재 Session이 샘플링에 포함되지 않았더라도 SDK가 조건에 맞는 요청에 Trace Header를 계속 주입합니다. 이 설정은 강제 샘플링을 수행하거나 새 Session을 생성하지 않으며, 샘플링되지 않은 Session의 View, Action, Resource, Error 등의 RUM 데이터를 업로드하지 않습니다.

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

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

원격 설정 가져오기¶

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 동작을 유지합니다.