시작하기

설치

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/capacitor-updater` plugin in my project.

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

npm

bun add @capgo/capacitor-updater
bunx cap sync

yarn

yarn add @capgo/capacitor-updater
bunx cap sync

pnpm

pnpm add @capgo/capacitor-updater
bunx cap sync

bun

bun add @capgo/capacitor-updater
bunx cap sync

빠른 시작

대부분의 사용자는 다음의 메인 Quickstart 가이드를 따르는 것을 권장합니다. 이 가이드에는 플러그인 설치와 Capgo 클라우드 연동 방법이 모두 포함되어 있습니다.

이 가이드는 내부 메커니즘을 이해하거나 자체 호스팅 업데이트를 구현하려는 숙련된 사용자를 위한 기술적인 플러그인 상세 정보를 다룹니다.

개요

Capacitor Updater 플러그인을 사용하면 Capacitor 애플리케이션에 OTA(over-the-air) 업데이트를 적용할 수 있습니다. 이를 통해 앱 스토어 심사 과정 없이 앱에 업데이트를 즉시 배포할 수 있습니다.

작동 원리

1. Bundle 다운로드: 플러그인이 업데이트 번들(웹 에셋이 포함된 ZIP 파일)을 다운로드합니다.
2. 압축 해제: 번들이 기기 저장소에 압축 해제됩니다.
3. 핫 리로드: 앱 재시작 없이 새로운 번들로 전환됩니다.
4. Fallback: 업데이트 실패 시, 앱은 이전의 정상 작동 버전으로 복구됩니다

사용 모드

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

자동 업데이트 관리를 통해 플러그인을 사용하는 가장 간단한 방법:

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

// Plugin handles everything automatically
// Configure in capacitor.config.ts

다음에 추가: capacitor.config.ts:

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

2. 수동 모드

업데이트 프로세스를 정밀하게 제어하려면:

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

// Download an update
const bundle = await CapacitorUpdater.download({
  url: 'https://your-server.com/updates/v1.0.1.zip',
  version: '1.0.1'
});

// Set the bundle (will be used on next app start)
await CapacitorUpdater.set({
  id: bundle.id
});

// Or reload immediately
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('Downloaded bundle:', bundle.id);

활성 번들 설정

// Set bundle to be used on next app start
await CapacitorUpdater.set({
  id: bundle.id
});

새 번들로 리로드

// Reload app immediately with new bundle
await CapacitorUpdater.reload();

Bundle 목록

const { bundles } = await CapacitorUpdater.list();
console.log('Available bundles:', bundles);

Bundle 삭제

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

현재 Bundle 가져오기

const { bundle } = await CapacitorUpdater.current();
console.log('Current bundle:', bundle.version);

이벤트 리스너

업데이트 이벤트 리스닝:

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

// Listen for download progress
CapacitorUpdater.addListener('download', (info) => {
  console.log('Download progress:', info.percent);
});

// Listen for download completion
CapacitorUpdater.addListener('downloadComplete', (bundle) => {
  console.log('Download complete:', bundle.version);
});

// Listen for update failures
CapacitorUpdater.addListener('updateFailed', (error) => {
  console.error('Update failed:', error);
});

// Listen for successful updates
CapacitorUpdater.addListener('updateAvailable', (info) => {
  console.log('Update available:', info.version);
});

설정 옵션

플러그인을 설정하세요: capacitor.config.ts:

{
  plugins: {
    CapacitorUpdater: {
      // Auto-update settings
      autoUpdate: 'atBackground',
      updateUrl: 'https://api.example.com/updates',

      // Update behavior
      resetWhenUpdate: true,

      // Version settings
      version: '1.0.0',

      // Security
      allowModifyUrl: false,

      // Stats collection
      statsUrl: 'https://api.example.com/stats',

      // Channel (for Capgo cloud)
      defaultChannel: 'production'
    }
  }
}

통합 패턴

Capgo Cloud와 함께

가장 빠르게 시작하는 방법:

// Install the Capgo CLI
bun add -g @capgo/cli

// Login to Capgo
npx @capgo/cli login

// Upload your first bundle
npx @capgo/cli bundle upload

// The plugin auto-updates from Capgo cloud

참고하세요: 예제 앱의 Quickstart 가이드 메인 에서 확인하세요.

자체 호스팅 업데이트

자체 업데이트 서버를 호스팅하세요:

// Configure your update endpoint
{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      updateUrl: 'https://your-server.com/api/check-update'
    }
  }
}

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

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

자세한 내용은 Self-Hosted 모드 자세한 내용은 확인하세요.

수동 업데이트 흐름

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

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

async function checkAndUpdate() {
  // Check for updates from your server
  const response = await fetch('https://api.example.com/check-update');
  const { version, url } = await response.json();

  // Download the update
  const bundle = await CapacitorUpdater.download({
    url,
    version
  });

  // Notify bundle is ready
  await CapacitorUpdater.notifyAppReady();

  // Set as next version
  await CapacitorUpdater.set({ id: bundle.id });

  // Reload when ready
  await CapacitorUpdater.reload();
}

모범 사례

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

다음 단계

• API 플러그인 레퍼런스 - 완전한 API 문서
• 플러그인 설정 - 모든 설정 옵션
• 이벤트 - 사용 가능한 업데이트 이벤트
• Self-Hosted 모드 - 자체 업데이트 서버 운영
• 로컬 개발 - 로컬에서 업데이트 테스트
• 디버깅 - 트러블슈팅 가이드

지원

• 알려진 이슈 - 자주 겪는 문제와 해결 방법
• GitHub 토론 - 커뮤니티 지원
• Discord에서 - 실시간 채팅

시작하기 다음 단계

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