Electron Updater 시작하기

이 가이드는 설정을 도와드립니다. @capgo/electron-updater Electron 앱에서 JavaScript/HTML/CSS 라이브 업데이트를 활성화하는 방법을 안내합니다.

팁

Capacitor와 함께 Capgo를 이미 사용 중이신가요? Electron Updater는 동일한 Capgo Cloud 백엔드를 사용하므로, 하나의 dashboard에서 모바일과 데스크톱 앱을 모두 관리할 수 있습니다.

사전 요구사항

• Electron 20.0.0 이상
• Node.js 18 이상
• Capgo 계정 (가입하기: capgo.app)

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

그런 다음 아래 프롬프트를 사용하세요:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/electron-updater` plugin in my project.

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

1. 패키지를 설치하세요:

   npm install @capgo/electron-updater

2. Capgo 대시보드에서 App ID를 확인하세요. 아직 앱을 생성하지 않았다면 다음 명령어를 실행하세요:

   npx @capgo/cli@latest init

빠른 시작

import { requireUpdater } from '@capgo/electron-updater/renderer';

const updater = requireUpdater();
await updater.notifyAppReady();

자주 하는 실수

• 호출하세요 notifyAppReady() UI 초기화가 지연되기 전, 설정된 타임아웃 내에 앱 실행 초기에 수행됩니다.
• 메인 프로세스의 Capgo 서명 설정을 일치시키세요.
• 배포 전 업데이트 채널을 설정하세요.

설정

Electron Updater를 사용하려면 main process, preload script, renderer process 세 곳에서 설정이 필요합니다.

메인 프로세스

main.ts

import { app, BrowserWindow } from 'electron';
import * as path from 'path';
import {
  ElectronUpdater,
  setupIPCHandlers,
  setupEventForwarding,
} from '@capgo/electron-updater';

// Create updater instance with your Capgo App ID
const updater = new ElectronUpdater({
  appId: 'YOUR_CAPGO_APP_ID', // e.g., 'com.example.myapp'
  autoUpdate: true,
});

app.whenReady().then(async () => {
  const mainWindow = new BrowserWindow({
    width: 1200,
    height: 800,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true,
    },
  });

  // Initialize updater with window and builtin path
  const builtinPath = path.join(__dirname, 'www/index.html');
  await updater.initialize(mainWindow, builtinPath);

  // Setup IPC communication between main and renderer
  setupIPCHandlers(updater);
  setupEventForwarding(updater, mainWindow);

  // Load the current bundle (either builtin or downloaded update)
  await mainWindow.loadFile(updater.getCurrentBundlePath());
});

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit();
  }
});

Preload Script

preload.ts

import { exposeUpdaterAPI } from '@capgo/electron-updater/preload';

// Expose the updater API to the renderer process
exposeUpdaterAPI();

Renderer Process

// renderer.ts (or in your app's entry point)
import { requireUpdater } from '@capgo/electron-updater/renderer';

const updater = requireUpdater();

// CRITICAL: Call this on every app launch!
// This confirms the bundle loaded successfully and prevents rollback
await updater.notifyAppReady();

console.log('App ready, current bundle:', await updater.current());

주의

귀하 해야 합니다 호출 notifyAppReady() 앱 실행 후 10초 이내에 (다음 설정을 통해 구성 가능: appReadyTimeout). 호출되지 않으면 updater는 업데이트가 실패한 것으로 간주하고 이전 버전으로 롤백합니다.

업데이트 확인 중

사용하면 autoUpdate: true, updater가 자동으로 업데이트를 확인합니다. 수동으로 확인을 실행할 수도 있습니다:

// Check for updates manually
const latest = await updater.getLatest();

if (latest.url && !latest.error) {
  console.log('Update available:', latest.version);

  // Download the update
  const bundle = await updater.download({
    url: latest.url,
    version: latest.version,
    checksum: latest.checksum,
  });

  console.log('Downloaded bundle:', bundle.id);

  // Option 1: Queue for next restart
  await updater.next({ id: bundle.id });

  // Option 2: Apply immediately and reload
  // await updater.set({ id: bundle.id });
}

이벤트 리스닝

이벤트를 통해 업데이트 진행 상황과 상태를 추적하세요:

// Download progress
updater.addListener('download', (event) => {
  console.log(`Download progress: ${event.percent}%`);
});

// Update available
updater.addListener('updateAvailable', (event) => {
  console.log('New version available:', event.bundle.version);
});

// Download completed
updater.addListener('downloadComplete', (event) => {
  console.log('Download finished:', event.bundle.id);
});

// Update failed
updater.addListener('updateFailed', (event) => {
  console.error('Update failed:', event.bundle.version);
});

업데이트 배포하기

Capgo CLI를 사용하여 업데이트를 upload 하세요:

# Build your app
npm run build

# Upload to Capgo
npx @capgo/cli@latest bundle upload --channel=production

Electron 앱이 다음 확인 시 새 bundle을 자동으로 감지하고 download 합니다.

디버그 메뉴

개발 중에 디버그 메뉴를 활성화하려면:

const updater = new ElectronUpdater({
  appId: 'YOUR_CAPGO_APP_ID',
  debugMenu: true, // Enable debug menu
});

누르세요 Ctrl+Shift+D (또는 Cmd+Shift+D (Mac의 경우) 디버그 메뉴를 열어 다음 작업을 수행할 수 있습니다:

• 현재 bundle 정보 확인
• 사용 가능한 bundle 간 전환
• 내장 버전으로 초기화
• 기기 및 channel 정보 확인

설정 옵션

const updater = new ElectronUpdater({
  // Required
  appId: 'com.example.app',

  // Server URLs (defaults to Capgo Cloud)
  updateUrl: 'https://plugin.capgo.app/updates',
  channelUrl: 'https://plugin.capgo.app/channel_self',
  statsUrl: 'https://plugin.capgo.app/stats',

  // Behavior
  autoUpdate: true,           // Enable auto-updates
  appReadyTimeout: 10000,     // MS before rollback (default: 10s)
  autoDeleteFailed: true,     // Delete failed bundles
  autoDeletePrevious: true,   // Delete old bundles after successful update

  // Channels
  defaultChannel: 'production',

  // Security
  publicKey: '...',           // For end-to-end encryption

  // Debug
  debugMenu: false,           // Enable debug menu
  disableJSLogging: false,    // Disable console logs

  // Periodic Updates
  periodCheckDelay: 0,        // Seconds between checks (0 = disabled, min 600)
});

다음 단계

• API 레퍼런스 - 사용 가능한 모든 방법 살펴보기
• 채널 - 배포 채널에 대해 알아보기
• 롤백 - 롤백 방지 기능 이해하기

Electron Updater 시작하기 다음 단계

사용 중이라면 Electron Updater 시작하기 네이티브 플러그인 작업을 계획하려면, 이를 다음 항목과 연결하세요: @capgo/electron-updater 사용하기 @capgo/electron-updater 사용하기에서 네이티브 기능을 위해, Capgo 플러그인 디렉토리 Capgo Plugin Directory의 제품 워크플로우에 맞춰, Capgo의 Capacitor 플러그인 Capgo의 Capacitor 플러그인 구현 상세 내용에 대해서는, 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트 구현 상세 내용에 대해서는, Ionic Enterprise 플러그인 대안 Ionic Enterprise 플러그인 대안의 제품 워크플로우에 대해서는.