내용으로 건너뛰기
Capgo - Capacitor 앱용 실시간 업데이트 Capgo

채널

__CAPGO_KEEP_1__ install the Capgo Live Updates SDK __CAPGO_KEEP_0__

How a device picks a channel (precedence)

장치 채널 선택 순위

When a device checks for an update, Capgo decides which channel to use in this strict order (highest priority first):

  1. 장치 강제 매핑 (대시보드) – 특정 장치 ID를 채널에 고정하여 긴급 디버깅 또는 단일 실제 사용자와 제어된 테스트에 사용합니다.
  2. Cloud override (per-device) via Dashboard or API – 대시보드 또는 API를 통해 장치 채널을 변경할 때 생성됩니다. QA 사용자가 기능/PR 채널 또는 사용자 문제를 재현하기 위해switching합니다. 바이너리 재설치로 지워지지 않으며, 장치 항목 삭제로 지워집니다.
  1. Capacitor 설정 defaultChannel (테스트 빌드 기본값) – __CAPGO_KEEP_0__가 존재할 경우, force/override가 존재하지 않으면 앱은 이 채널에서 시작합니다 (예: ). capacitor.config.* 테스트 플라이트 / 내부 빌드용으로 설계되었습니다. 테스터는 자동으로 미리 릴리즈 채널에 접속하게 됩니다. 프로덕션 빌드는 일반적으로 이 설정을 비워둡니다. beta, qa, pr-123Cloud Default Channel (주요 경로 ~99%의 사용자)
  2. – Dashboard에서 기본 채널을 표시하면, 모든 일반 사용자 (force, override, config defaultChannel가 존재하지 않음)는 이 채널에 연결됩니다. 즉시 릴리즈 또는 롤백할 수 있습니다—새 바이너리가 필요하지 않습니다. 플랫폼별 기본값이 존재하는 경우 (예: iOS 전용, Android 전용, Electron 전용), 각 기기는 해당 플랫폼에 맞는 기본값으로 연결됩니다. Cloud Default 채널을 비워두는 것은 허용되며, 그 경우 기기는 1–3 단계를 통해 업데이트를 받습니다. Best practice:

1–3을 예외 / 테스트層으로 다루세요. Cloud Default를 설정하면, 실제 사용자는 이 채널로 흐릅니다. Cloud Default를 설정하지 않으면, 사용자가 연결하는 방법에 대해 명확하게 생각하세요 (일반적으로 config 또는 per-device override를 통해).

  • __CAPGO_KEEP_0__를 사용하여 config 또는 per-device override를 통해 사용자가 연결하는 방법을 명확하게 하세요. defaultChannel __CAPGO_KEEP_0__를 사용하여 config 또는 per-device override를 통해 사용자가 연결하는 방법을 명확하게 하세요.
  • 만들어야 하는 바이너리만 테스터에게 전송하세요. defaultChannel 생산 로직을 중앙에서 관리하기 위해 프로덕션 로직을 설정하지 않으면.
  • 적극적으로 사용하세요. setChannel() 생산에서 주로 QA 또는 특정 진단을 위해 사용하세요.

플랫폼 (iOS/Android/Electron)에서 채널이 비활성화되어 선택될 경우, 목록을 계속 진행합니다.

강제 > 오버라이드 > 설정 defaultChannel > Cloud Default.

기본 채널 동작

기본 채널 동작

클라우드 기본값을 설정하는 것은 선택사항이지만, 새로운 장치의 기본 경로로 사용됩니다. 기본값이 없으면, 강제 매핑, 오버라이드, 또는 __CAPGO_KEEP_0__ 설정에 일치하는 장치만 업데이트를 받습니다. 기본값을 설정할 때 다음 패턴을 고려하세요: defaultChannel in the Capacitor config will receive updates. When you do choose to mark defaults, keep these patterns in mind:

  • Single default (most common) – iOS, 안드로이드, 그리고 Electron이 모두 활성화된 채널은 유일한 기본 채널이 됩니다. 오버라이드가 없는 모든 기기는 여기에 연결됩니다.
  • 플랫폼별 기본값 – 플랫폼별로 채널을 나누면 (예를 들어 iOS만 활성화된 경우, ios-production 안드로이드만 활성화된 경우, android-production Electron만 활성화된 경우), 각 채널을 해당 플랫폼의 기본값으로 표시하세요. iOS 기기는 iOS 기본값으로, 안드로이드 기기는 안드로이드 기본값으로, Electron 앱은 Electron 기본값으로 연결됩니다. electron-production Cloudflare 기본값과

두 채널은 동일한 결정 층을 차지합니다. Cloudflare 기본값을 설정하면 __CAPGO_KEEP_0__ 구성에서 값을 중복으로 설정할 필요가 없습니다.—생산 빌드에서는 빈 채널을 남겨두세요. 테스터나 QA에게 배포할 때 비프로덕션 채널에 연결하고 싶다면, Cloudflare 기본값이 다른 경우에도. defaultChannel 기본값을 언제든지 대시보드에서 변경할 수 있습니다. 기본값을 교체하면 새로운 기기는 즉시 새로운 라우팅을 따르며 기존 기기는 다음에 체크인할 때 정상 우선순위 규칙을 따릅니다. capacitor.config.* both occupy the same decision layer. If you set a cloud default, you don’t need to duplicate the value in your Capacitor config—leave defaultChannel – defaultChannel –

–

채널 설정

채널 설정 섹션

온보딩 중에 첫 번째 채널을 생성합니다(대부분의 팀은 '생산'이라고 이름을 지어줍니다). 그러나 모든 것이 잠금 상태가 아니며, 채널 이름을 변경하거나 삭제할 수 있습니다. 추가 채널을 생성하려면:

  1. Capgo 대시보드의 '채널' 섹션으로 이동하세요
  2. 새 채널 버튼을 클릭하세요
  3. 채널 이름을 입력하고 '생성' 버튼을 클릭하세요

채널 이름은 마음대로 지어질 수 있습니다. 일반적인 전략은 개발 단계와 채널 이름을 일치시키는 것입니다.

  • Development - 로컬 장치나 에뮬레이터에서 실시간 업데이트를 테스트합니다
  • QA - QA 팀이 더 넓은 릴리스 전에 업데이트를 확인합니다
  • Staging - 실제 환경과 유사한 환경에서 최종 테스트를 진행합니다
  • Production - 앱 스토어에서 사용자에게 제공되는 앱 버전

앱에서 채널을 구성하세요

앱에서 채널을 구성하는 방법

채널이 생성되면, 해당 채널을 듣기 위해 앱을 구성해야 합니다. 이 예에서는 Development 채널.

채널을 열기 위해 capacitor.config.ts (또는 capacitor.config.json) 파일을 열어 plugins 부분 하위 섹션에서 defaultChannel 테스트 빌드 내부 / QA) 경우에만 생산 빌드의 경우 생략하는 것이 좋습니다. 이 경우 디바이스는 Cloud Default를 사용합니다. 만약 명시적으로 오버라이드하지 않는다면.

import { CapacitorConfig } from '@capacitor/cli';


const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      // For a QA/TestFlight build – testers start on the Development channel automatically.
      defaultChannel: 'Development',
      // Production builds usually omit this so users attach to the Cloud Default channel.
    },
  },
};

다음으로 웹 앱을 빌드하고 실행하세요 npx cap sync iOS, 안드로이드, 및 Electron 프로젝트에 업데이트된 구성 파일을 복사하세요. 이 동기화 단계를 건너뛰면, 네이티브 프로젝트는 이전에 구성된 채널을 계속 사용합니다.

채널 옵션 및 전략

Channel selection order: Force > Override (

채널은 여러 옵션을 제공하여 업데이트를 받을 수 있는 사람과 업데이트가 전달되는 방법을 제어합니다. 가장 중요한 것은 아래에 나열되어 있습니다. 웹 앱, CLI, 또는 Public API에서 이러한 옵션을 구성할 수 있습니다.

  • 기본 채널: 새로운 장치가 연결될 때 채널 또는 플랫폼별 채널을 표시할 수 있습니다. '기본 채널 동작'을 참조하여 라우팅 시나리오를 확인하세요.
  • 플랫폼 필터: iOS, Android, 또는 Electron , 장치에 업데이트를 전달할 수 있습니다.
  • 장치당 채널당
  • , 장치에 업데이트를 전달할 수 있습니다.
  • 네이티브 하위 버전 방지: 장치의 네이티브 앱 버전이 채널의 패키지 버전보다 새로운 경우 업데이트를 보내지 않도록 합니다. 예를 들어, 장치가 1.2.3 버전이고 채널이 1.2.2 버전인 경우.
  • 개발 빌드 허용: 테스트를 위해 업데이트를 개발 빌드로 허용합니다. setChannel에뮬레이터 장치 허용: 테스트를 위해 에뮬레이터/시뮬레이터에 업데이트를 허용합니다. setChannel 장치 자체 할당 허용: 런타임에 이 채널로 앱을 Switch할 수 있습니다. 만약 비활성화하면

, 이 채널에서 실패합니다.

업데이트 자동 업데이트 전략 비활성화 섹션

이 옵션을 사용하여 채널이 자동으로 전달할 수 있는 업데이트의 종류를 제한합니다.

  • major: 메이저 버전 간의 업데이트를 차단합니다 (0.0.0 → 1.0.0). 소수점 및 패치 업데이트는 허용됩니다.
  • minor: 소수점 버전 간의 업데이트를 차단합니다 (예: 1.1.0 → 1.2.0) 및 메이저 버전. 패치 업데이트는 허용됩니다. 주의: 0.1.0 → 1.1.0은 차단되지 않습니다.
  • patch: 매우 엄격합니다. 동일한 메이저 및 소수점 버전 내에서 패치 버전만 증가시키는 업데이트만 허용합니다. 예시: 0.0.311 → 0.0.314 ✅, 0.1.312 → 0.0.314 ❌, 1.0.312 → 0.0.314 ❌.
  • metadata: 업데이트된 버전 메타데이터가 각 패키지에 포함되어야 합니다. CLI을 사용하여 설정합니다. --min-update-version none: semver 호환성에 따라 모든 업데이트를 허용합니다. --auto-min-update-versionDisable updates strategy에 대한 자세한 내용과 예시를 보려면 /docs/__CAPGO_KEEP_0__/commands/#disable-updates-strategy을 참조하세요.
  • 예시 (__CAPGO_KEEP_0__):

Learn more details and examples in Disable updates strategy at /docs/cli/commands/#disable-updates-strategy.

CLI

__CAPGO_KEEP_0__
# Block major updates on the Production channel
npx @capgo/cli@latest channel set production com.example.app \
  --disable-auto-update major


# Allow devices to self-assign to the Beta channel
npx @capgo/cli@latest channel set beta com.example.app --self-assign

앱에서 setChannel() 사용

앱에서 setChannel() 사용

이 setChannel() 메소드는 앱이 런타임에 채널을 프로그래밍적으로switch할 수 있게합니다. 이 기능은 특히 다음 경우에 유용합니다:

  • QA/테스트 메뉴에서 테스터가 채널을 switch할 수 있도록 해주며
  • 베타 프로그램 옵인 플로우
  • 기능 플래그 구현
  • A/B 테스트 시나리오
import { CapacitorUpdater } from '@capgo/capacitor-updater';


// Switch to the beta channel
await CapacitorUpdater.setChannel({ channel: 'beta' });


// Optionally trigger an immediate update check after switching
await CapacitorUpdater.setChannel({
  channel: 'beta',
  triggerAutoUpdate: true
});

채널에 번들을 Assign하는 방법

채널에 번들을 Assign하는 방법

실시간 업데이트 배포를 위해서는 새로운 JS 번들을 업로드하고 채널에 Assign해야 합니다. Capgo CLI 단계에서 한번에 이 작업을 수행할 수 있습니다.

터미널 창
npx @capgo/cli@latest bundle upload --channel=Development

이 작업은 웹 자산을 빌드하고 새로운 번들을 활성화된 빌드로 설정합니다. 채널. 채널에 연결된 앱은 다음에 업데이트를 확인할 때 업데이트를 받습니다. Development 채널에 빌드를 Assign할 수 있습니다. __CAPGO_KEEP_0__ 대시보드의 "빌드" 섹션에서 메뉴 아이콘을 클릭하고 "Assign to Channel"을 선택하여 빌드에 채널을 선택할 수 있습니다.

You can also assign builds to channels from the “Bundles” section of the Capgo dashboard. Click the menu icon next to a build and select “Assign to Channel” to choose the channel for that build.

번들 버전 관리 및 채널

You can also assign builds to channels from the “Bundles” section of the __CAPGO_KEEP_0__ dashboard. Click the menu icon next to a build and select “Assign to Channel” to choose the channel for that build.

Capgo의 번들들은 앱 전체에 걸쳐 전역적이며, 개별 채널에 특정되지 않습니다. 동일한 번들을 여러 채널에 할당할 수 있습니다.

번들을 버전화할 때는 의미론적 버전 관리(semver)를 권장합니다. semver 예를 들어, 베타 버전은 채널에 특정된 빌드에 대해 버전화할 수 있습니다. 1.2.3-beta.1.

이 접근 방식에는 다음과 같은 이점이 있습니다:

  • 채널 빌드 간의 관계를 명확하게 전달합니다. 1.2.3-beta.1 __CAPGO_KEEP_0__는 __CAPGO_KEEP_1__의 전제 버전입니다. 1.2.3.
  • 채널 간에 버전 번호를 재사용할 수 있어 혼란을 줄입니다.
  • 명확한 롤백 경로를 제공합니다. __CAPGO_KEEP_0__에서 __CAPGO_KEEP_1__로 롤백할 필요가 있을 때, __CAPGO_KEEP_1__은 이전 안정 버전입니다. 1.2.3채널 설정의 일반적인 예를 통해 번들 버전을 어떻게 일치시킬 수 있는지 살펴보겠습니다: 1.2.2 이러한 접근 방식은 여러 채널에 걸쳐 버전 관리를 단순화하고, 롤백을 용이하게 합니다.

이러한 접근 방식은 여러 채널에 걸쳐 버전 관리를 단순화하고, 롤백을 용이하게 합니다.

  • Development 채널: 1.2.3-dev.1, 1.2.3-dev.2, etc.
  • QA 채널: 1.2.3-qa.1, 1.2.3-qa.2, etc.
  • Staging 채널: 1.2.3-rc.1, 1.2.3-rc.2, etc.
  • Production 채널: 1.2.3, 1.2.4, etc.

pre-release 식별자와 함께 semver를 사용하는 것은 권장되는 방법이지만, 엄격히 필요하지는 않습니다. 중요한 것은, 빌드 간의 관계를 명확하게 전달하고 팀의 개발 프로세스와 일치하는 버전 관리 방식을 찾는 것입니다.

실시간 업데이트 롤백

실시간 업데이트 롤백

실시간 업데이트에서 버그를 도입하거나 다시 되돌리기 위해 필요한 경우, 이전 빌드로 쉽게 롤백할 수 있습니다. 대시보드의 "채널" 섹션에서:

  1. 원하는 채널의 이름을 클릭하세요.
  2. 원하는 빌드를 찾고 crown 아이콘을 클릭하세요. 롤백 빌드
  3. 작업을 확인하세요.

선택한 빌드는 즉시 해당 채널의 활성 빌드로 변환됩니다. 앱은 업데이트를 확인할 때 다음으로 롤백된 버전을 받습니다.

배포 자동화

배포 자동화

더 복잡한 워크플로우를 위해, CI/CD pipeline의 일부로 라이브 업데이트 배포를 자동화할 수 있습니다. 빌드 프로세스에 Capgo을 통합하면, 특정 branch로 푸시하거나 새로운 릴리즈를 만들 때마다 새로운 배ंडल을 자동으로 업로드하고 채널에 assign할 수 있습니다.

배포 자동화에 대한 자세한 내용은 CI/CD Integration docs to learn more about automating Capgo live updates.

장치에 배포

장치에 배포하는 방법

채널을 이해한 후, 실제 장치에 라이브 업데이트를 배포하기 위해 준비가 되었습니다. 기본적인 프로세스는:

  1. 앱에 Capgo SDK을 설치합니다.
  2. 앱을 사용자가 원하는 채널에 수신하도록 구성합니다.
  3. 업데이트를 할당한 채널에 빌드를 업로드합니다.
  4. 앱을 실행하고 업데이트를 기다립니다!

상세한_walkthrough를 보려면 실시간 업데이트 배포 guide를 참조하세요. 업데이트를 즐기세요!

고급 채널 사용: 사용자 구분

장치에 배포하는 방법

고급 채널 사용: 사용자 구분

  • __CAPGO_KEEP_0__
  • __CAPGO_KEEP_1__
  • __CAPGO_KEEP_2__
  • __CAPGO_KEEP_3__

__CAPGO_KEEP_4__ __CAPGO_KEEP_5__.

__CAPGO_KEEP_6__

__CAPGO_KEEP_7__

__CAPGO_KEEP_8__ __CAPGO_KEEP_9__ __CAPGO_KEEP_10__ __CAPGO_KEEP_11__ 채널에서 구현 세부 정보에 대해 채널 채널에서 구현 세부 정보에 대해 베타 테스트 솔루션 베타 테스트 솔루션의 제품 워크플로에 대해 버전 대상 솔루션 버전 대상 솔루션의 제품 워크플로에 대해, 그리고 Capgo 환경 최적화: 단일 모바일 앱 ID와 스테이징 Capgo 환경 최적화: 단일 모바일 앱 ID와 스테이징에 대한 실제 상황에 대해