콘텐츠로 이동

Electron 앱 연동 안내

Electron 앱 연동으로 돌아가기

Native SDK 통합 시 Native Bridge를 사용하세요

이 페이지는 Browser RUM이 Session을 독립적으로 관리하고 직접 업로드하는 연동 방식을 설명합니다. Windows 또는 macOS Native SDK가 Session, 샘플링, 컨텍스트, 영속화, 업로드를 관리해야 하는 경우 먼저 Electron 연동 방식 선택을 읽고, 앱 본체가 Electron이면 managed 빠른 시작을 사용하세요. Native Bridge 모드에서는 이 페이지의 실제 applicationId, clientToken, site, sessionPersistence 설정을 그대로 사용할 수 없습니다.

Electron 앱은 main process와 renderer process로 구성됩니다. RUM SDK는 브라우저 환경에서 실행되므로 renderer process에서만 초기화해야 하며, 창 내 페이지의 방문, 리소스, 요청, 오류, 사용자 행동 데이터를 수집합니다.

이 문서에서는 현재 SDK의 초기화 파라미터를 바탕으로 Electron 앱의 연동 방식을 설명합니다.

연동 원칙

  • renderer process에서만 RUM SDK를 초기화하고, main process에서는 초기화하지 마세요.
  • 모니터링이 필요한 각 BrowserWindow, BrowserView, webview에 해당하는 renderer 페이지마다 연동해야 합니다.
  • 페이지가 file://로 로드되는 경우 sessionPersistence: 'local-storage'를 반드시 사용하여 사용 불가능하거나 불안정한 cookie에 의존하지 않도록 하세요.
  • 페이지가 https://로 로드되는 경우 기본 cookie 세션 정책을 계속 사용할 수 있고, local-storage를 통일해서 사용해도 됩니다. 다만 RUM과 Logs SDK의 세션 정책을 일치시켜야 합니다.
  • 동일한 Electron 앱이 로컬 file:// 페이지와 원격 http(s):// 페이지를 함께 사용하면 브라우저 동일 출처 정책에 의해 분리되어 일반적으로 서로 다른 session이 생성됩니다.

권장 연동 방식

NPM 연동

Webpack, Vite, Rollup 등으로 renderer 코드를 빌드하는 Electron 앱에 적합합니다.

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

renderer 진입 파일에서 초기화합니다:

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

datafluxRum.init({
  applicationId: '<앱 ID>',

  // Public DataWay 연동
  clientToken: '<clientToken>',
  site: '<Public DataWay 주소>',

  // DataKit을 사용하는 경우 datakitOrigin으로 변경
  // datakitOrigin: '<DataKit 도메인 또는 IP>',

  service: 'electron-renderer',
  env: 'production',
  version: '<앱 버전>',
  sessionSampleRate: 100,
  trackUserInteractions: true,

  // file:// 페이지에서는 필수
  sessionPersistence: 'local-storage'
})

세션 리플레이가 필요하면:

datafluxRum.startSessionReplayRecording()

CDN 연동

renderer HTML을 직접 관리하는 앱에 적합합니다. 데스크톱 앱의 오프라인 또는 약한 네트워크 환경에서 원격 CDN에 의존하지 않도록 SDK 파일을 앱 정적 리소스와 함께 패키징하는 것을 권장합니다.

<script src="./vendor/dataflux-rum.js" type="text/javascript"></script>
<script>
  window.DATAFLUX_RUM &&
    window.DATAFLUX_RUM.init({
      applicationId: '<앱 ID>',
      clientToken: '<clientToken>',
      site: '<Public DataWay 주소>',
      service: 'electron-renderer',
      env: 'production',
      version: window.__APP_VERSION__,
      sessionSampleRate: 100,
      trackUserInteractions: true,
      sessionPersistence: 'local-storage'
    })
</script>

renderer 페이지가 항상 https://로 로드되고 cookie를 사용할 수 있다면 sessionPersistence를 설정하지 않아도 됩니다.

main process 예시

main process는 창을 생성하며 RUM SDK를 가져오거나 초기화할 필요가 없습니다. 필요한 버전, 채널 등의 정보만 renderer로 전달하는 것을 권장합니다.

const { app, BrowserWindow } = require('electron')
const path = require('path')

function createWindow() {
  const win = new BrowserWindow({
    width: 1200,
    height: 800,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true,
      nodeIntegration: false
    }
  })

  win.loadFile('index.html')
}

app.whenReady().then(createWindow)

preload.js에서는 안전하고 읽기 전용인 앱 정보만 노출하면 됩니다:

const { contextBridge } = require('electron')
const { version } = require('./package.json')

contextBridge.exposeInMainWorld('electronAppInfo', {
  version
})

renderer에서는 이 값을 읽어 RUM 설정에 반영합니다:

datafluxRum.init({
  applicationId: '<앱 ID>',
  clientToken: '<clientToken>',
  site: '<Public DataWay 주소>',
  service: 'desktop-app',
  env: 'production',
  version: window.electronAppInfo.version,
  sessionSampleRate: 100,
  trackUserInteractions: true,
  sessionPersistence: 'local-storage'
})

다중 창 연동

앱이 동시에 여러 창을 여는 경우:

  • 각 창의 renderer 페이지에서 RUM SDK를 초기화해야 합니다.
  • sessionPersistence: 'local-storage'를 사용하면 여러 창 사이의 localStorage 동기화에 아주 짧은 지연이 발생할 수 있습니다.
  • 초기화 직후 많은 창을 동시에 만들면 아주 짧은 임시 session이 발생할 수 있습니다. 창 생성과 초기화 사이에 수십 밀리초 이상 간격을 두거나, 업무 순서에 따라 창을 하나씩 생성하는 것을 권장합니다.

로컬 페이지와 원격 페이지

Electron 앱에서 흔히 볼 수 있는 두 가지 페이지 소스:

페이지 소스 권장 설정 설명
file:// 로컬 페이지 sessionPersistence: 'local-storage' cookie가 신뢰할 수 없으므로 localStorage로 session을 저장해야 합니다.
https:// 원격 페이지 기본 cookie 또는 local-storage 기본 cookie를 사용하는 경우 페이지 도메인과 보안 정책에서 cookie 쓰기를 허용하는지 확인해야 합니다.
file://와 https:// 혼합 각각 연동하고 각각 분석 동일 출처 정책의 영향으로 로컬 페이지와 원격 페이지는 일반적으로 session을 공유하지 않습니다.

앱이 로컬 랜딩 페이지에서 원격 사이트로 이동하면 RUM에서 두 개의 서로 다른 세션으로 표시될 것으로 예상해야 합니다. 통일된 user.id, service, env, version 필드를 사용해 연관 분석하는 것을 권장합니다.

datafluxRum.setUser({
  id: currentUserId,
  name: currentUserName
})

API 요청 및 분산 추적

renderer의 fetch와 XMLHttpRequest는 브라우저 SDK 로직에 따라 자동으로 수집됩니다. 백엔드 API에 Trace Header를 주입해야 한다면 allowedTracingUrls를 설정해야 합니다:

NPM + TypeScript 연동 시 traceType에는 browser-core 패키지에서 가져온 TraceType 열거형을 사용합니다:

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

datafluxRum.init({
  applicationId: '<앱 ID>',
  clientToken: '<clientToken>',
  site: '<Public DataWay 주소>',
  service: 'desktop-app',
  env: 'production',
  version: window.electronAppInfo.version,
  sessionPersistence: 'local-storage',
  allowedTracingUrls: [
    'https://api.example.com',
    /https:\/\/.*\.internal-api\.example\.com/
  ],
  traceType: TraceType.DDTRACE
})

CDN 연동에는 모듈 import가 없으므로 이 타입을 명시적으로 지정할 때 런타임 값 'ddtrace'를 사용하며, 설정하지 않아도 기본적으로 이 값을 사용합니다.

file:// 페이지 주소를 allowedTracingUrls에 넣지 마세요. 이 설정은 renderer 페이지 자체가 아니라 백엔드 API 요청을 매칭하는 데 사용됩니다.

오류 및 SourceMap

Electron 로컬 페이지의 오류 스택은 종종 file://로 시작하며, 서버는 공개 URL처럼 SourceMap을 직접 매칭하지 못할 수 있습니다. 권장 사항:

  • service, env, version과 빌드 산출물 버전을 일치시키세요.
  • renderer 산출물에 대한 SourceMap을 생성하고 배포 버전별로 저장하세요.
  • 로컬 파일 경로를 변경해야 하는 경우 beforeSend에서 비즈니스 컨텍스트를 추가하여 이후 검색이 용이하도록 하세요.
datafluxRum.init({
  // ...
  beforeSend: (event) => {
    if (event.type === 'error') {
      event.context = {
        ...event.context,
        electron: true,
        rendererUrl: window.location.href
      }
    }
    return true
  }
})

CSP 및 Worker

세션 리플레이, compressIntakeRequests, canvas 녹화를 활성화하면 SDK가 Worker를 사용할 수 있습니다. Electron 앱에서 비교적 엄격한 CSP를 설정한 경우 해당 Worker 소스를 허용해야 합니다.

기본 인라인 Worker에는 일반적으로 다음이 필요합니다:

worker-src blob:;

blob:을 허용하지 않으면 worker 파일을 앱 정적 리소스로 패키징하고 동일 출처 주소를 구성하세요:

datafluxRum.init({
  // ...
  workerUrl: './worker.js',
  replayCanvasWorkerUrl: './canvas-worker.js'
})

@cloudcare/browser-rum-slim을 사용하는 경우, 이 패키지에는 세션 리플레이와 compressIntakeRequests 압축 기능이 포함되어 있지 않으므로 이 두 기능을 위해 worker를 구성할 필요가 없습니다.

보안 권장 사항

  • main process에서 RUM token 또는 기타 민감한 설정을 노출하거나 쓰기 인터페이스를 제공하지 마세요.
  • preload에서는 앱 버전, 채널, 빌드 번호 등 필요한 읽기 전용 정보만 노출하세요.
  • contextIsolation: true와 nodeIntegration: false를 유지하세요.
  • beforeSend에서 로컬 파일의 절대 경로, 사용자 이름 디렉터리, 기타 민감한 정보를 전송하지 마세요.
  • 사용자 입력, 파일 이름, 경로 등의 필드는 마스킹한 후 사용자 정의 컨텍스트에 작성하세요.

검증 방법

연동 후 다음 순서로 검증할 수 있습니다:

  1. Electron 앱의 대상 창을 엽니다.
  2. DevTools Network에서 RUM 전송 요청이 있는지 확인합니다.
  3. 페이지 방문, 버튼 클릭, API 요청, 프런트엔드 오류를 각각 한 번씩 트리거합니다.
  4. view, action, resource, error 데이터가 Guance에 유입되는지 확인합니다.
  5. 동일 사용자가 여러 창 또는 로컬/원격 페이지를 전환할 때 session이 예상대로 유지되는지 확인합니다.

로컬 디버깅 시 beforeSend에서 이벤트 타입을 출력하도록 임시로 활성화할 수도 있습니다:

datafluxRum.init({
  // ...
  beforeSend: (event) => {
    console.log('[RUM]', event.type, event)
    return true
  }
})

자주 묻는 질문

main process에 데이터가 없는 이유는 무엇인가요?

RUM SDK는 브라우저용 SDK로 renderer process의 페이지 동작만 수집합니다. main process의 크래시, IPC, 파일 시스템, 네이티브 모듈 오류는 앱 자체의 로그 또는 크래시 수집 방안으로 처리해야 합니다.

file:// 페이지에 session이 없는 이유는 무엇인가요?

일반적으로 sessionPersistence: 'local-storage'를 설정하지 않았거나 renderer 페이지가 실행되는 환경에서 localStorage가 비활성화되어 있기 때문입니다. 먼저 해당 설정과 localStorage 사용 가능 여부를 확인하세요.

로컬 페이지에서 원격 페이지로 이동하면 session이 변경되는 이유는 무엇인가요?

file://와 https://는 서로 다른 origin이므로 브라우저는 cookie나 localStorage를 공유하지 않습니다. setUser()로 안정적인 사용자 ID를 설정하고 분석 시 사용자 기준으로 연관 지을 것을 권장합니다.

여러 창에서 아주 짧은 session이 나타나는 이유는 무엇인가요?

여러 창을 동시에 초기화하면 localStorage가 창 사이에서 동기화되는 데 아주 짧은 지연이 발생할 수 있습니다. 동시에 많은 창을 만들고 초기화하지 말고, 창 생성 사이에 짧은 간격을 두는 것을 권장합니다.

참고 자료

문서 평가

이 페이지가 도움이 되었나요?