Capawesome Cloud에서 Capgo로 마이그레이션

이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.

⚡️ Capgo는 채널, 번들 정리, 롤백, 분석, CLI 업로드를 네이티브로 자동화합니다. 이 가이드에 따라 마이그레이션에 필요한 최소 단계를 수행하고, 필요하다면 여전히 필요한 커스텀 동작을 다시 구현하세요.

개요

나중에 아카이브하거나 감사(audit)할 수 있도록 기존 Capawesome Cloud 설정(App ID, 채널, 서명 키, CLI 토큰)을 모아 두세요.
Capgo 플러그인을 설치하고 Capawesome SDK를 제거한 뒤 호출하세요 CapacitorUpdater.notifyAppReady().
현재 수동 다운로드, 번들 고정(pinning), 리로드 같은 플로우를 쓴다면 해당 옵션을 설정하세요.

Capgo를 사용하면 저희 플러그인을 설치한 뒤 호출하기만 하면 됩니다 CapacitorUpdater.notifyAppReady(). 채널, 번들 정리, 롤백, 분석, CLI 자동화 등 나머지는 모두 네이티브로 처리됩니다. 아래 섹션에서 각 작업을 하나씩 다룹니다.

시작하기 전에

프로젝트가 이미 Capacitor 5 이상을 사용하고 있는지 확인하세요.
Capgo CLI (npm install -g @capgo/cli)를 CI/CD에서 번들을 푸시할 계획이라면 설치하세요.

1단계 – Capgo 설치 및 Capawesome SDK 제거

npm uninstall @capawesome/capacitor-live-update
npm install @capgo/capacitor-updater
npx cap sync

이것이 유일한 필수 교체 작업입니다. Capgo의 네이티브 code는 플러그인에 포함되어 있어 별도의 JavaScript 헬퍼가 필요하지 않습니다.

2단계 – 최소 설정

이전 설정에서는 다음의 수많은 옵션을 매핑해야 했습니다: capacitor.config. Capgo는 프로젝트를 자동으로 인식하므로, 최소 설정은 다음과 같습니다:

import { CapacitorConfig } from '@capacitor/cli'

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      autoDeletePrevious: true,
      periodCheckDelay: 10 * 60 * 1000, // optional: check every 10 minutes
    },
  },
}

export default config

Capawesome에서 수동 플래그로 나열하는 모든 항목(defaultChannel, autoDeleteBundles, 보관 정책 등)은 Capgo 대시보드 또는 API을 통해 관리됩니다. Capgo의 기본값과 다른 동작을 원할 때만 이 키들을 오버라이드하면 됩니다.

설정 빠른 참조

Capawesome 옵션	Capgo 대응 기능	설정해야 하나요?
`appId`	프로젝트 생성 후 Capgo 대시보드에서 가져온 값	하나의 바이너리에서 여러 프로젝트를 사용하는 경우에만 해당
`defaultChannel`	대시보드/API에서 관리되는 채널 규칙	선택 사항; 대부분의 팀은 서버 측에서 설정합니다
`autoDeleteBundles`	`autoDeletePrevious: true` (기본값)	이미 활성화됨
`publicKey`	Capgo 콘솔에서 관리	키를 수동으로 교체하는 경우에만 해당
`maxVersions` / 보관 기간	Bundle 보관 정책	Capgo에서 중앙 설정 (기본 1개월, 최대 24개월)

3단계 – 호출 `notifyAppReady()` (유일하게 필수적인 hook)

기존 워크플로우에서는 커스텀 리스너를 사용했습니다(checkForUpdates(), retryDownload(), 스플래시 화면 숨기기 등). Capgo는 이러한 단계를 네이티브로 수행합니다. 반드시 호출해야 하는 유일한 API은 다음과 같습니다:

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

CapacitorUpdater.notifyAppReady()

앱이 성공적으로 부팅되었음을 확인합니다. 확인 신호가 오지 않으면 Capgo가 자동으로 번들을 롤백하며, 추가 JavaScript 코드는 필요 없습니다.

이게 전부입니다. Capgo가 백그라운드 체크, 스플래시 화면 표시 및 롤백을 네이티브로 처리합니다.

선택 사항: 스플래시 화면이 사라지기 전에 커스텀 로직 실행

import { CapacitorUpdater } from '@capgo/capacitor-updater'
import { SplashScreen } from '@capacitor/splash-screen'

CapacitorUpdater.addListener('appReady', () => {
  // Run diagnostics or logging if you need to
  SplashScreen.hide()
})

CapacitorUpdater.notifyAppReady()

4단계 – API 호출 매핑 (대부분 선택 사항)

Capgo에서는 보통 자동 업데이터를 실행하도록 두지만, 완전한 제어를 원하면 수동 API도 사용할 수 있습니다.

Capawesome Cloud	Capgo 대응 기능	필요한가요?
`LiveUpdate.fetchLatestBundle()`	`CapacitorUpdater.getLatest()`	자체 다운로드 워크플로우를 구현할 때만 필요합니다
`LiveUpdate.downloadBundle()`	`CapacitorUpdater.download()`	선택 사항: 기존 native auto-update 다운로드 방식 유지
`LiveUpdate.setNextBundle()`	`CapacitorUpdater.next()`	선택 사항: dashboard에서 번들 자동 고정
`LiveUpdate.reload()`	`CapacitorUpdater.reload()`	선택 사항: 이후 Capgo를 통해 필수 번들 적용 `notifyAppReady()`
`LiveUpdate.getCurrentBundle()`	`CapacitorUpdater.current()`	선택 사항: 진단 도구

기존 native auto-update 방식을 그대로 사용한다면 Capawesome JavaScript를 완전히 삭제해도 됩니다.

수동 제어 예시

최신 번들 다운로드

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

const downloadUpdate = async () => {
  const latest = await CapacitorUpdater.getLatest()
  if (latest?.url) {
    const bundle = await CapacitorUpdater.download({
      url: latest.url,
      version: latest.version,
    })
    console.log('Bundle downloaded', bundle?.id)
  }
}

import { LiveUpdate } from '@capawesome/capacitor-live-update'

const downloadUpdate = async () => {
  const result = await LiveUpdate.fetchLatestBundle()
  if (result.downloadUrl) {
    await LiveUpdate.downloadBundle({
      bundleId: result.bundleId,
      url: result.downloadUrl,
    })
    console.log('Bundle downloaded')
  }
}

다음 bundle 설정

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

const setNextBundle = async () => {
  await CapacitorUpdater.next({ id: 'bundle-id-123' })
}

import { LiveUpdate } from '@capawesome/capacitor-live-update'

const setNextBundle = async () => {
  await LiveUpdate.setNextBundle({ bundleId: 'bundle-id-123' })
}

다운로드한 bundle을 즉시 적용

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

const applyUpdate = async () => {
  await CapacitorUpdater.reload()
}

import { LiveUpdate } from '@capawesome/capacitor-live-update'

const applyUpdate = async () => {
  await LiveUpdate.reload()
}

5단계 – 업데이트 전략: Capgo의 처리 방식

Capawesome에서는 세 가지 전략을 제시합니다. Capgo에서는 다음과 같이 적용됩니다:

백그라운드 업데이트

이전 워크플로우: code에서 설정하고 다운로드를 수동으로 예약해야 합니다.
Capgo: 기본적으로 활성화되어 있음 (autoUpdate: true). 추가적인 code가 필요하지 않습니다.

항상 최신 버전

이전 워크플로우: 추가 App.resume 리스너, 호출 download, 그 다음 set.
Capgo: 백그라운드 자동 업데이트가 resume 이후 이미 체크를 수행합니다. 커스텀 간격이 필요한 경우에만 수동 리스너를 사용하세요.

선택 사항: 수동 resume 체크

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

App.addListener('resume', async () => {
  const latest = await CapacitorUpdater.getLatest()
  if (latest?.url) {
    const downloaded = await CapacitorUpdater.download({
      url: latest.url,
      version: latest.version,
    })
    if (downloaded) {
      await CapacitorUpdater.next({ id: downloaded.id })
    }
  }
})

강제 업데이트

이전 워크플로우: 프롬프트 로직을 연결하고 리로드를 강제합니다.
Capgo: 대시보드에서 bundle을 “mandatory”로 설정한 다음, 다음을 감지합니다. majorAvailable event (emitted after notifyAppReady())를 통해 앱 내에서 사용자 업그레이드를 유도하세요.

6단계 – 번들 배포

기존에 다음을 사용하셨다면, capawesome live-update deployCapgo은 유사한 CLI 워크플로우를 제공하며, API를 통해 배포를 완전히 자동화할 수도 있습니다.

# Authenticate once (stores a token in your CI environment)
capgo login

# Upload a new bundle (auto-detects platform/version)
capgo bundle upload --path dist --channel production

Capgo은 번들 상태를 자동으로 추적하므로 다음 기능도 함께 제공합니다:

모든 설치 건에 대한 디바이스 레벨 감사 로그(audit logs).
자동 보관 기능(기본 1개월) 및 최대 24개월까지 설정 가능한 보관 제한.
실시간 지연 시간(latency) 메트릭 상태.capgo.app/history.

마이그레이션 일정

목록 확인 및 설치: 10분 (npm install, 기존 플러그인 제거).
설정 및 준비: 5분 (notifyAppReady).
정상 작동 확인: 15분 (선택 사항: 수동 테스트 또는 리스너).
첫 배포: Capgo CLI 또는 CI 연동 시 10분 소요.

실제로 대부분의 팀은 한 시간 이내에 완료합니다. Capawesome 프로젝트 세부 정보를 제공해 주시면 채널과 디바이스 목록까지 대신 가져올 수 있습니다.

Capgo 지원팀에 공유해 주세요.

마이그레이션 컨시어지: 세션 예약하기: book.capgo.app/demo.
커뮤니티: 다음 채널에 참여하세요: Capgo Discord.
이슈 트래커: github.com/Cap-go/capacitor-updater/issues.

Capgo는 장기적인 안정성을 위해 설계되었습니다. 네이티브 델타 업데이트, 암호화된 bundle, 자동 롤백, 그리고 별도의 JavaScript 코드가 필요 없는 분석 기능을 제공합니다. 마이그레이션이 완료되면 유지보수가 까다로운 glue 코드를 삭제하고 플랫폼이 자동으로 업데이트를 수행하도록 맡기세요.