Getting Started

설치

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.

만약 Manual Setup을 선호한다면, 플러그인을 설치하기 위해 다음 명령어를 실행하고 아래에 플랫폼에 따라 설명된 지침을 따르세요:

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

빠른 시작

대부분의 사용자에게는, 우리는 다음을 권장합니다. main 시작 가이드 Capgo 설정과 클라우드 통합을 모두 다루는 문서입니다.

이 시작 가이드는 기술적인 플러그인 세부 사항에 중점을 둡니다. 이 플러그인에 대한 이해를 높이고 자체 호스팅 업데이트를 구현하려는 고급 사용자에게 적합합니다.

개요

Capacitor 업데이터 플러그인은 Capacitor 애플리케이션에 대한 오버 더 에어(OTA) 업데이트를 지원합니다. 앱 스토어 리뷰를 거치지 않고 앱에 업데이트를 푸시할 수 있습니다.

작동 방식

1. 배포 다운로드: 플러그인은 업데이트를 다운로드하는 업데이트를 다운로드합니다 (ZIP 파일에 웹 자산이 포함되어 있습니다)
2. 추출: 업데이트는 장치의 저장소에 추출됩니다
3. Hot Reload: 앱은 새로운 번들을 사용하기 위해 재시작 없이 전환합니다.
4. Fallback: 업데이트 실패 시 이전에 작동하던 버전으로 돌아갑니다.

Usage Modes

1. Auto-Update Mode (Recommended)

자동 업데이트 관리와 함께 플러그인을 사용하는 가장 쉬운 방법:

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

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

Add to your 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

추가 설정이 필요하지 않습니다. 플러그인은 BOX에서 작동합니다.

Android

추가 설정이 필요하지 않습니다. 플러그인은 BOX에서 작동합니다.

기본 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();

번들 목록

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);

이벤트 리스너

__CAPGO_KEEP_0__

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

빠른 시작 main 빠른 시작 가이드 for details.

자체 호스팅 업데이트

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

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

__CAPGO_KEEP_1__

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

__CAPGO_KEEP_2__ 자체 호스팅 모드 for complete details.

수동 업데이트 흐름

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

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() 프로덕션으로 푸시하기 전에 업데이트 테스트를 철저히
• 네트워크 실패 시 적절한 오류 처리를 구현
• 버전 번호를 일관되게 사용
• 다운로드 속도가 빠른 빠른 배포를 위해 배ंडल 크기를 작게 유지
• 업데이트 성공률을 모니터링
• 다음 단계들로 진행하기

__CAPGO_KEEP_0__

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

지원

• 알려진 문제 - 일반적인 문제와 해결책
• GitHub Discussions - 커뮤니티 지원
• 디스코드 - 실시간 채팅

Getting Started에서 계속

사용 중인 경우 Getting Started native 플러그인 작업을 계획하기 위해 연결하세요. @capgo/capacitor-업데이터를 사용하여 @capgo/capacitor-업데이터를 사용하여 native 기능을 사용하는 경우, Capgo 플러그인 디렉토리 Capgo 플러그인 디렉토리에서 제품 워크플로우를 사용하는 경우, Capacitor 플러그인들에 의해 Capgo Capacitor 플러그인들에 의해 Capgo에서 구현 세부 정보를 사용하는 경우, 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트에서 구현 세부 정보를 사용하는 경우, Ionic Enterprise 플러그인 대체 Ionic Enterprise 플러그인 대체에서 제품 워크플로우를 사용하는 경우.