UniApp 미니 프로그램 JavaScript SDK 원격 구성¶

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

이 문서는 rum-uniapp JavaScript SDK에 적용되며, 다른 페이지에서 소개하는 GCUniPlugin-* 네이티브 모듈에는 적용되지 않습니다.

원격 구성 활성화¶

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