콘텐츠로 이동

Electron 빠른 시작

이 문서는 애플리케이션 자체가 Electron이고 Adapter가 Native SDK를 관리하는 전체 모드(managed)에 적용됩니다. Browser 단독 전송만 필요하거나 기존 네이티브 호스트가 있는 경우 먼저 액세스 방식 선택을 읽어 주세요.

준비 및 설치

대상 플랫폼의 네이티브 RUM 애플리케이션 ID와 사용 가능한 DataKit 주소 또는 DataWay 주소 및 Client Token을 준비합니다. 이 값들은 Main Process에서 구성되며, Native SDK가 Session, 샘플링, 사용자, 전역 컨텍스트, 영속화 및 업로드를 관리합니다. Renderer의 플레이스홀더 구성은 독립 Web 애플리케이션을 만드는 데 사용되지 않으며 업로드 역할도 담당하지 않습니다.

설치에는 Node.js 18+가 필요합니다. Windows에서는 대상 아키텍처와 일치하는 Microsoft Visual C++ v14 Redistributable 및 Windows Universal CRT가 추가로 필요합니다. Electron 및 플랫폼 요구 사항은 지원 범위를 참조하세요.

Electron Native Adapter 버전

기존 Electron 프로젝트에 설치합니다:

npm install @cloudcare/electron-native-adapter@alpha @cloudcare/browser-rum

postinstall이 현재 플랫폼에 맞는 Native Runtime을 다운로드하고 검증하므로 로컬 컴파일이 필요하지 않습니다. 설치 스크립트는 유지하세요. 이 예시에서는 native.directory를 설정하지 않습니다. 오프라인, 사용자 정의 런타임 및 네이티브 호스트 연동은 플랫폼별 문서를 참조하며, 최초 연동 시 vcpkg를 설치할 필요가 없습니다.

Main: 초기화 및 창 등록

다음 코드를 애플리케이션의 CommonJS 메인 프로세스 진입점(예: main.cjs)에 병합합니다. Electron이 준비되고 bootstrap()이 완료될 때까지 기다린 후 창을 생성하고 로드합니다.

const electron = require("electron");
const { app, BrowserWindow } = electron;
const { bootstrap } = require("@cloudcare/electron-native-adapter");

let client;
let stopping = false;
let stopped = false;

// Electron은 비동기 종료 콜백을 자동으로 기다리지 않습니다.
app.on("before-quit", (event) => {
  if (!client || stopped) return;
  event.preventDefault();
  if (stopping) return;
  stopping = true;
  client.stop().catch(console.error).finally(() => {
    stopped = true;
    app.quit();
  });
});

app.whenReady().then(async () => {
  client = await bootstrap({
    electron,
    native: {
      mode: "managed",
      settings: {
        applicationId: "<RUM 应用 ID>",
        datakitUrl: "http://127.0.0.1:9529",
        service: "electron-desktop",
        environment: "prod",
        version: app.getVersion(),
      },
    },
    autoAttach: true,
    onError: console.error,
  });

  const window = new BrowserWindow({
    webPreferences: {
      preload: require.resolve(
        "@cloudcare/electron-native-adapter/preload/standalone",
      ),
      contextIsolation: true,
      nodeIntegration: false,
      sandbox: true,
    },
  });
  await window.loadFile("index.html");
}).catch((error) => {
  console.error(error);
  app.quit();
});

app.on("window-all-closed", () => app.quit());

이 예시에서는 모든 창을 신뢰할 수 있으므로 autoAttach: true를 사용합니다. 일부 창만 모니터링하려면 수동 창 등록을 사용하세요. index.html은 애플리케이션의 실제 빌드 산출물 페이지 경로로 교체해야 합니다.

DataWay를 사용할 때는 datakitUrl을 datawayUrl 및 clientToken으로 교체하며, 실제 자격 증명은 Main에서만 구성합니다. macOS에서 실제로 전송되는 애플리케이션 버전은 애플리케이션 패키징 정보에 따라 결정됩니다.

Preload: 페이지 브리지 구축

위의 preload/standalone이 window.FTWebViewJavascriptBridge를 설치하므로 추가로 Preload 파일을 만들 필요가 없습니다. 이 Preload는 Browser RUM 초기화 전에 실행되어야 합니다. 애플리케이션에 기존 비즈니스 Preload가 있는 경우 Preload 병합에 따라 설치 함수를 연결하고 단일 파일로 번들링합니다.

Renderer: 페이지 수집 초기화

다음 코드를 기존 프런트엔드 빌드 도구가 처리하는 Renderer 진입점에 배치하고, index.html이 해당 진입점의 빌드 산출물을 로드하도록 합니다. npm bare 모듈 import가 포함된 소스 파일을 샌드박스 페이지 스크립트로 직접 로드하지 마세요.

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

if (typeof window.FTWebViewJavascriptBridge?.sendEvent !== "function") {
  throw new Error("Electron Native Bridge 尚未就绪");
}

datafluxRum.init({
  applicationId: "native-bridge",
  datakitOrigin: "http://127.0.0.1",
  service: "electron-renderer",
  env: "prod",
  sessionSampleRate: 100,
  trackUserInteractions: true,
});

applicationId와 datakitOrigin은 플레이스홀더 값으로 유지하면 됩니다. Bridge가 활성화되면 Browser SDK는 이벤트를 Native에 전달하며 이 주소로 RUM 요청을 보내지 않습니다. Bridge가 준비되지 않은 경우 먼저 Preload와 창 등록을 수정하고, 검사를 제거한 채 초기화를 계속하지 마세요. 또한 Browser 단독 전송의 실제 애플리케이션 ID, Token 또는 세션 영속화 구성을 혼합하지 마세요.

수집 대상 페이지마다 초기화를 한 번 수행합니다. 페이지가 새로고침되면 해당 페이지의 진입점에서 다시 초기화됩니다. 실제 샘플링은 Native가 제어하므로 Browser는 100%로 유지하여 샘플링 비율이 이중으로 낮아지지 않도록 합니다.

종료 정리

Main 예시는 이미 before-quit에서 client.stop()을 기다리므로 정리가 끝난 후에 종료를 계속합니다. Windows에서는 Adapter가 시작한 Bridge EXE를 종료하고, macOS에서는 Adapter가 초기화한 Native SDK를 종료합니다. 프로세스를 직접 종료하는 방식으로 정상 종료를 대체하지 마세요. stop()이 완료되었다고 해서 오프라인 큐가 모두 서버에 전송된 것은 아닙니다.

전송 검증

  1. 개발 실행: 프로젝트의 기존 실행 명령으로 애플리케이션을 실행하고 Main에 초기화 오류가 없으며 Renderer에 Bridge가 존재하고 Network에 Browser RUM 직접 전송 요청이 없는지 확인합니다.
  2. 페이지 이벤트: 페이지에 접속하고 버튼을 클릭하며 요청을 한 번 보내고 테스트 오류를 트리거한 후 Guance에서 View, Action, Resource, Error가 Native 구성의 애플리케이션 ID를 사용하는지 확인합니다. Long Task는 수집 임계값을 초과하는 작업을 트리거해야 합니다.
  3. 다중 창: 두 번째 창을 생성하고 동일한 Preload를 로드한 후 해당 페이지에서 Browser RUM을 초기화하여 두 창 모두에 데이터가 있는지 확인합니다. Native가 Session을 전환하지 않은 상태에서 세션 연결을 확인하고, 수동 등록을 사용하는 경우 등록되지 않은 창에서 Bridge 데이터가 생성되지 않는지 확인합니다.
  4. 종료: 애플리케이션을 정상적으로 종료하고 client.stop()이 완료되었으며 정리 오류가 없는지 확인합니다. Windows에서는 이 애플리케이션이 시작한 Bridge EXE가 종료되었는지 확인합니다.
  5. 패키징 실행: Windows 패키징 또는 macOS 패키징 및 서명에 따라 전체 런타임을 ASAR 외부로 전달한 후 패키징 산출물을 실행하고 위 검사를 반복합니다. 검증이 개발 머신의 절대 경로에 의존하지 않는지 확인합니다.

연동을 완료한 후 공통 구성에 따라 샘플링, 창 및 선택적 수집 기능을 조정합니다.

문서 평가

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