채널

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

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

Channels 실제 활용

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

1. 기본 채널 사용하기

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

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

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

2. 디바이스가 채널을 선택하게 하기

이 가이드에서는 다음을 사용합니다: 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(). 이 로컬 설정은 콘솔 설정을 덮어쓰지 않습니다. 업데이트 버전 8.51.0 이상의 Android 및 iOS에서는, persistDefaultChannelOnReinstall 기본값은 true이므로, OS가 앱 데이터를 복구하고 persistDefaultChannelOnReinstall 남음 true. 호출하여 unsetChannel() 로컬 설정을 초기화할 수 있습니다. 콘솔 및 API 오버라이드는 여전히 아래 우선순위를 따릅니다.

3. 콘솔에서 기기 1대 할당하기

Capgo 콘솔에서, 앱 앱을 선택하고, 디바이스 기기를 선택한 뒤, 해당 기기의 Channel override를 변경하세요. 로 devCapgo는 이제 해당 기기를 dev로 라우팅하며, 앱의 클라우드 기본값은 production.

콘솔 기기 override 영상 다운로드 (MP4).

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

지금 바로 시작해 보세요 Console에서 채널 생성하기, 그런 다음 bundle 업로드 제공하기 위해.

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

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

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

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

이전에는, setChannel() 채널 오버라이드를 백엔드 데이터베이스(Dashboard 또는 API 변경처럼)에 저장했기 때문에, 기기에서는 새 채널이 인식되기까지 데이터 복제(최대 2분)를 기다려야 했습니다. 새 방식은 백엔드에서 (검증용으로) 읽기만 하고 로컬에 저장하므로 채널 전환이 즉시 이루어집니다.

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

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

중요: Dashboard 또는 API를 통해 채널을 변경하면, 모든 edge 서버에 변경 사항이 반영되기까지 여전히 최대 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 overrides는 90일 후 만료됩니다

Forced mapping 및 Dashboard 또는 Public API 채널 override는 Capgo에 디바이스별 할당으로 저장됩니다. 클린업 작업은 다음 시점에 해당 할당을 삭제합니다. 마지막 override 기록 후 90일이 경과했을 때. 업데이트 확인을 해도 타이머는 초기화되지 않습니다. override를 다시 기록하거나 직접 삭제해야만 타임스탬프가 변경됩니다.

이는 다음 항목과 다릅니다: 디바이스 인벤토리 보존. 인벤토리는 90일 동안 Capgo에 연결되지 않은 디바이스를 삭제합니다. 반면 override 클린업은 디바이스가 여전히 활성 상태여도 매핑을 삭제합니다.

이 정리 작업으로 삭제되지 않는 할당의 경우:

설정 defaultChannel 에서 capacitor.config.* (재설치 후에도 유지되지만, 나중에 변경하려면 새로운 Native Build가 필요합니다).
앱에서 setChannel() 를 호출하세요. 플러그인 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 이상 버전부터 해당 할당은 로컬에 저장되어 이 정리 작업으로 삭제되지 않습니다. 업데이트 버전 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 settings에서 Manage를 선택하면 앱 정보으로 이동합니다. 이제 채널 페이지에서 기본값은 토글이 아닙니다. 기본값을 바꾸면 새 기기는 즉시 새 라우팅을 따르고, 기존 기기는 다음 체크인 때 일반 우선순위 규칙을 따릅니다.

채널 설정하기

온보딩 과정에서 첫 번째 채널(대부분의 팀은 “Production”으로 명명)을 생성하지만, 고정된 것은 없습니다. 언제든 채널 이름을 변경하거나 삭제할 수 있습니다. 나중에 추가 채널을 만드려면 다음 단계를 따르세요:

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

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

Development - 로컬 기기나 에뮬레이터에서 Live Update를 테스트할 때
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, Android, Electron 프로젝트로 복사하세요. 이 동기화 단계를 건너뛰면 네이티브 프로젝트는 이전에 설정된 채널을 계속 사용하게 됩니다.

채널 옵션 및 전략

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

기본 채널: 새 기기가 연결될 채널 또는 플랫폼별 채널을 선택적으로 지정합니다. 콘솔의 App Information 항목에서 설정할 수 있으며 (App settings에서 Manage 채널 페이지에서도 확인 가능합니다). 라우팅 시나리오는 “Default Channel Behavior”를 참조하세요.
플랫폼 필터: 다음 대상에 대한 업데이트 전달을 활성화하거나 비활성화합니다. iOS, Android, 또는 Electron 채널별 기기.
Native Build 시 자동 다운그레이드 방지: 기기의 Native Build 버전이 채널의 bundle보다 최신인 경우 업데이트 전송을 방지합니다 (예: 기기는 1.2.3 버전인데 채널은 1.2.2 버전인 경우).
Development Build 허용: 개발용 build에 업데이트를 허용합니다 (테스트 시 유용). CLI: --dev / --no-dev.
Production 빌드 허용: 프로덕션(스토어) 빌드에 업데이트를 허용합니다. 실제 사용자가 이용하는 채널은 이 옵션을 켜두세요. 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: 기기의 네이티브 베이스라인보다 major 버전이 높은 타겟 번들을 차단합니다 (version_build). 예시: 1.2.3 -> 2.0.0 차단됨; 1.2.3 -> 1.9.0 허용됨.
minor: major 또는 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에 최소 업데이트 버전 metadata를 요구합니다. CLI에서 다음을 통해 설정하세요: --min-update-version 또는 --auto-min-update-version. 설정이 누락되면 채널 구성 오류로 표시되며, 설정 전까지 업데이트가 거부됩니다.
none: 다음 기준에 따라 모든 업데이트를 허용합니다: semver 호환성.

이 전략은 채널의 대상 bundle을 native baseline과 비교하며, 이 baseline은 다음과 같이 전송됩니다 version_build, 현재 다운로드된 bundle과는 비교하지 않습니다. 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/디버그 메뉴
베타 프로그램 옵트인 플로우
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() method를 사용하세요.

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

채널에 Bundle 할당하기

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

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

This will upload your built web assets and set the new bundle as the active build for the Development 해당 채널을 구독하도록 설정된 모든 앱은 다음 업데이트 확인 시 업데이트를 받게 됩니다.

Capgo 대시보드의 “Bundles” 섹션에서도 빌드를 채널에 할당할 수 있습니다. 빌드 옆의 메뉴 아이콘을 클릭하고 “Assign to Channel”을 선택하여 해당 빌드에 사용할 채널을 지정하세요.

Bundle 버전 관리 및 채널

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

번들 버전을 관리할 때는 다음 방식을 권장합니다. Capgo의 Semver Tester를 활용한 semantic versioning과 채널별 빌드를 위한 pre-release 식별자 사용을 권장합니다. 예를 들어, 베타 릴리스는 다음과 같이 버전을 지정할 수 있습니다. 1.2.3-beta.1.

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

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

빌드 간의 관계를 명확하게 보여줍니다. 1.2.3-beta.1 is obviously a pre-release of 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 라이브 업데이트 자동화 방법을 확인하세요.

최소 권한 PR 프리뷰

다음을 사용하세요: 앱 미리보기 CI에서 풀 리퀘스트마다 임시 채널 하나가 필요하지만 기존 main/default 채널은 관리하면 안 될 때 API 키를 사용하세요. 이 키는 소유 조직과 선택한 앱에 바인딩되며, 조직 전체 범위의 역할은 갖지 않습니다. 이 키가 만드는 각 비공개 프리뷰 채널에는 채널 범위의 자동 라이프사이클 권한이 부여됩니다.

조직 관리자가 프리뷰 앱에만 한정된 보안 API 키를 생성하고 다음을 선택하도록 하세요: 앱 미리보기. 보기 API 키.
다음과 같은 고유한 비공개 채널을 사용하세요: pr-123. 다음을 전달하지 마세요: --default, --self-assign, 롤아웃 옵션 또는 --delete-linked-bundle-on-upload.
명령 하나로 PR 번들을 업로드하고 프로모션한 다음, 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 없는 채널을 생성하고 번들을 업로드한 뒤 프로모션하는 과정을 한 번에 처리합니다. 정리 작업은 원자적(atomic)이며 소유권 검사를 거칩니다. 즉, 해당 키는 자신이 생성한 채널과 그에 연결된 공유되지 않은 번들만 삭제할 수 있습니다. 기존 메인/기본 채널, 다른 프리뷰 키의 채널, 다른 키의 번들은 변경하거나 프로모션하거나 삭제할 수 없습니다.

리뷰어에게 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 키는 앱 설정 권한이 없으므로 직접 프리뷰를 활성화할 수 없습니다. GitHub Actions에서는 시크릿을 포함하는 프리뷰 작업을 다음에서 실행하세요: pull_request을 사용하세요, pull_request_target, 그리고 동일 저장소의 PR로 제한합니다. github.event.pull_request.head.repo.full_name == github.repository.

기기에 배포하기

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

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

더 자세한 단계별 안내는 다음을 참조하세요: Live Updates 배포하기 가이드를 확인해 보세요. 즐거운 업데이트 되시길 바랍니다!

고급 채널 활용: 사용자 세그먼테이션

채널은 단순히 개발 단계 구분용으로만 쓰이지 않습니다. 다음과 같은 기능을 지원하는 강력한 사용자 세그먼테이션 도구입니다:

사용자 등급별 기능 플래그(Feature flags)
A/B 테스트
단계적 기능 출시(Gradual rollouts)
베타 테스트 프로그램

가이드를 통해 이러한 고급 활용 사례를 구현하는 방법을 알아보세요: 기능 플래그 및 A/B 테스트를 위한 플랜 및 채널별 사용자 세그먼테이션 방법.

채널에서 계속 진행하기

사용 중인 경우 채널 채널 라우팅과 단계적 롤아웃을 계획하려면, 이를 다음 항목과 연결하세요 채널 Channels의 구현 세부 사항은, 채널 Channels의 구현 세부 사항은, Beta Testing 솔루션 Beta Testing Solution의 제품 워크플로우를 위해, Version Targeting 솔루션 Version Targeting Solution의 제품 워크플로우를 위해, 그리고 Capgo 환경 베스트 프랙티스: 하나의 Mobile App ID로 Staging 환경 구성 Capgo 환경 베스트 프랙티스: 하나의 Mobile App ID로 Staging 환경 구성의 실무 맥락을 위해.