시작하기

설치

npm

npm install @capgo/capacitor-updater
npx cap sync

yarn

yarn add @capgo/capacitor-updater
npx cap sync

pnpm

pnpm add @capgo/capacitor-updater
npx cap sync

bun

bun add @capgo/capacitor-updater
npx cap sync

빠른 시작

대부분의 사용자에게는 플러그인 설치와 Capgo 클라우드 통합을 모두 다루는 메인 빠른 시작 가이드를 따르는 것을 권장합니다.

이 시작 가이드는 기본 메커니즘을 이해하거나 자체 호스팅 업데이트를 구현하려는 고급 사용자를 위한 기술적 플러그인 세부 정보에 중점을 둡니다.

개요

Capacitor Updater 플러그인은 Capacitor 애플리케이션에 대한 무선(OTA) 업데이트를 가능하게 합니다. 이를 통해 앱 스토어 검토를 거치지 않고도 앱에 업데이트를 푸시할 수 있습니다.

작동 방식

1. 번들 다운로드: 플러그인이 업데이트 번들(웹 자산이 포함된 ZIP 파일)을 다운로드합니다
2. 추출: 번들이 기기의 스토리지로 추출됩니다
3. 핫 리로드: 앱이 다시 시작하지 않고도 새 번들로 전환됩니다
4. 폴백: 업데이트가 실패하면 앱이 이전 작동 버전으로 되돌아갑니다

사용 모드

1. 자동 업데이트 모드 (권장)

자동 업데이트 관리를 사용하는 가장 간단한 방법:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// 플러그인이 모든 것을 자동으로 처리합니다
// capacitor.config.ts에서 구성

capacitor.config.ts에 추가:

{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      updateUrl: 'https://your-update-server.com/api/updates'
    }
  }
}

2. 수동 모드

업데이트 프로세스에 대한 고급 제어:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// 업데이트 다운로드
const bundle = await CapacitorUpdater.download({
  url: 'https://your-server.com/updates/v1.0.1.zip',
  version: '1.0.1'
});

// 번들 설정 (다음 앱 시작 시 사용됨)
await CapacitorUpdater.set({
  id: bundle.id
});

// 또는 즉시 다시 로드
await CapacitorUpdater.reload();

플랫폼 구성

iOS

추가 구성이 필요하지 않습니다. 플러그인이 즉시 작동합니다.

Android

추가 구성이 필요하지 않습니다. 플러그인이 즉시 작동합니다.

기본 API 사용법

업데이트 다운로드

import { CapacitorUpdater } from '@capgo/capacitor-updater';

const bundle = await CapacitorUpdater.download({
  url: 'https://example.com/update.zip',
  version: '1.0.1'
});

console.log('다운로드된 번들:', bundle.id);

활성 번들 설정

// 다음 앱 시작 시 사용할 번들 설정
await CapacitorUpdater.set({
  id: bundle.id
});

새 번들로 다시 로드

// 새 번들로 앱을 즉시 다시 로드
await CapacitorUpdater.reload();

번들 목록

const { bundles } = await CapacitorUpdater.list();
console.log('사용 가능한 번들:', bundles);

번들 삭제

await CapacitorUpdater.delete({
  id: 'bundle-id'
});

현재 번들 가져오기

const { bundle } = await CapacitorUpdater.current();
console.log('현재 번들:', bundle.version);

이벤트 리스너

업데이트 이벤트 수신:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// 다운로드 진행률 수신
CapacitorUpdater.addListener('download', (info) => {
  console.log('다운로드 진행률:', info.percent);
});

// 다운로드 완료 수신
CapacitorUpdater.addListener('downloadComplete', (bundle) => {
  console.log('다운로드 완료:', bundle.version);
});

// 업데이트 실패 수신
CapacitorUpdater.addListener('updateFailed', (error) => {
  console.error('업데이트 실패:', error);
});

// 성공적인 업데이트 수신
CapacitorUpdater.addListener('updateAvailable', (info) => {
  console.log('사용 가능한 업데이트:', info.version);
});

구성 옵션

capacitor.config.ts에서 플러그인 구성:

{
  plugins: {
    CapacitorUpdater: {
      // 자동 업데이트 설정
      autoUpdate: true,
      updateUrl: 'https://api.example.com/updates',

      // 업데이트 동작
      resetWhenUpdate: true,
      directUpdate: false,

      // 버전 설정
      version: '1.0.0',

      // 보안
      allowModifyUrl: false,

      // 통계 수집
      statsUrl: 'https://api.example.com/stats',

      // 채널 (Capgo 클라우드용)
      defaultChannel: 'production'
    }
  }
}

통합 패턴

Capgo 클라우드와 함께

시작하는 가장 쉬운 방법:

// Capgo CLI 설치
npm install -g @capgo/cli

// Capgo에 로그인
npx @capgo/cli login

// 첫 번째 번들 업로드
npx @capgo/cli bundle upload

// 플러그인이 Capgo 클라우드에서 자동 업데이트

자세한 내용은 메인 빠른 시작 가이드를 참조하세요.

자체 호스팅 업데이트

자체 업데이트 서버 호스팅:

// 업데이트 엔드포인트 구성
{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      updateUrl: 'https://your-server.com/api/check-update'
    }
  }
}

서버는 다음을 반환해야 합니다:

{
  "version": "1.0.1",
  "url": "https://your-server.com/updates/1.0.1.zip"
}

전체 세부 정보는 자체 호스팅 모드를 참조하세요.

수동 업데이트 흐름

업데이트에 대한 완전한 제어:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

async function checkAndUpdate() {
  // 서버에서 업데이트 확인
  const response = await fetch('https://api.example.com/check-update');
  const { version, url } = await response.json();

  // 업데이트 다운로드
  const bundle = await CapacitorUpdater.download({
    url,
    version
  });

  // 번들이 준비되었음을 알림
  await CapacitorUpdater.notifyAppReady();

  // 다음 버전으로 설정
  await CapacitorUpdater.set({ id: bundle.id });

  // 준비되면 다시 로드
  await CapacitorUpdater.reload();
}

모범 사례

• 앱이 성공적으로 로드되면 항상 notifyAppReady()를 호출하세요
• 프로덕션에 푸시하기 전에 업데이트를 철저히 테스트하세요
• 네트워크 장애에 대한 적절한 오류 처리 구현
• 버전 번호를 일관되게 사용하세요
• 더 빠른 다운로드를 위해 번들 크기를 작게 유지하세요
• 업데이트 성공률 모니터링

다음 단계

• 플러그인 API 참조 - 전체 API 문서
• 플러그인 설정 - 모든 구성 옵션
• 이벤트 - 사용 가능한 업데이트 이벤트
• 자체 호스팅 모드 - 자체 업데이트 서버 실행
• 로컬 개발 - 로컬에서 업데이트 테스트
• 디버깅 - 문제 해결 가이드

지원

• 알려진 문제 - 일반적인 문제 및 해결책
• GitHub 토론 - 커뮤니티 지원
• Discord - 실시간 채팅