macOS Electron 모니터링¶

이 페이지에서는 macOS 네이티브 호스트, 런타임, Replay, 패키징 및 서명에 대한 설명을 제공합니다. 처음 연동할 때는 Electron 앱 연동에서 방식을 선택하고, 앱의 주체가 Electron인 경우 managed 빠른 시작을 먼저 완료하세요.

macOS SDK는 Guance Electron Native Adapter를 통해 Electron에 연동됩니다. Renderer의 Browser RUM과 Browser Logs가 페이지 방문, 사용자 액션, 요청, 오류, Long Task, 페이지 로그를 수집하고, Electron 메인 프로세스가 데이터를 macOS 네이티브 SDK에 전달하여 네이티브 RUM 앱, 세션, 샘플링, 업로드를 통합 관리합니다. 세션 리플레이가 필요하면 아래 내용에 따라 네이티브 SDK와 페이지 녹화를 함께 구성하세요.

앱 구조에 따라 한 가지 모드를 선택하세요. 하나의 Electron 프로세스에서는 한 가지 모드만 사용합니다.

두 모드는 동일한 Preload, 창 등록, Renderer 초기화 방식을 사용합니다. Renderer에는 실제 RUM 앱 ID, 업로드 주소, Client Token을 구성하지 않습니다. 모드를 선택한 후 Preload를 구성하고 페이지 SDK를 초기화하세요. Electron 페이지를 독립형 웹 애플리케이션으로만 모니터링하려면 Web RUM의 Electron 연동을 참고하세요.

데이터 흐름은 다음과 같습니다.

전체 모드(managed)
Electron Renderer
  Browser SDK -> 보안 Preload -> Electron 메인 프로세스
                                      |
                                      v
                      Node Addon(Native SDK 포함)
                                      |
                                      v
                                     업로드

혼합 모드(external)
Electron Renderer
  Browser SDK -> 보안 Preload -> Electron 메인 프로세스
                                      |
                                      | 인증된 Unix Domain Socket
                                      v
                         macOS 네이티브 메인 프로그램
                         Native SDK -> 업로드

Electron 연동¶

의존성 설치¶

• Adapter와 Native 런타임을 설치하려면 Node.js 18 이상이 필요하며, npm Registry와 Native SDK의 GitHub Release에 접근할 수 있어야 합니다. 오프라인 환경에서는 npm 패키지, 의존성, Native 런타임 압축 파일을 미리 준비해야 합니다.
• 전체 모드는 사전 컴파일된 Universal 런타임을 사용하므로 설치 시 Native SDK를 컴파일하지 않으며, 이를 위해 Git, Swift, Xcode Command Line Tools를 설치할 필요가 없습니다. 앱 패키징, 서명, 공증에는 여전히 해당 macOS 툴체인이 필요합니다.
• 혼합 모드는 먼저 macOS 네이티브 호스트에서 Native SDK를 연동해야 합니다. 아래의 configureElectronProcess 연동 방식은 Native SDK 1.6.8-alpha.7부터 제공되며, 네이티브 호스트 통합을 참고하세요.

Guance Electron Native Adapter는 Electron 22.x(22.3.27 이상)와 43.x를 지원합니다.

전체 모드는 공통 빠른 시작에 따라 의존성을 설치하고 Main, Preload, Renderer를 연동합니다. 설치 시 호환되는 macOS 런타임이 자동으로 다운로드되며 로컬 컴파일은 필요하지 않습니다.

혼합 모드만 사용하는 경우 네이티브 호스트가 Native SDK를 제공하므로, Adapter를 설치할 때 필요하지 않은 런타임 다운로드를 건너뜁니다.

GUANCE_NATIVE_SKIP_DOWNLOAD=1 npm install @cloudcare/electron-native-adapter@alpha

페이지 의존성 및 초기화는 공통 Renderer 연동을 참고하고, 로그가 필요하면 아래의 네이티브 Logger 구성을 먼저 완료하세요.

전체 모드 Native 런타임 지정 또는 오프라인 설치¶

npm으로 자동 설치된 런타임을 사용할 때는 개발 단계에서 native.directory를 설정할 필요가 없습니다. Adapter가 자체 설치 디렉터리에서 런타임을 찾습니다. npm 패키지와 Native SDK의 버전 번호는 서로 독립적이며, 함께 제공되는 Native SDK 버전은 npm 패키지에 고정되므로 두 버전 번호가 같을 필요는 없습니다.

다른 Native SDK 버전을 지정하려면 Electron 앱 프로젝트 루트 디렉터리에서 다음 명령을 실행하고, <SDK_VERSION>을 Electron 런타임 자산이 포함된 Native SDK Release 태그로 바꾸세요.

npx guance-electron-native --sdk-version '<SDK_VERSION>'

이 명령은 arm64와 x86_64를 모두 포함하는 사전 컴파일된 Universal 런타임을 다운로드하며, 단일 아키텍처 소스 빌드 옵션은 제공되지 않습니다. 설치 프로그램은 압축 파일, SDK 버전, 아키텍처, 파일 해시를 검증합니다.

오프라인 설치 시 동일한 Release에 있는 guance-electron-runtime-<SDK_VERSION>-darwin-universal.tar.gz와 동일한 이름의 .sha256 파일을 미리 준비하고, 두 파일을 같은 디렉터리에 두세요.

npx guance-electron-native --sdk-version '<SDK_VERSION>' \
  --runtime-archive '/absolute/path/guance-electron-runtime-<SDK_VERSION>-darwin-universal.tar.gz'

오프라인 명령을 실행하기 전에 Adapter와 해당 npm 의존성이 설치되어 있어야 합니다. 그렇지 않으면 npx 자체가 npm에 접근할 수 있습니다. npm 설치 시 로컬 런타임 압축 파일을 전달할 수도 있습니다.

GUANCE_NATIVE_RUNTIME_ARCHIVE='/absolute/path/runtime.tar.gz' \
  npm install @cloudcare/electron-native-adapter@alpha

로컬 압축 파일은 네트워크 다운로드보다 우선하며, 해당 버전은 이번 설치에서 선택한 Native SDK 버전과 일치해야 합니다. npm 설치 시에는 GUANCE_NATIVE_SDK_VERSION으로 함께 제공되는 버전을 덮어쓸 수 있고, 명시적 CLI 설치에서는 --sdk-version을 사용합니다. 버전을 변경한 후에는 앱을 실행해 데이터가 정상적으로 전송되는지 확인하세요.

npm으로 자동 설치된 런타임은 node_modules/@cloudcare/electron-native-adapter/.cloudcare/native/darwin/runtime에 있습니다. 명시적 CLI 설치에서는 앱 프로젝트의 .cloudcare/native/darwin/runtime으로 출력되며, 이때 native.directory를 해당 디렉터리의 절대 경로로 설정해야 합니다. 프로젝트의 .cloudcare/는 Git 무시 규칙에 추가하는 것이 좋습니다.

패키징 시 전체 runtime 디렉터리를 앱 리소스 디렉터리에 함께 복사하세요. 자세한 구성은 패키징 리소스를 참고하세요.

Native Bridge 초기화¶

전체 모드¶

macOS managed 모드에서는 Electron 메인 프로세스가 Node Addon을 통해 Native SDK를 초기화합니다. 전체 예제는 managed 빠른 시작, 필드 및 샘플링 단위는 Main 구성을 참고하세요.

macOS에서 실제로 전송되는 앱 버전은 앱 패키징 정보에 따라 결정됩니다. 네이티브 SDK의 샘플링 API를 직접 호출할 때는 0..100을 사용하며, 이전 Adapter 필드의 0..1 단위와 혼용하지 마세요.

혼합 모드¶

혼합 모드는 native.mode: 'external'을 사용하며, 먼저 macOS 네이티브 호스트에서 SDK를 구성한 후 네이티브 호스트가 Electron을 시작해야 합니다. 앱 정보, 업로드 주소, 수집 옵션은 네이티브 호스트에서 일괄 설정합니다.

네이티브 호스트 통합¶

네이티브 호스트 프로젝트에서 Swift Package Manager를 통해 Native SDK를 추가하고, <SDK_VERSION>을 사용 중인 SDK 버전 번호로 바꾸세요.

.package(
    url: "https://github.com/GuanceCloud/datakit-ios.git",
    exact: "<SDK_VERSION>"
)

다음 Product를 macOS 메인 프로그램 타깃에 추가하세요.

• GuanceSDK: Native SDK
• GuanceElectronWebView: Electron 페이지 데이터 연동용
• GuanceSessionReplay: Session Replay가 필요할 때만 추가

네이티브 호스트는 먼저 SDK와 RUM을 초기화합니다. 이미 SDK에 연동된 앱은 기존 초기화 코드를 유지하고 enableTraceWebView를 활성화하면 되며, 중복 초기화할 필요가 없습니다.

#import <GuanceSDK/GuanceSDK.h>
#import <GuanceElectronWebView/GuanceElectronWebView.h>

FTSDKConfig *sdkConfig =
    [[FTSDKConfig alloc] initWithDatakitUrl:@"http://127.0.0.1:9529"];
[FTSDKAgent startWithConfigOptions:sdkConfig];

FTRumConfig *rumConfig =
    [[FTRumConfig alloc] initWithAppid:@"<RUM 앱 ID>"];
rumConfig.enableTraceWebView = YES;
rumConfig.enableTraceUserView = YES;
[[FTSDKAgent sharedInstance] startRumWithConfigOptions:rumConfig];

Session Replay가 필요하면 Electron 자식 프로세스를 시작하기 전에 Native SDK의 Session Replay API로 초기화하세요. 페이지 로그가 필요할 때도 이 단계에서 네이티브 Logger 구성을 완료해야 합니다.

#import <GuanceSessionReplay/GuanceSessionReplay.h>

FTSessionReplayConfig *replayConfig = [[FTSessionReplayConfig alloc] init];
replayConfig.sampleRate = 100;
replayConfig.textAndInputPrivacy = FTTextAndInputPrivacyLevelMaskSensitiveInputs;
[[FTRumSessionReplay sharedInstance]
    startWithSessionReplayConfig:replayConfig];

Electron 자식 프로세스 구성 및 시작¶

FTElectronBridgeServer와 NSTask를 생성하고, 자식 프로세스를 시작하기 전에 configureElectronProcess:error:를 호출하세요. 이 메서드는 Bridge를 자동으로 시작하고 연결 매개변수를 지정된 자식 프로세스의 환경 변수에 병합하므로, startWithError:를 별도로 호출하거나 Bridge 환경 변수를 수동으로 설정할 필요가 없습니다.

AppDelegate 또는 자식 프로세스 수명 주기를 담당하는 객체에 강한 참조 속성을 선언하세요.

@property (nonatomic, strong) FTElectronBridgeServer *electronBridgeServer;
@property (nonatomic, strong) NSTask *electronProcess;

위의 Native SDK 구성을 완료한 후 다음 시작 코드를 실행하세요.

self.electronBridgeServer = [[FTElectronBridgeServer alloc] init];
self.electronProcess = [[NSTask alloc] init];
self.electronProcess.executableURL =
    [NSURL fileURLWithPath:@"<Electron 실행 파일의 절대 경로>"];
// 앱 구조에 따라 시작 인수를 설정합니다. 예: 개발 모드의 Electron 프로젝트 경로.
// self.electronProcess.arguments = @[@"<Electron 프로젝트의 절대 경로>"];

NSError *error = nil;
if (![self.electronBridgeServer
        configureElectronProcess:self.electronProcess error:&error]) {
    [self.electronBridgeServer stop];
    // 앱에서 error를 처리하고, 구성에 성공하지 못한 자식 프로세스를 계속 시작하지 마세요.
    return;
}

// configureElectronProcess는 프로세스만 구성하며 Electron을 자동으로 시작하지 않습니다.
if (![self.electronProcess launchAndReturnError:&error]) {
    [self.electronBridgeServer stop];
    // 앱에서 시작 실패를 처리하세요.
    return;
}

Swift에서는 try bridgeServer.configureElectronProcess(process)로 호출한 다음 try process.run()을 실행합니다.

비즈니스 환경 변수를 전달해야 하면 configureElectronProcess를 호출하기 전에 electronProcess.environment를 설정하세요. SDK는 기존의 Bridge가 아닌 매개변수를 유지하며, 설정하지 않은 경우 NSProcessInfo.processInfo.environment를 상속합니다. 이 메서드는 지정된 자식 프로세스의 시작 환경만 수정할 뿐 네이티브 호스트의 환경은 수정하지 않습니다. 시작 전에 여러 번 호출할 수 있지만, 현재 Bridge의 값으로 기존 Bridge 매개변수를 대체합니다.

다음 연결 매개변수는 Native Bridge가 생성하거나 제공하며, Adapter는 기본적으로 Electron 메인 프로세스의 process.env에서 읽어옵니다. 사용자가 직접 값을 할당하거나 .env.local에 작성할 필요가 없으며, 이러한 매개변수를 Renderer에 노출하지 마세요.

configureElectronProcess를 지원하지 않는 이전 SDK나 사용자 지정 실행기를 사용할 때는 startWithError:를 먼저 호출한 다음 environmentByAddingToEnvironment:의 반환 값을 Electron의 시작 환경으로 전달할 수 있습니다. Bridge만 시작해도 다른 프로세스의 환경 변수가 자동으로 수정되지는 않습니다.

Electron 메인 프로세스 구성¶

Electron이 첫 번째 창을 생성하거나 이동하기 전에 bootstrap()을 사용해 네이티브 호스트에 연결하세요. native.settings를 전달하거나 연결 매개변수를 수동으로 읽을 필요가 없습니다.

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

let client

app.whenReady().then(async () => {
  client = await bootstrap({
    electron,
    native: {
      mode: 'external',
    },
    autoAttach: true,
  })

  const window = new BrowserWindow({ /* 안전한 Preload 구성 */ })
  await window.loadURL('https://example.com')
})

앱 종료¶

정상적으로 종료할 때는 client.stop()이 완료될 때까지 기다리세요. 자세한 처리는 공통 수명 주기를 참고하세요. 혼합 모드에서는 Electron 연결만 끊으며, Bridge와 Native SDK를 중지하는 것은 여전히 네이티브 호스트의 역할입니다.

Preload 및 창 연동¶

공통 Preload 구성에 따라 브리지를 로드하고, 안전한 창 옵션을 사용하며 비즈니스 Preload를 올바르게 패키징하세요.

수집 창 지정¶

공통 창 관리에 따라 autoAttach를 선택하거나 수동으로 등록하고, 수집 대상 각 창은 페이지를 로드하기 전에 연동을 완료하세요.

Renderer 초기화¶

두 모드는 빠른 시작의 Renderer 초기화를 공통으로 사용합니다. 자리 표시자 매개변수를 유지하고, 실제 앱, 업로드 주소, 자격 증명은 Main 또는 네이티브 호스트에서 구성합니다.

사용자 액션 수집¶

페이지 클릭 등의 사용자 액션을 수집해야 할 때는 이 섹션의 Renderer 초기화 예시에 따라 trackUserInteractions: true를 설정하세요. 혼합 모드에서 네이티브 컨트롤의 자동 액션 수집은 네이티브 호스트의 RUM 구성을 통해 활성화합니다.

페이지 로그 수집¶

페이지 로그를 수집해야 하면 먼저 연동 모드에 따라 로그 수집을 활성화하세요.

• 전체 모드: Electron 메인 프로세스의 native.settings에서 loggingEnabled: true를 설정하고, loggingSampleRate로 샘플링 비율을 설정합니다.
• 혼합 모드: macOS 네이티브 호스트에서 Logger를 초기화하고 enableWebViewLog를 활성화합니다.

혼합 모드에서는 네이티브 호스트가 Electron을 시작하기 전에 Logger를 구성하세요. 이미 Logger 초기화 코드가 있으면 다음 옵션을 기존 구성에 병합합니다.

FTLoggerConfig *loggerConfig = [[FTLoggerConfig alloc] init];
loggerConfig.enableWebViewLog = YES;
loggerConfig.enableLinkRumData = YES;
loggerConfig.sampleRate = 100;
[[FTSDKAgent sharedInstance] startLoggerWithConfigOptions:loggerConfig];

메인 프로세스는 client.capabilities.log로 네이티브가 페이지 로그를 수신할 수 있는지 확인할 수 있습니다. 이 능력이 활성화된 페이지에서만 Browser Logs를 초기화하세요. 비즈니스 Preload를 통해 이 상태를 페이지에 전달할 때는 필요한 불리언 값만 노출하고 전체 네이티브 구성을 전달하지 마세요.

enableWebViewLog는 페이지 로그를 수신하는 데 사용됩니다. 로그를 네이티브 RUM 세션과 연결해야 하면 enableLinkRumData: YES도 함께 설정하고, 혼합 모드 예시대로 RUM의 enableTraceWebView를 활성화하세요.

네이티브 구성을 완료한 후 공통 페이지 로그 구성에 따라 Browser Logs를 초기화하여 이중 샘플링을 방지하세요.

세션 리플레이 활성화¶

먼저 연동 모드에 따라 리플레이 수집을 활성화하세요.

• 전체 모드: native.settings에서 replayEnabled: true를 설정하고, 필요에 따라 replaySampleRate와 replayPrivacy를 설정합니다.
• 혼합 모드: 네이티브 호스트에서 혼합 모드 예시에 따라 Session Replay의 샘플링 비율과 프라이버시 보호 방식을 구성합니다.

리플레이는 기본적으로 꺼져 있습니다. 네이티브 구성을 완료한 후 공통 Replay 기능 확인에 따라 Bridge가 records를 반환할 때만 녹화를 시작하세요. 이 능력이 현재 세션이 반드시 샘플링 대상이 된다는 의미는 아닙니다.

연동을 완료한 후 Guance에서 페이지 방문, 사용자 액션, 해당 리플레이를 확인할 수 있습니다. 혼합 모드에서는 동일한 세션에서 네이티브 앱과 Electron 페이지의 방문 데이터를 확인할 수 있으며, 네이티브 화면과 Electron 페이지의 리플레이는 각각 표시됩니다.

혼합 모드의 페이지 스냅샷은 Browser SDK가 관리하며, Native Bridge는 반대로 페이지 전체 스냅샷을 트리거하지 않습니다. 혼합 모드에서 녹화를 일시 중지하는 방법으로 client.updateWindow(..., { visible: false })를 사용하지 마세요. 전체 모드에서는 네이티브와 페이지 간의 스냅샷 동기화 메커니즘이 유지됩니다.

패키징 리소스¶

전체 모드¶

managed 모드는 먼저 Native 런타임을 설치한 다음 전체 디렉터리를 ASAR 외부로 복사해야 합니다. macOS Universal 산출물에는 arm64와 x86_64가 포함됩니다. npm으로 자동 설치된 런타임을 사용할 때 electron-builder는 다음 extraResources 구성으로 런타임을 복사하고 .node를 macOS 바이너리 서명 구성에 추가할 수 있습니다.

{
  "extraResources": [
    {
      "from": "node_modules/@cloudcare/electron-native-adapter/.cloudcare/native/darwin/runtime",
      "to": "native"
    }
  ],
  "mac": {
    "binaries": [
      "Contents/Resources/native/guance_electron.node"
    ]
  }
}

명시적 CLI 설치를 사용하는 경우 위의 from을 앱 프로젝트의 .cloudcare/native/darwin/runtime으로 변경하세요. .node 파일만 복사하지 말고, 런타임의 리소스 번들도 함께 포함해야 합니다. 패키징된 Adapter는 기본적으로 process.resourcesPath 아래의 native 디렉터리를 우선 사용합니다. native.directory를 명시적으로 구성한 경우 패키징 후에도 해당 디렉터리를 가리키도록 해야 하며, 개발 머신 경로를 계속 사용하면 안 됩니다.

앱의 기존 macOS 서명 및 공증 프로세스를 그대로 사용하고 guance_electron.node도 함께 서명하세요. 출시 전에 패키징된 앱을 실행하여 SDK가 정상적으로 로드되고 데이터를 전송하는지 검증하세요.

혼합 모드¶

혼합 모드는 네이티브 호스트의 기존 프로세스에 따라 Native SDK, GuanceElectronWebView, 필요에 따라 사용하는 Session Replay 구성 요소를 패키징하고 서명합니다. Electron은 일반적인 방식으로 패키징하면 됩니다.

통합 경계¶

• 페이지 RUM 이벤트와 로그는 Preload와 메인 프로세스를 거쳐 Native SDK에 전달됩니다. SDK 내부 IPC 채널을 직접 등록하거나 전달하지 마세요.
• Adapter는 등록된 창의 메인 프레임 이벤트만 수락하며, 자식 프레임은 독립적인 신뢰할 수 있는 진입점으로 취급하지 않습니다.
• traceEnabled는 Native SDK Trace를 구성하는 것으로, Renderer의 fetch/XHR에 분산 추적을 자동으로 구성하지 않습니다. 페이지 요청에 트레이스 연결이 필요한 경우 Browser RUM에서 allowedTracingUrls와 백엔드에 맞는 traceType을 별도로 설정하세요. 저장소의 Electron 예제를 참고할 수 있습니다.
• 현재 macOS Adapter는 Windows 연동에서 제공하는 자동 launch_cold, launch_hot 액션 전송을 제공하지 않습니다. enableAppLaunch가 macOS에서 이러한 이벤트를 생성할 것이라고 기대하지 마세요.
• Renderer JavaScript 오류와 Long Task는 Browser RUM이 수집합니다. Electron의 unresponsive, render-process-gone은 Bridge가 자동으로 RUM 오류로 변환하지 않습니다. 네이티브 호스트의 크래시 모니터링도 Electron 자식 프로세스의 크래시 수집을 대체할 수 없으므로 앱 요구 사항에 따라 별도로 연동해야 합니다.
• 원격 페이지의 탐색, 팝업, 권한, 허용 도메인을 제한하세요. 업로드 주소와 자격 증명은 Electron 메인 프로세스 또는 네이티브 호스트에 구성하고 페이지 코드에는 작성하지 마세요.

통합 검증¶

1. 앱을 시작하고 메인 프로세스와 페이지 콘솔에 SDK 초기화 오류가 없는지 확인하세요. Renderer DevTools의 Network에서 RUM 또는 로그 직접 전송 요청이 없는지 확인합니다.
2. 페이지에 접속하고 컨트롤을 클릭하며 요청을 보내고 오류와 Long Task를 하나씩 발생시킨 다음, Guance에서 해당 데이터를 확인할 수 있고 앱 ID가 네이티브 구성으로 설정되어 있는지 확인하세요. 페이지 로그를 활성화한 후 로그를 하나 보내 검증합니다.
3. 리플레이를 끈 상태에서 getCapabilities()에 records가 포함되지 않는지 확인하세요. 활성화하고 샘플링에 포함된 후 녹화 결과를 확인하여 텍스트와 입력 내용이 선택한 프라이버시 설정에 맞는지 확인합니다.
4. 두 번째 창을 만들어 해당 창을 수집할 수 있는지 확인하세요. 지정한 창 수집을 사용할 때는 연동되지 않은 창에 데이터가 없는지 확인합니다.
5. 혼합 모드에서 동일한 세션의 네이티브 앱과 Electron 페이지 방문 기록을 확인하세요.
6. 전체 모드 앱을 종료하고 client.stop()이 완료되는지 확인하세요. 혼합 모드 Electron 자식 프로세스를 종료하여 네이티브 SDK가 계속 수집하고 전송하는지 확인합니다. 패키징된 앱을 실행하여 데이터와 리플레이가 정상인지 다시 검증하세요.

전체 예제는 macOS SDK 저장소의 Electron 전체 모드 예제와 네이티브 호스트 혼합 모드 예제에서 확인할 수 있습니다.

자주 묻는 질문¶