Web 애플리케이션 연동¶

이 페이지의 설정을 완료하면 Browser RUM SDK가 자동으로 페이지 View, 리소스 요청, 프론트엔드 오류 및 사용자 작업을 수집하고 데이터를 Guance에 전송합니다.

연동 경로 선택¶

먼저 애플리케이션 형태에 따라 진입점을 선택하여 View가 중복 구성되거나 서버 측 렌더링 단계에서 브라우저 API에 접근하는 것을 방지합니다.

연동 정보 준비¶

1. 「RUM > 애플리케이션 목록 > 애플리케이션 생성 > Web」으로 이동합니다.
2. 애플리케이션을 생성하고 콘솔에서 생성된 applicationId, env, version 등의 설정을 확인합니다.

3. 데이터 전송 방식을 선택합니다:

4. 공용 OpenWay: site 및 clientToken을 획득하며, DataKit 배포가 필요 없습니다.

5. DataKit 직접 연결: datakitOrigin을 준비합니다. DataKit에서 RUM 수집기를 활성화하고 공용 네트워크에서 접근 가능하며 IP 지리 정보 데이터베이스를 설치하도록 구성해야 합니다.

전송 방식¶

{
  applicationId: "<APPLICATION_ID>",
  datakitOrigin: "<DATAKIT_ORIGIN>"
}

{
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>"
}

SDK 통합¶

NPM 연동¶

프론트엔드 프로젝트에 SDK를 설치하고 가져옵니다:

npm install @cloudcare/browser-rum @cloudcare/browser-core

프로젝트에서 SDK를 초기화합니다:

import { datafluxRum } from "@cloudcare/browser-rum"

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  service: "web-app",
  env: "production",
  version: "1.0.0",
  sessionSampleRate: 100,
  trackUserInteractions: true
})

CDN 동기 로드¶

HTML 파일에 스크립트를 추가합니다:

<script
  src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
  type="text/javascript"
></script>
<script>
  window.DATAFLUX_RUM &&
    window.DATAFLUX_RUM.init({
      applicationId: "<APPLICATION_ID>",
      site: "<PUBLIC_OPENWAY_URL>",
      clientToken: "<CLIENT_TOKEN>",
      service: "web-app",
      env: "production",
      version: "1.0.0",
      sessionSampleRate: 100,
      trackUserInteractions: true
    })
</script>

CDN 비동기 로드¶

HTML 파일에 스크립트를 추가합니다:

<script>
  ;(function (h, o, u, n, d) {
    h = h[d] = h[d] || {
      q: [],
      onReady: function (c) {
        h.q.push(c)
      },
    }
    d = o.createElement(u)
    d.async = 1
    d.src = n
    n = o.getElementsByTagName(u)[0]
    n.parentNode.insertBefore(d, n)
  })(
    window,
    document,
    "script",
    "https://static.guance.com/browser-sdk/v3/dataflux-rum.js",
    "DATAFLUX_RUM"
  )
  DATAFLUX_RUM.onReady(function () {
    DATAFLUX_RUM.init({
      applicationId: "<APPLICATION_ID>",
      site: "<PUBLIC_OPENWAY_URL>",
      clientToken: "<CLIENT_TOKEN>",
      service: "web-app",
      env: "production",
      version: "1.0.0",
      sessionSampleRate: 100,
      trackUserInteractions: true
    })
  })
</script>

위 예시는 공용 OpenWay를 사용합니다. DataKit 직접 연결을 사용하는 경우 site 및 clientToken을 제거하고 datakitOrigin을 대신 구성하십시오.

연동 확인¶

1. SDK가 연동된 페이지를 열고 페이지 이동, 버튼 클릭 및 API 요청을 한 번 수행합니다.
2. 브라우저 개발자 도구의 Network 탭에서 /v1/write/rum을 필터링하여 성공적인 전송 요청이 있는지 확인합니다.
3. Console에서 Application ID is not configured, datakitOrigin or site is not configured와 같은 초기화 오류가 없는지 확인합니다.
4. 「RUM > 애플리케이션 목록」으로 이동하여 해당 Web 애플리케이션을 열고 탐색기에서 service, env, version별로 필터링하여 View, Resource 또는 Action 데이터가 있는지 확인합니다.

일반적인 선택적 구성¶

기본 데이터가 성공적으로 확인된 후 필요에 따라 다른 기능을 활성화합니다:

분산 추적 설정 (선택 사항)¶

NPM + TypeScript 연동 시 traceType은 해당 브랜드의 browser-core 패키지에서 가져온 TraceType 열거형을 사용해야 합니다:

import { TraceType } from "@cloudcare/browser-core"
import { datafluxRum } from "@cloudcare/browser-rum"

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  allowedTracingUrls: ["https://api.example.com"],
  traceType: TraceType.DDTRACE
})

TraceType.DDTRACE의 런타임 값은 여전히 "ddtrace"입니다. CDN 연동에는 모듈 가져오기가 없으므로 명시적 구성 시 해당 런타임 문자열을 사용합니다. 분산 추적을 활성화한 후에는 API 서버에서 해당 Trace Header를 허용해야 합니다. 자세한 내용은 APM과 RUM 연결 방법을 참조하십시오.

일반 Session이 샘플링에 해당되지 않지만 Trace Header를 백엔드로 전송해야 하는 경우 allowTraceHeaderWithoutSession을 명시적으로 활성화할 수 있습니다:

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  sessionSampleRate: 0,
  sessionOnErrorSampleRate: 0,
  allowedTracingUrls: ["https://api.example.com"],
  allowTraceHeaderWithoutSession: true
})

이 설정을 활성화하면 SDK는 여전히 allowedTracingUrls에 해당하는 XHR 및 Fetch 요청에만 Trace Header를 주입합니다. 이 구성은 RUM Session을 생성하거나 강제로 활성화하지 않으며, 샘플링되지 않은 Session의 View, Error, Resource 또는 Action 데이터를 전송하지 않습니다. API 서비스는 선택한 traceType에 해당하는 요청 헤더를 허용해야 합니다. 또한 교차 출처 요청은 CORS가 올바르게 구성되어야 합니다.

매개변수 설정¶

초기화 매개변수¶

low, medium, high 문자열 사전 설정을 사용하지 않을 때 Canvas 자동 스케줄링 기준은 다음과 같습니다: sampling 2, 각 Canvas의 목표 interval 250 ms, cooldown 250 ms, unchanged backoff 3000 ms, failure backoff 5000 ms, 라운드당 최대 2개 Canvas. 문자열 사전 설정은 이러한 예산과 인코딩 품질을 동시에 대체합니다. 여러 Canvas는 공정한 순환 및 전역 수집 예산의 제한도 받습니다. 명시적인 개별 구성은 사전 설정의 해당 값을 재정의합니다. 전체 preset 매트릭스는 Canvas 녹화 사용 설명서를 참조하십시오.

위의 고빈도 스케줄링 기준은 Canvas 2D용입니다. WebGL 플러그인이 명시적으로 interval/cooldown을 구성하지 않은 경우 더 보수적인 GPU 읽기백 속도를 계속 사용합니다. 명시적인 개별 구성이 있어야 각각 재정의됩니다.

site 매개변수 처리¶

런타임 Session 제어¶

RUM SDK 3.3.6에 startSession()이 추가되었습니다. 호출하면 즉시 현재 Session을 종료하고 현재 샘플링 구성에 따라 Session을 다시 시작합니다. 다음 사용자 상호 작용을 기다릴 필요가 없습니다:

datafluxRum.startSession()

또한 런타임 sessionSampleRate를 동시에 재정의할 수 있습니다:

datafluxRum.startSession({
  sessionSampleRate: 100,
})

샘플링 비율은 0에서 100 사이여야 합니다. 이 재정의 값은 이번 및 이후 자동으로 재개되는 Session에 사용됩니다. 전체 RUM 패키지와 경량 RUM 패키지 모두 이 API를 지원합니다. 자세한 의미와 사용 사례는 런타임 Session 다시 시작을 참조하십시오.

필요에 따라 고급 기능 활성화¶

오류 세션 이벤트만 수집¶

페이지에서 오류가 트리거되면 SDK가 자동으로 다음을 실행합니다:

• 지속적 기록: 오류 트리거 시점부터 세션 전체 수명 주기 데이터를 완전히 기록합니다.
• 정밀 보상: 독립적인 샘플링 채널을 통해 오류 시나리오가 누락되지 않도록 보장합니다.

구성 방법¶

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    applicationId: "<APPLICATION_ID>",
    site: "<PUBLIC_OPENWAY_URL>",
    clientToken: "<CLIENT_TOKEN>",
    sessionSampleRate: 0,
    sessionOnErrorSampleRate: 100
  })

위 예시는 공용 OpenWay를 사용합니다. DataKit 직접 연결 시 기본 연동 예시에 따라 전송 주소 필드를 교체하십시오.

데이터 압축¶

많은 정적 리소스(예: JS, CSS, 이미지 등)를 수집하고 전체 수집을 활성화한 경우, SDK는 초기화 후 많은 데이터를 생성하여 요청이 누적되고 애플리케이션 스레드 상태에 영향을 줄 수 있습니다.

compressIntakeRequests: true를 설정하면 SDK는 Web Worker에서 deflate를 사용하여 전송 데이터를 압축하여 요청 크기와 요청 수를 줄입니다.

구성 예시¶

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    applicationId: "<APPLICATION_ID>",
    site: "<PUBLIC_OPENWAY_URL>",
    clientToken: "<CLIENT_TOKEN>",
    compressIntakeRequests: true
  })

주의 사항¶

1. 데이터 압축 로직은 Web Worker에서 실행됩니다. CSP 보안 정책이 활성화된 경우 worker-src에서 blob:을 허용해야 합니다. 자세한 내용은 CSP 보안 정책 설명을 참조하십시오.
2. SDK는 workerUrl 구성 항목을 통해 자체 호스팅 Worker 주소를 지정할 수 있습니다.
3. 이 기능을 사용하려면 SDK 버전이 >= 3.2여야 합니다.

사용자 정의 데이터 및 이벤트¶

기본 연동 페이지에서는 모든 공용 API를 다시 펼쳐서 설명하지 않습니다. 비즈니스 목표에 따라 해당 페이지로 이동하면 CDN, NPM 및 전체 매개변수 예시를 확인할 수 있습니다:

• 사용자 작업 추적: 클릭 자동 수집, Action 이름 정의, 사용자 정의 Action 추가
• 사용자 정의 사용자 식별자: 로그인 후 사용자 설정, 로그아웃 또는 계정 전환 시 사용자 정리
• 전역 컨텍스트: 모든 후속 RUM 이벤트에 안정적인 비즈니스 차원을 추가합니다.
• 사용자 정의 Action 추가: 페이지 클릭으로 표현할 수 없는 비즈니스 작업을 기록합니다.
• 사용자 정의 Error 전송: 이미 캡처되었거나 비즈니스에서 직접 식별한 예외를 전송합니다.

Web 세션 리플레이¶

녹화 시작¶

SDK 초기화 후 startSessionReplayRecording() 메서드를 호출하여 세션 리플레이 녹화를 시작합니다. 사용자 로그인 후와 같은 특정 조건에서 시작하도록 선택할 수 있습니다. 세션 녹화 시작하기

오류 관련 세션 리플레이 데이터만 수집¶

페이지에서 오류가 발생하면 SDK가 자동으로 다음 작업을 수행합니다:

• 역추적 수집: 오류 발생 1분 전의 전체 페이지 스냅샷을 기록합니다.
• 지속적 녹화: 오류 발생 시점부터 세션이 종료될 때까지 지속적으로 기록합니다.
• 지능적 보상: 독립적인 샘플링 채널을 통해 오류 시나리오가 누락되지 않도록 보장합니다.

구성 예시¶

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    applicationId: "<APPLICATION_ID>",
    site: "<PUBLIC_OPENWAY_URL>",
    clientToken: "<CLIENT_TOKEN>",
    sessionSampleRate: 100,
    sessionReplaySampleRate: 0,
    sessionReplayOnErrorSampleRate: 100
  })

window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()

주의 사항¶

• 세션 리플레이는 iframe, 비디오 및 오디오 재생 콘텐츠를 기록하지 않습니다. Canvas는 기본적으로 수집되지 않으며 별도로 replayCanvasEnabled를 구성해야 합니다. WebGL/WebGL2는 SDK 3.3.7부터 제공되며 RUM 메인 패키지 버전 >= 3.3.7이 필요하고 호환되는 browser-rum-webgl 플러그인을 추가로 설치 및 등록해야 합니다. 플러그인과 메인 패키지는 동일한 SDK 릴리스 버전을 사용하는 것이 좋습니다. 자세한 내용은 Canvas 녹화 사용 설명서를 참조하십시오.
• 리플레이 시 정적 리소스(예: 글꼴, 이미지)에 정상적으로 액세스하려면 CORS 정책을 구성해야 할 수 있습니다.
• CSSStyleSheet 인터페이스를 통해 CSS 규칙에 액세스할 수 있는지 확인하여 CSS 스타일 및 마우스 호버 이벤트를 지원하십시오.

녹화 상태 확인¶

window.DATAFLUX_RUM.isRecording()을 호출하여 현재 페이지가 녹화 중인지 확인하고 세션 리플레이 탐색기에서 해당 Session이 리플레이 데이터를 생성했는지 확인합니다. 프로덕션 환경에서는 비즈니스 요구 사항에 따라 sessionReplaySampleRate를 조정하십시오.