Electron 구성 및 수명 주기¶

이 문서는 Windows 및 macOS Native Bridge 공통 구성 설명입니다. 최초 연동은 managed 빠른 시작을 사용하며, 모드 선택은 애플리케이션 연동을 참조하세요. 플랫폼 호스트 초기화, 런타임 설치 및 패키징은 각각 Windows 및 macOS를 참조하세요.

Main 구성¶

managed는 bootstrap()의 native.settings에서 애플리케이션 및 업로드 파라미터를 구성합니다. external은 네이티브 호스트가 Native SDK를 구성하며 native.settings를 전달하지 않습니다.

Windows는 0.1과 같은 소수 정밀도를 유지할 수 있습니다. 기본 제공되는 macOS Native Runtime은 정수 백분율을 사용하므로, 활성화된 수집 기능에 새 필드로 소수를 전달하면 Adapter는 반올림하지 않고 오류를 보고합니다. 사용자 지정 macOS Runtime의 소수 샘플링 지원 여부는 실제 기능에 따라 달라지며, 일반 샘플링과 Replay는 각각 확인합니다. 이전 샘플링 필드는 Adapter 0.1.0-alpha.4부터 사용이 중단되었으며, 기존 단위 및 기존 macOS 반올림 동작과 여전히 호환됩니다. 동일한 구성에서 새 필드와 이전 필드를 동시에 설정하면 명시적으로 0을 설정한 경우를 포함하여 새 필드가 우선합니다.

macOS에서 실제로 업로드되는 애플리케이션 버전은 애플리케이션 패키징 정보에 따라 결정됩니다. traceEnabled는 Native Trace만 구성하며 Renderer 요청에 Trace 헤더를 자동으로 주입하지 않습니다.

사용자 바인딩 및 전역 속성은 Native SDK 기능을 통해 통합 관리됩니다. Windows 사용자 정의 태그 및 Apple SDK 사용자 정의 태그를 참조하세요. Adapter Client는 Browser setUser()에 대응하는 공개 사용자 바인딩 인터페이스를 제공하지 않습니다. Adapter 내부 모듈을 참조하여 Native 상태를 수정하지 마세요.

Preload¶

npm 패키지의 공개 진입점만 사용하세요. Main은 @cloudcare/electron-native-adapter를 사용하고, 비즈니스 Preload가 없는 경우 빠른 시작의 preload/standalone을 사용합니다. 기존 Preload가 있으면 설치 함수를 한 번 호출합니다:

const {
  installElectronRumPreload,
} = require("@cloudcare/electron-native-adapter/preload/install");

installElectronRumPreload();

contextIsolation: true, nodeIntegration: false, sandbox: true를 유지하세요. 샌드박스 Preload는 일반 Node.js require()로 npm 패키지를 직접 로드할 수 없습니다. 애플리케이션의 번들러로 위 코드와 해당 의존성을 번들링하고 electron은 외부 의존성으로 유지해야 합니다. 예를 들어 esbuild가 설치된 프로젝트에서는 다음을 실행할 수 있습니다:

npx esbuild src/preload.cjs --bundle --platform=node --format=cjs --external:electron --outfile=dist/preload.cjs

webPreferences.preload가 산출물의 절대 경로를 가리키도록 설정하세요. 독립형 Preload는 샌드박스에서 바로 사용할 수 있으므로 브리지를 다시 설치할 필요가 없습니다. Adapter 소스 코드를 복사하거나 공개되지 않은 internal/, core/, platform/ 파일을 직접 참조하지 마세요.

창 관리¶

수집이 필요한 모든 창은 Preload를 로드하고 페이지를 로드하기 전에 등록해야 합니다. autoAttach의 기본값은 false입니다. true로 설정하면 기존 창과 이후 생성된 창을 모두 등록하며, 모든 창을 신뢰할 수 있고 수집이 필요한 애플리케이션에 적합합니다. Preload를 대체할 수는 없습니다.

지정한 창만 모니터링하려면 bootstrap()에서 autoAttach: false를 유지한 후 해당 창을 등록합니다:

// client는 bootstrap()의 반환 값이며, window는 Preload가 구성된 BrowserWindow입니다.
const detach = client.attachWindow(window);
await window.loadFile("index.html");
// 수집을 조기에 중지해야 하는 경우 detach() 또는 client.detachWindow(window)를 호출합니다.

각 창은 개별적으로 등록합니다. 새로고침 및 탐색 시에는 다시 등록할 필요가 없습니다. 창이 소멸되면 Adapter가 등록을 자동으로 제거합니다. 신뢰할 수 없는 페이지를 포함하는 애플리케이션은 대상 창에만 Preload를 로드하고, 원격 페이지의 탐색, 팝업, 권한 및 허용 도메인을 제한하세요.

Renderer¶

managed와 external은 빠른 시작의 Renderer 초기화를 공용으로 사용합니다. 각 페이지는 Bridge가 준비된 후 Browser RUM을 초기화하며, 실제 애플리케이션 ID, 세션, 샘플링 및 업로드는 여전히 Native SDK가 관리합니다. Bridge가 존재한다고 해서 데이터가 반드시 전송되는 것은 아니므로 Main 전송 오류와 서버 수신 결과도 확인해야 합니다.

페이지 로그¶

먼저 Native 로그 기능을 활성화합니다. managed는 loggingEnabled: true로 설정하고, external은 Windows 호스트 또는 macOS Logger에 따라 구성합니다. 메인 프로세스는 client.capabilities.log로 실제 기능을 확인하고, 해당 기능이 활성화된 페이지에서만 Browser Logs를 초기화합니다. 비즈니스 Preload를 통해 이 상태를 전달하는 경우 불리언 값만 노출하세요.

@cloudcare/browser-logs를 설치한 후(Bridge 연동에는 3.3.6 이상 필요), RUM Bridge 연동이 완료된 Renderer에서 다음과 같이 사용합니다:

import { datafluxLogs } from "@cloudcare/browser-logs";

datafluxLogs.init({
  datakitOrigin: "http://127.0.0.1",
  sessionSampleRate: 100,
  forwardErrorsToLogs: true,
  forwardConsoleLogs: ["error", "warn"],
});

Browser는 100%로 유지하며, 실제 로그 샘플링은 Native가 제어합니다. Native 로그 기능을 끈 경우에도 페이지에서 Logs를 별도로 초기화하여 예비 업로드 경로로 사용하지 마세요.

Session Replay¶

Replay는 기본적으로 꺼져 있으며, Native SDK 구성, 해당 컴포넌트 및 Bridge 실제 기능 요구 사항을 모두 충족해야 합니다. 먼저 Windows 선택적 Replay 런타임 또는 macOS Replay 구성을 완료한 후, datafluxRum.init() 뒤에서 기능을 확인합니다:

const capabilities = JSON.parse(
  window.FTWebViewJavascriptBridge.getCapabilities(),
);
if (capabilities.includes("records")) {
  datafluxRum.startSessionReplayRecording();
}

records는 Native가 리플레이 기능을 제공함을 의미하며, 현재 세션이 반드시 샘플링에 포함된다는 뜻은 아닙니다. Browser 독립 녹화 프로세스를 그대로 적용하여 Replay를 강제로 활성화하지 마세요. 메인 프로세스에서도 client.capabilities.replay를 확인할 수 있습니다. 컴포넌트 누락, 비활성화, 활성화 후 검증은 플랫폼 설명에 따라 수행합니다.

수명 주기 및 진단¶

bootstrap()은 Client를 반환하며 capabilities, attachWindow(), detachWindow(), updateWindow(), transportState 및 멱등성 있는 stop()을 제공합니다. onError를 통해 비동기 전송 및 창 처리 오류를 수신하고, transportState는 쓰기 가능 상태, 백프레셔 및 전송 실패를 확인하는 데 사용합니다.

정상 종료 시에는 반드시 stop()을 기다려야 합니다. 전체 비동기 종료 처리는 빠른 시작 Main 예시를 참조하세요. 수집 중지는 "모든 오프라인 데이터가 업로드되었다"는 확인이 아닙니다. Windows 연결 타임아웃, Bridge 출력 및 시작 Action 등의 파라미터는 플랫폼 구성을 참조하세요. macOS는 Windows의 자동 시작 Action을 제공하지 않습니다. 혼합 모드의 리플레이 창 가시성 경계는 macOS Replay를 참조하세요.