채널

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

Live Update 채널은 앱의 특정 JS bundle 빌드를 가리키며, 해당 채널의 업데이트를 수신하도록 설정된 모든 기기와 공유됩니다. 업데이트를 진행할 때 Capgo Live Updates SDK 설치 앱에서 해당 채널로 설정된 모든 native binary는 앱이 실행될 때마다 사용 가능한 업데이트가 있는지 확인합니다. 채널이 가리키는 빌드는 언제든 변경할 수 있으며, 필요 시 이전 빌드로 롤백할 수도 있습니다.

Channel 활용 사례

채널은 업데이트를 가리키는 이름이 지정된 포인터라고 생각하면 쉽습니다: production 배포된 앱을 서비스하는 동안 beta 테스터에게 서비스를 제공합니다. 세 개의 짧은 영상은 기기가 채널에 할당되는 과정을 보여줍니다. 각 영상에는 배경음악만 포함되어 있으며 별도의 설명은 없습니다. 아래의 설명이 동일한 단계를 다룹니다.

1. 기본 Channel 사용

실행 중인 기기가 v1.1.0 Capgo에 업데이트를 요청합니다. 기기 할당이나 앱에 설정된 채널이 없으면, Capgo은 클라우드 기본값을 확인하며, production, 그리고 해당 v1.2.0 bundle. dev 및 staging 채널은 이 기기에 영향을 주지 않고 자체 bundle을 유지합니다.

기본 채널 영상 다운로드 (MP4).

다음에서 production 기본값을 설정하세요: 앱 정보. 일반적인 production build는 defaultChannel 설정하지 않은 상태로 둘 수 있으며, Capgo에서 해당 라우팅을 관리할 수 있습니다.

2. 기기에서 Channel 선택

이 가이드에서는 다음을 사용합니다: setChannel() 및 unsetChannel() 과 @capgo/capacitor-updater Android 및 iOS에서 작동하며, 브라우저에서는 지원되지 않습니다. updater에서 제공하는 local-channel 방식을 사용합니다. 5.34.0+, 6.34.0+, 7.34.0+, 또는 8.0.0+ 플러그인의 메이저 버전에 맞춰 작동합니다. 이전 버전은 백엔드 오버라이드를 작성하는 방식이었으며, 현재 할당 방식은 console 및 API 오버라이드 유지 규칙을 따릅니다..

테스터가 앱 내부에서 베타 업데이트를 활성화합니다. 그러면 앱이 CapacitorUpdater.setChannel({ channel: 'beta', triggerAutoUpdate: true })를 호출합니다. Capgo는 이를 확인하여 beta 기기 자체 할당(self-assignment)을 허용하며, 플러그인은 향후 업데이트 확인을 위해 해당 선택 사항을 로컬에 저장합니다. 다른 기기들은 기존 라우팅을 유지합니다.

기기 셀프 할당 영상 다운로드 (MP4).

활성화 기기가 스스로 연결 해제/연결할 수 있도록 허용 사용하기 전에 대상 채널에서 setChannel(). 이 로컬 설정은 콘솔 오버라이드를 생성하지 않습니다. updater 8.51.0 이상의 Android 및 iOS에서는, persistDefaultChannelOnReinstall 기본값은 true, 따라서 OS가 앱 데이터를 복구할 때만 재설치 후에도 설정이 유지되며, persistDefaultChannelOnReinstall 유지됩니다 true. unsetChannel() 를 호출하여 로컬 설정을 초기화하세요. 콘솔 및 API 오버라이드는 여전히 아래 우선순위를 따릅니다.

3. 콘솔에서 기기 하나 할당하기

Capgo 콘솔에서, 앱 앱을 선택하고, 기기 디바이스를 선택하세요. 디바이스의 채널 오버라이드 대상 dev를 변경하면, Capgo가 해당 디바이스를 dev로 라우팅하며, 앱의 클라우드 기본값은 production.

콘솔 디바이스 오버라이드 영상 다운로드 (MP4).

특정 테스트나 지원을 위해 override를 사용하세요. 강제 매핑이 없는 한, 기기의 로컬 채널 및 클라우드 기본 설정보다 우선순위를 가집니다. Console 및 API override 마지막 override 작성 후 90일 뒤 만료.

지금 바로 시작해볼까요? Console에서 채널 생성, 그 다음 bundle upload 를 통해 배포합니다.

디바이스의 채널 선택 방식 (우선순위)

디바이스가 업데이트를 확인할 때, Capgo는 다음의 엄격한 순서에 따라 사용할 채널을 결정합니다 (높은 우선순위부터):

강제 디바이스 매핑 (Dashboard) – 특정 디바이스 ID를 채널에 수동으로 고정합니다. 긴급 디버깅이나 특정 실사용자를 대상으로 한 제어된 테스트에 사용하세요. 이 설정이 항상 최우선 적용됩니다. Capgo는 마지막 오버라이드 작성 후 90일이 지나면 매핑을 삭제합니다. 자세한 내용은 Console 및 API override는 90일 후 만료됩니다.
Dashboard 또는 API를 통한 클라우드 오버라이드 (디바이스별) – Dashboard나 API에서 디바이스의 채널을 변경할 때 생성됩니다. 기능/PR 채널을 전환하는 QA 사용자나 사용자 이슈 재현 시 사용하세요. 바이너리를 재설치해도 유지되며, 디바이스 오버라이드를 삭제해야만 해제됩니다. 동일하게 90일의 유지 기간이 적용됩니다.
플러그인 setChannel() 로컬 채널 – 앱이 다음을 호출할 때 생성됩니다: setChannel() 백엔드에서 대상 채널이 셀프 할당을 허용하는지 확인합니다. 선택된 채널은 해당 디바이스에 로컬로 저장되어 즉시 적용되며, Device Override UI에는 표시되지 않습니다.

플러그인 버전 5.34.0, 6.34.0, 7.34.0 또는 8.0.0부터 (사용 중인 메이저 버전에 따라 다름), setChannel() 작동 방식이 다릅니다. 백엔드에 접속하여 검증을 수행합니다. 해당 채널이 허용되는지 확인한 후(채널의 self-assignment 활성화 여부 체크), 채널 정보를 기기 로컬에 저장합니다. 로 defaultChannel따라서 새로운 채널은 즉시 다음 업데이트 확인 시 적용됩니다. 복제(replication)를 기다릴 필요가 없습니다.

이전에는, setChannel() 채널 오버라이드 설정을 백엔드 데이터베이스(API 또는 Dashboard와 같은 곳)에 저장했기 때문에, 새로운 채널이 인식되기까지 데이터 복제 시간(최대 2분)을 기다려야 했습니다. 이제는 백엔드에서 검증을 위해 데이터를 읽어온 뒤 로컬에 저장하므로, 채널 전환이 즉시 이루어집니다.

왜냐하면 setChannel() 로컬 전용이므로, 하지 마세요 Capgo dashboard에 Device Override 항목을 생성합니다. Device Override UI에는 dashboard나 Public API을 통해 생성된 오버라이드만 표시됩니다.

참고: 로컬에서 설정한 채널이 나중에 허용되지 않는 채널이 되더라도, 업데이트 체크 시 백엔드에서 채널을 검증하므로 보안은 그대로 유지됩니다.

중요: Dashboard나 API를 통해 채널을 변경하면, 모든 edge server에 변경 사항이 반영되기까지 최대 2분의 복제 지연이 발생할 수 있습니다. 즉각적인 채널 전환을 원한다면 다음을 사용하세요: setChannel() 앱의 code에서 실행하세요. 백엔드 검증을 거친 후 로컬에 채널을 즉시 설정합니다.

Capacitor 설정 defaultChannel (테스트 빌드 기본값) – 포함되어 있고 capacitor.config.* force/override/local 채널이 없으면, 앱은 이 채널로 시작됩니다 (예: beta, qa, pr-123). TestFlight 또는 내부 빌드용으로, 테스터가 자동으로 프리릴리스 채널에 들어가도록 하기 위한 설정입니다. 프로덕션 빌드에서는 보통 이 값을 설정하지 않습니다.
Cloud Default Channel (사용자의 약 99%가 이용하는 기본 경로) – 대시보드에서 기본 채널을 지정하면, 모든 일반 사용자(force, Dashboard/API override, 플러그인 local 채널, config defaultChannel이 없는 경우)가 이 채널에 연결됩니다. 새로운 바이너리 배포 없이 이 설정을 변경해 즉시 롤아웃하거나 롤백할 수 있습니다. 플랫폼별 기본 채널(예: iOS 전용, Android 전용, Electron 전용)이 있는 경우, 각 기기는 해당 플랫폼에 맞는 기본 채널로 연결됩니다. Cloud default를 설정하지 않아도 되며, 이 경우 기기가 업데이트를 받으려면 1~4단계 조건을 모두 충족해야 합니다.

권장 사항:

1~4단계를 예외/테스트 레이어로 취급하세요. Cloud default를 설정하면 실제 사용자들이 이 채널로 유입됩니다. 설정하지 않기로 했다면, 사용자가 어떻게 연결될지 신중하게 결정해야 합니다(보통 defaultChannel config 또는 기기별 override를 통해).
테스터에게 명시적으로 배포하는 바이너리에서만 defaultChannel 구성하세요. 설정을 비워두면 프로덕션 로직을 대시보드에서 중앙 집중식으로 관리할 수 있습니다.
사용 setChannel() 운영 환경에서는 제한적으로, 주로 QA나 특정 진단 목적으로만 사용하세요.

특정 플랫폼(iOS/Android/Electron 토글)에서 채널이 비활성화된 경우, 선택 대상이더라도 선택 프로세스에서 제외하고 다음 채널로 넘어갑니다.

요약: Force > Dashboard/API Override > Plugin setChannel() 로컬 채널 > Config defaultChannel > Cloud 기본값.

Console 및 API override는 90일 후 만료됩니다

Forced mapping과 Dashboard 또는 Public API 채널 override는 Capgo에 디바이스별 할당으로 저장됩니다. cleanup job이 해당 할당을 삭제합니다. 마지막 오버라이드 쓰기 후 90일. 업데이트 확인(check-in)을 해도 그 기한은 초기화되지 않습니다. override를 다시 작성하거나 직접 삭제해야만 타임스탬프가 바뀝니다.

이는 다음과 다릅니다: 디바이스 인벤토리 보관 주기. Inventory는 90일 동안 Capgo에 연결되지 않은 기기를 삭제합니다. Override cleanup을 사용하면 기기가 활성 상태여도 매핑을 삭제합니다.

이 cleanup 작업으로 삭제되지 않는 할당(assignment)의 경우:

설정 defaultChannel 에서 capacitor.config.* (재설치 후에도 유지되지만, 나중에 변경하려면 새로운 native binary가 필요합니다).
호출하세요 setChannel() 앱에서 삭제됩니다. plugin 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 이상 버전부터 해당 할당은 로컬에 저장되어 이 cleanup으로 삭제되지 않습니다. updater 8.51.0 이상 버전의 Android 및 iOS에서는 persistDefaultChannelOnReinstall 기본값은 true, 따라서 운영 체제가 앱 데이터를 복구할 때만 재설치 후에도 할당이 유지될 수 있습니다. persistDefaultChannelOnReinstall 유지됩니다 true. 사용하세요 unsetChannel() 명시적으로 삭제하려면

채널 기기 탭과 디바이스 Override UI에는 console 및 Public API 할당 내역만 표시됩니다. 채널 내 모든 디바이스나 로컬 setChannel() 할당 내역은 표시되지 않습니다.

Capgo 채널의 Devices 탭에서 Override 보관 기간 팝오버가 표시되는 모습: console override는 90일 후 만료됩니다. — 채널 Devices 탭의 Override 보관 기간 안내.

기본 채널 동작

클라우드 기본값을 설정하는 것은 선택 사항이지만, 보통 새로운 디바이스를 위한 catch-all 경로 역할을 합니다. 기본값이 없으면 강제 매핑, override 또는 defaultChannel Capacitor 설정과 일치하는 디바이스만 업데이트를 받습니다. 기본값을 설정할 때는 다음 패턴을 참고하세요:

단일 기본값 (가장 일반적) – 채널에 iOS, Android, Electron이 활성화되어 있으면 해당 채널이 유일한 기본값이 되며, override가 없는 모든 디바이스는 여기에 연결됩니다.
플랫폼별 기본값 설정 – 플랫폼별로 채널을 분리하는 경우(예를 들어, ios-production iOS만 활성화하거나, android-production Android만 활성화하거나, 또는 electron-production Electron만 활성화하는 경우), 각 플랫폼의 기본값으로 설정하세요. iOS 기기는 iOS 기본값으로, Android 기기는 Android 기본값으로, Electron 앱은 Electron 기본값으로 연결됩니다.

클라우드 기본값과 defaultChannel 에서 capacitor.config.* 플랫폼 기본값은 동일한 결정 계층에 있다는 점을 유의하세요. 클라우드 기본값을 설정했다면 Capacitor 설정에 값을 중복해서 입력할 필요가 없습니다. 프로덕션 빌드 시에는 defaultChannel 비워두세요. 플랫폼 기본값은 defaultChannel 클라우드 기본값과 다르더라도 테스터나 QA용 바이너리가 비프로덕션 채널에서 시작되도록 의도적으로 배포할 때 사용합니다.

대시보드에서 언제든 기본값을 변경할 수 있습니다. 채널을 연 다음, App 설정에서 관리, 이동합니다. 앱 정보. 이제 채널 페이지에서 기본값(default)은 토글 방식이 아닙니다. 기본 채널을 변경하면 새로운 디바이스는 즉시 새로운 라우팅을 따르며, 기존 디바이스는 다음 체크인 시점에 일반적인 우선순위 규칙에 따라 변경 사항을 적용합니다.

Channel 설정하기

onboarding 과정에서 첫 번째 채널(대부분의 팀은 “Production”으로 명명)을 생성하지만, 모든 설정은 자유롭게 변경할 수 있습니다. 언제든 채널 이름을 바꾸거나 삭제할 수 있습니다. 나중에 추가 채널을 만드려면 다음 단계를 따르세요:

Capgo dashboard의 “Channels” 섹션으로 이동합니다.
“New Channel” 버튼을 클릭합니다.
채널 이름을 입력하고 “Create”를 클릭합니다.

채널 이름은 원하는 대로 지정할 수 있습니다. 일반적으로는 다음과 같이 개발 단계에 맞춰 채널을 구성합니다:

Development - 로컬 디바이스나 에뮬레이터에서 Live Update를 테스트할 때
QA - 정식 배포 전 QA 팀에서 업데이트를 검증할 때
Staging - 프로덕션과 유사한 환경에서의 최종 테스트용
Production - 앱 스토어를 통해 사용자가 받는 앱 버전용

앱 내 Channel 설정하기

Channel을 생성했다면, 앱이 적절한 Channel을 수신하도록 설정해야 합니다. 이 예제에서는 Development channel

다음 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, Android 및 Electron 프로젝트로 복사합니다. 이 동기화 단계를 건너뛰면 네이티브 프로젝트는 이전에 설정된 채널을 계속 사용하게 됩니다.

채널 옵션 및 전략

채널에는 업데이트 수신 대상과 전달 방식을 제어하는 여러 옵션이 있습니다. 주요 옵션은 다음과 같습니다. 웹 앱, CLI, 또는 Public API에서 설정할 수 있습니다.

기본 채널: 새 기기가 연결될 채널 또는 플랫폼별 채널을 선택적으로 지정합니다. 콘솔의 App Information 항목에서 설정할 수 있으며 (App 설정에서 관리 채널 페이지에서도 확인 가능합니다). 라우팅 시나리오는 “Default Channel Behavior”를 참조하세요.
플랫폼 필터: 다음 대상에 대한 업데이트 전달을 활성화 또는 비활성화합니다. iOS, Android, 또는 Electron 채널별 기기.
네이티브 환경에서 자동 다운그레이드 방지: 기기의 네이티브 앱 버전이 채널의 bundle보다 최신인 경우 업데이트 전송을 방지합니다 (예: 채널은 1.2.2인데 기기는 1.2.3인 경우).
개발용 빌드 허용: 개발용 빌드에 업데이트를 허용합니다 (테스트 시 유용). CLI: --dev / --no-dev.
프로덕션 빌드 허용: 프로덕션(스토어) 빌드에 업데이트를 허용합니다. 실제 사용자가 이용하는 채널은 이 옵션을 켜두세요. CLI: --prod / --no-prod.
에뮬레이터 기기 허용: 에뮬레이터/시뮬레이터에 업데이트를 허용합니다(테스트 시 유용). CLI: --emulator / --no-emulator.
실제 기기 허용: 실제 스마트폰 및 태블릿에 업데이트를 허용합니다. 프로덕션 채널은 이 옵션을 켜두세요. CLI: --device / --no-device.
기기 자체 할당 허용: 앱이 런타임에 다음을 사용하여 이 채널로 전환할 수 있게 합니다: setChannel. 비활성화 시, setChannel 이 채널에 대한 작업이 실패합니다. CLI: --self-assign / --no-self-assign.
다운로드 형식: 기기가 전체 zip을 다운로드할지, 변경된 delta 파일만 받을지, 또는 두 방식의 장점을 결합한 방식을 사용할지 선택하세요.all, zip, delta, zip_from_builtin, delta_from_builtin"). 규칙은 다운로드 형식 콘솔 드롭다운 및 각 모드의 활용 사례에 대한 설명입니다.

단계적 배포

채널을 사용하면 특정 기기 그룹에 새로운 롤아웃 대상을 점진적으로 노출하면서도 안정적인 번들을 유지할 수 있습니다. 전체 사용자의 채널을 변경하지 않고도 일시 중지, 재개, 승인, 롤백 및 자동 장애 대응 설정을 구성할 수 있습니다. 자세한 내용은 단계적 배포 전달 모델, 대시보드 워크플로우, API 필드 및 CLI 명령어를 참조하세요.

Auto Update 전략 비활성화

채널이 자동으로 전달할 업데이트 종류를 제한할 때 사용합니다. 옵션:

major: 기기의 네이티브 베이스라인보다 메이저 버전이 높은 타겟 번들을 차단합니다 ("version_build"). 예시: 1.2.3 -> 2.0.0 차단됨; 1.2.3 -> 1.9.0 허용됨.
minor: 메이저 또는 마이너 버전이 다음 값과 다른 타겟 번들을 차단합니다: version_build. 예시: 1.2.3 -> 1.3.0 차단됨; 1.2.3 -> 1.2.4 허용됨.
patch: 가장 엄격한 모드입니다. major, minor, patch 버전 번호의 변경을 모두 차단하며, 오직 suffix 변경만 허용합니다. MAJOR.MINOR.PATCH 가 유지되는 동안 1.0.0-beta.1 -> 1.0.0-beta.2 허용됨, 1.0.0+build.1 -> 1.0.0+build.2 허용됨, 1.0.0 -> 1.0.1 차단됨.
metadata: 각 bundle에 최소 업데이트 버전 메타데이터를 요구합니다. CLI를 통해 설정하세요. --min-update-version 또는 --auto-min-update-version설정되지 않은 경우, 채널 설정 오류로 표시되며 설정될 때까지 업데이트가 거부됩니다.
none: 다음 규칙에 따라 모든 업데이트를 허용합니다: semver 호환성.

이 전략은 채널의 대상 번들을 전송된 네이티브 베이스라인과 비교하며, version_build현재 다운로드된 번들과 비교하지 않습니다. version_name.

자세한 내용과 예시는 /docs/cli/commands/#disable-updates-strategy 의 Disable updates strategy 섹션을 참조하세요.

예시 (CLI). 채널은 이미 존재해야 합니다 (channel set 채널을 새로 생성하지는 않습니다):

# 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

# Production channel: store builds on real devices, no emulators
npx @capgo/cli@latest channel set production com.example.app --prod --device --no-emulator

앱에서 setChannel() 사용하기

이 @capgo/capacitor-updater 메서드 setChannel() Android 또는 iOS 앱이 런타임에 프로그래밍 방식으로 채널을 전환할 수 있게 해줍니다. 특히 다음과 같은 경우에 유용합니다:

테스터가 채널을 전환할 수 있는 QA/디버그 메뉴
Beta 프로그램 참여 플로우
Feature flag 구현
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
});

시기 setChannel() 호출 시:

백엔드 검증 (읽기 전용): Capgo 백엔드로 요청을 보내 해당 채널 사용 권한을 검증합니다 (self-assignment 권한 확인)
로컬 스토리지 업데이트: 검증에 성공하면, 해당 채널은 기기의 로컬 스토리지에 다음과 같이 저장됩니다. defaultChannel
즉각적인 효과 적용: 다음 업데이트 확인 시 즉시 새 채널을 사용합니다 (복제 대기 시간 없음)

이것이 중요한 이유: 이전 버전에서는, setChannel() 채널 오버라이드를 백엔드 데이터베이스에 저장했습니다 (Dashboard 또는 API 변경과 동일). 따라서 채널 변경 사항이 적용되기까지 백엔드 복제를 기다려야 했습니다 (최대 2분). 이제는, setChannel() 백엔드에서 (검증을 위해) 읽기만 하고 로컬에 저장하므로 채널 전환이 즉각적입니다.

Dashboard 표시 여부: 플러그인으로 설정한 채널은 Capgo UI의 Device Override 목록에 나타나지 않습니다. Dashboard나 Public API을 통해 생성된 채널 할당만 여기에 표시됩니다. 관리자에게 보이는 오버라이드가 필요한 경우 Dashboard나 API를 사용하세요.

보안 참고 사항: 로컬에 설정된 후 채널 권한이 변경되더라도 (예: 셀프 할당 비활성화), 업데이트 확인 시 백엔드에서 채널을 검증하므로 보안이 유지됩니다.

채널 변경 방식 비교:

메서드	효과 적용 시간	저장 위치	기기 Override UI 표시 여부	만료 시간	사용 사례
`setChannel()` 플러그인에서	즉시	기기 전용 (로컬)	아니요	자동 만료 없음; 다음 시 삭제 `unsetChannel()` (재설치 시 유지될 수 있음)	앱 내 사용자 주도 채널 전환
대시보드 기기 오버라이드	최대 2분	백엔드 데이터베이스	지원	마지막 오버라이드 기록 후 90일	특정 기기에 대한 관리자 주도 변경
API 채널 할당	최대 2분	백엔드 데이터베이스	지원	마지막 오버라이드 기록 후 90일	자동화된 백엔드 통합

채널 전환 UI를 구축할 때 최상의 사용자 경험을 제공하려면 항상 플러그인의 setChannel() 메서드를 사용하세요.

로컬 전용 채널 전환을 위한 최소 버전: 5.34.0, 6.34.0, 7.34.0, 또는 8.0.0 (메이저 버전에 따라 다름). 각 마이너 버전 번호는 모든 메이저 버전에 대해 동일한 기능 세트에 해당합니다 (예: X가 5, 6, 7, 8 중 무엇이든 X.34.0은 동일한 기능을 포함함). 버전 태그는 plugin 설치 를 참조하세요.

채널에 Bundle 할당하기

live update를 배포하려면 새로운 JS bundle 빌드를 upload하고 채널에 할당해야 합니다. Capgo CLI를 사용하면 이 과정을 한 번에 처리할 수 있습니다:

npx @capgo/cli@latest bundle upload --channel=Development

빌드된 웹 에셋을 upload하고, 해당 channel의 활성 build로 새 bundle을 설정합니다. Development 해당 channel을 구독하도록 설정된 모든 앱은 다음 업데이트 확인 시 업데이트를 받게 됩니다.

Capgo dashboard의 “Bundles” 섹션에서도 build를 channel에 할당할 수 있습니다. build 옆의 메뉴 아이콘을 클릭하고 “Assign to Channel”을 선택하여 해당 build의 channel을 지정하세요.

Bundle 버전 관리와 Channel

Capgo의 bundle은 개별 channel에 종속되지 않고 앱 전체에 적용되는 global 단위라는 점에 유의하세요. 동일한 bundle을 여러 channel에 할당할 수 있습니다.

bundle 버전을 관리할 때는 다음 방식을 권장합니다. Capgo의 Semver Tester를 활용한 semantic versioning과 channel별 build를 위한 pre-release identifier를 사용하세요. 예를 들어, beta release의 버전은 다음과 같을 수 있습니다. 1.2.3-beta.1.

CI 환경에서 로컬 버전이 이미 upload된 경우, 다음을 사용하세요. npx @capgo/cli@latest bundle upload --auto-bump (선택 사항 major, minor, patch/fix, metadata, 또는 ai) 따라서 자유로운 이름이 발견될 때까지 채널에 연결된 번들에서 CLI를 순차적으로 탐색합니다. ai, Workers AI는 로컬과 이전 델타 매니페스트 간의 차이를 통해 레벨을 추론합니다(이전 patch Capgo 버전이 없는 경우로 대체됨). 이는 다음을 조합할 수 없습니다: --bundle. 참조 CI/CD 통합 및 CLI 참조.

이 방식은 다음과 같은 장점이 있습니다:

빌드 간의 관계를 명확하게 전달합니다. 1.2.3-beta.1 는 명백히 다음의 프리릴리스 버전입니다: 1.2.3.
채널 간에 버전 번호를 재사용할 수 있어 혼란을 줄여줍니다.
이를 통해 명확한 롤백 경로를 확보할 수 있습니다. 만약 1.2.3에서 롤백이 필요하다면, 1.2.2 이 바로 이전의 안정적인 릴리스입니다.

다음은 일반적인 채널 설정에 맞춰 번들 버전을 맞추는 예시입니다:

Development 채널: 1.2.3-dev.1, 1.2.3-dev.2등의 에셋을 첨부합니다.
QA 채널: 1.2.3-qa.1, 1.2.3-qa.2등의 에셋을 첨부합니다.
Staging 채널: 1.2.3-rc.1, 1.2.3-rc.2등의 에셋을 첨부합니다.
Production 채널: 1.2.3, 1.2.4등의 에셋을 첨부합니다.

사용하기 pre-release 식별자를 포함한 semver 권장되는 방식이지만 필수 사항은 아닙니다. 핵심은 빌드 간의 관계를 명확히 전달하고 팀의 개발 프로세스와 일치하는 버전 관리 체계를 찾는 것입니다.

Live Update 롤백하기

버그가 포함된 live update를 배포했거나 이전 상태로 되돌려야 하는 경우, 이전 빌드로 쉽게 롤백할 수 있습니다. 대시보드의 “Channels” 섹션에서 다음을 수행하세요:

롤백하려는 채널의 이름을 클릭합니다
되돌리려는 빌드를 찾아 왕관 아이콘을 클릭합니다
작업 확인

선택한 빌드가 해당 채널의 활성 빌드로 즉시 다시 설정됩니다. 앱은 다음 업데이트 확인 시 롤백된 버전을 받게 됩니다.

배포 자동화

더 고도화된 워크플로우를 위해 CI/CD 파이프라인의 일부로 live update 배포를 자동화할 수 있습니다. 빌드 프로세스에 Capgo를 통합하면, 특정 브랜치에 푸시하거나 새로운 릴리스를 생성할 때마다 새로운 번들을 자동으로 업로드하고 채널에 할당할 수 있습니다.

자세한 내용은 CI/CD 통합 문서를 참조하여 Capgo live updates 자동화에 대해 알아보세요.

최소 권한 PR 프리뷰

Use an 앱 미리보기 API 키를 사용하세요. 이 키는 소유 조직 및 선택된 앱에 귀속되며, 조직 전체에 영향을 미치는 역할은 갖지 않습니다. 생성된 각 비공개 프리뷰 채널은 채널 범위 내에서 자체적인 자동 라이프사이클 권한을 부여받습니다.

조직 관리자에게 프리뷰 앱으로 권한이 제한된 보안 API 키를 생성하고 다음을 선택하도록 요청하세요. 앱 미리보기. 참조 API 키.
다음과 같은 고유한 비공개 채널을 사용하세요: pr-123. 다음을 전달하지 마세요: --default, --self-assign롤아웃 옵션이나 --delete-linked-bundle-on-upload.
한 번의 명령으로 PR 번들을 upload하고 promote한 뒤, PR이 닫히면 소유한 채널과 번들을 삭제하세요:

APP_ID="com.example.app"
PREVIEW_CHANNEL="pr-123"
BUNDLE_VERSION="1.2.3-pr.123"

npx @capgo/cli@latest bundle upload "$APP_ID" \
  --apikey "$CAPGO_PREVIEW_KEY" \
  --path ./dist \
  --channel "$PREVIEW_CHANNEL" \
  --bundle "$BUNDLE_VERSION"

npx @capgo/cli@latest channel delete "$PREVIEW_CHANNEL" "$APP_ID" \
  --apikey "$CAPGO_PREVIEW_KEY" \
  --delete-bundle \
  --success-if-not-found

bundle upload --channel 없는 채널을 생성하고 번들을 upload한 뒤 한 번의 흐름으로 promote합니다. 정리 작업은 원자적이며 소유권 검사를 거칩니다. 즉, 키는 자신이 생성한 채널과 연결된 비공유 번들만 삭제할 수 있습니다. 기존 main/default 채널, 다른 preview 키의 채널, 다른 키의 번들은 변경하거나 promote하거나 삭제할 수 없습니다.

리뷰어에게 QR code 또는 미리보기 URL이 필요한 경우, 관리자가 앱에 대해 미리보기를 한 번 활성화해야 합니다:

npx @capgo/cli@latest app set "$APP_ID" --preview
npx @capgo/cli@latest get-qr "$APP_ID" --channel "$PREVIEW_CHANNEL" --apikey "$CAPGO_PREVIEW_KEY" --url

App Preview 키는 app-settings 권한이 없으므로 스스로 프리뷰를 활성화할 수 없습니다. GitHub Actions에서 시크릿을 사용하는 프리뷰 작업을 실행하고, pull_request, 아니라 pull_request_target동일 저장소의 PR로만 제한하세요. github.event.pull_request.head.repo.full_name == github.repository.

기기에 배포하기

이제 채널을 이해했으니, 실제 기기에 라이브 업데이트를 배포할 준비가 되었습니다. 기본 프로세스는 다음과 같습니다:

앱에 Capgo SDK 설치
원하는 채널을 수신하도록 앱 설정
빌드를 업로드하고 해당 채널에 할당
앱을 실행하고 업데이트를 기다리세요!

더 자세한 단계별 가이드는 다음을 참조하세요: Live Updates 배포하기 가이드. 즐거운 업데이트 하세요!

고급 Channel 활용: 사용자 세그먼트

채널은 개발 단계에만 쓰이는 게 아닙니다. 다음과 같은 기능을 가능하게 하는 강력한 사용자 세그먼테이션 도구입니다:

사용자 등급별 기능 플래그
A/B 테스트
점진적 기능 롤아웃
베타 테스트 프로그램

이러한 고급 활용 사례를 구현하는 방법은 가이드에서 확인하세요: 기능 플래그와 A/B 테스트를 위한 요금제·채널별 사용자 세그먼테이션 방법.

Channels에서 계속하기

사용 중이라면 채널 채널 라우팅과 단계적 배포를 계획하려면, 다음을 연결하세요: 채널 Channels의 구현 세부 사항은 다음을 참고하세요: 채널 Channels의 구현 세부 사항은 다음을 참고하세요: Beta Testing 솔루션 Beta Testing Solution의 제품 워크플로우를 위해, 버전 타겟팅 솔루션 Version Targeting Solution의 제품 워크플로우를 위해, Capgo 환경 베스트 프랙티스: 하나의 Mobile App ID로 스테이징하기 Capgo 환경 베스트 프랙티스: 하나의 모바일 앱 ID로 스테이징 구성하기의 실무 사례를 위해.