채널

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

A Live Update channel points to a specific JS bundle build of your app that will be shared with any devices configured to listen to that channel for updates. When you install the Capgo Live Updates SDK in your app, any native binary configured to that channel will check for available updates whenever the app is launched. You can change the build a channel points to at any time and can also roll back to previous builds if needed.

장치가 채널을 선택하는 순서 (우선순위)

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

Forced device mapping (Dashboard) – 특정 기기 ID를 채널에 수동으로 고정합니다. 긴급 디버깅이나 단일 실제 사용자와 제어된 테스트에 사용합니다. 항상 우선합니다.
Cloud override (per‑device) via Dashboard or API – 대시보드나 API를 통해 기기의 채널을 변경할 때 생성됩니다. QA 사용자가 기능/PR 채널 사이를 전환하거나 사용자 문제를 재현할 때 사용합니다. 바이너리 재설치로 지워지지 않으며 기기 항목 삭제로 지워집니다.
Plugin setChannel() local channel – 앱이 호출할 때 생성됩니다. setChannel() and 백엔드가 대상 채널이 자체 할당을 허용하는지 검증합니다. 선택한 채널은 즉시 적용되고 기기 override UI에 표시되지 않습니다.

Plugin 버전 5.34.0, 6.34.0, 7.34.0, 또는 8.0.0부터 시작하여 (대부분의 경우) setChannel() , 허용된 채널인지 확인 (자신의 할당이 해당 채널에 대해 활성화되어 있는지 확인)하고, 그 채널을 장치에 저장합니다. 이것은 새로운 채널이 즉시 다음 업데이트 체크부터 적용되기 때문에 기다리지 않습니다. defaultChannel이전에는 백엔드 데이터베이스 (예: 대시보드 또는 __CAPGO_KEEP_0__ 변경)로 채널 오버라이드 저장하고, 장치들은 데이터 복제가 완료될 때까지 (2분까지) 새로운 채널이 인식되기까지 기다려야 했습니다. 새로운 동작은 백엔드에서만 읽어 (유효성 검사)하고, 장치에 저장하기 때문에 채널 Switch가 즉시 적용됩니다. 로컬 전용이기 때문에

이는 setChannel() saved the channel override to the backend database (like Dashboard or API changes), and devices had to wait for data replication (up to 2 minutes) before the new channel was recognized. The new behavior only reads from the backend (for validation) and stores locally, making channel switches instant.

이는 setChannel() 백엔드에서만 읽어 (유효성 검사)하고, 장치에 저장하기 때문에 채널 Switch가 즉시 적용됩니다. 이는 Capgo에서 장치 오버라이드 항목을 생성하세요. 장치 오버라이드 UI에서는 Capgo 또는 Public API에서 생성된 오버라이드만 표시됩니다.

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

중요: 채널 변경이 Dashboard 또는 API에서 이루어질 경우, 모든 에지 서버가 변경을 반영하기까지 최대 2분의 지연이 발생합니다. 즉시 채널-switching을 원한다면 setChannel() 앱 code에서 채널을 변경하세요—it은 백엔드와 검증을 하며, 그 후 로컬에서 채널을 설정하여 즉시 효과를 낼 수 있습니다.

Capacitor 설정 defaultChannel (테스트 빌드 기본값) – 만약에 __CAPGO_KEEP_0__이 존재하고, force/override/local 채널이 없다면, 앱은 이 채널에서 시작됩니다 (예를 들어, capacitor.config.* ). 테스트 플라이트 / 내부 빌드에 사용하여 테스터가 자동으로 프리-리리즈 채널에 도착하도록 하세요. 프로덕션 빌드는 일반적으로 이 설정을 비워둡니다. beta, qa, pr-123클라우드 기본 채널 (주요 경로 ~99%의 사용자)
__CAPGO_KEEP_1__ – 만약에 대시보드에서 기본 채널을 표시하면, 모든 일반 사용자 (강제, 대시보드/API override, 플러그인 로컬 채널, config defaultChannel 제외)는 여기에 연결됩니다. 이 채널을 출시 또는 롤백으로 즉시 변경할 수 있습니다. 새로운 바이너리가 없습니다. 플랫폼에 따라 기본값이 있는 경우 (예를 들어 iOS 전용, Android 전용, Electron 전용), 각 기기는 해당 플랫폼에 맞는 기본값으로 연결됩니다. 클라우드 기본값을 비워두는 것은 허용되며, 그 경우 기기는 1-4 단계를 통해 업데이트를 받습니다.

Best practice:

1-4을 예외/테스트層으로 간주하십시오. 클라우드 기본값을 설정하면 실제 사용자는 이 채널로 흐릅니다. 기본값을 설정하지 않으면, 사용자가 연결하는 방법에 대해 명확하게 결정하십시오 (일반적으로 config 또는 per-device override를 통해). defaultChannel Only configure
production에서 사용하는 바이너리에서만 설정하십시오. 기본값을 비워두면, 프로덕션 로직은 중앙에서 대시보드에서 관리됩니다. defaultChannel Use
production에서 sparingly 사용하십시오—QA 또는 대상 진단에만 사용하십시오. setChannel() 대시보드에서 플랫폼 (iOS/Android/Electron)으로 채널이 비활성화된 경우, 선택 프로세스는 해당 채널을 건너뛰고 목록을 계속 진행합니다.

Summary: Force > Dashboard/__CAPGO_KEEP_0__ Override > Plugin

Summary: Force > Dashboard/API Override > Plugin setChannel() > Cloud Default. defaultChannel Best practice:

기본 채널 동작

클라우드 기본 설정은 선택 사항이지만, 새로운 장치의 기본 경로로 사용됩니다. 기본 설정이 없으면, 강제 매핑, 오버라이드, 또는 defaultChannel Capacitor 설정에 명시된 것만 업데이트를 받습니다. 기본 설정을 지정할 때 다음 패턴을 기억하세요:

단일 기본 설정(가장 일반적인 경우) – iOS, Android, Electron이 모두 활성화된 채널이 단일 기본 설정이 됩니다. 오버라이드가 없는 장치들은 이 채널에 연결됩니다.
플랫폼별 기본 설정 – 플랫폼별 채널을 나누어(예를 들어, ios-production iOS만 활성화된 채널, android-production Android만 활성화된 채널, electron-production Electron만 활성화된 채널), 각 채널을 플랫폼별 기본 설정으로 지정하세요. iOS 장치들은 iOS 기본 설정으로, Android 장치들은 Android 기본 설정으로, Electron 앱들은 Electron 기본 설정으로 연결됩니다.

클라우드 기본 설정과 defaultChannel In __CAPGO_KEEP_0__에서 cloud 기본값을 설정하면, __CAPGO_KEEP_0__ config에서 값을 중복해서 입력할 필요가 없습니다. capacitor.config.* 생산 빌드용으로 빈칸을 남겨두세요. 테스터나 QA에게 배포할 바이너리용으로는 Capacitor 채널을 비프로덕션 채널로 시작하도록 하세요. defaultChannel __CAPGO_KEEP_0__에서 기본값을 변경할 수 있습니다. 기본값을 바꾸면 새로운 기기들은 즉시 새로운 라우팅을 따르며 기존 기기는 다음에 체크인할 때 정상적인 우선순위를 따릅니다. defaultChannel 채널 설정

__CAPGO_KEEP_0__에서 채널 설정

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

새 채널 버튼을 클릭하세요.

Go to the “Channels” section of the Capgo dashboard
채널 이름은 자유롭게 지정할 수 있습니다. 일반적인 전략은 개발 단계와 채널 이름을 일치시키는 것입니다.
생산, 개발, 테스트, 배포 등

__CAPGO_KEEP_0__

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

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

채널을 생성한 후, 앱을 구성하여 해당 채널을 듣도록 해야 합니다. 이 예에서는 채널을 사용하겠습니다. Development channel.

파일을 열어보세요. capacitor.config.ts (또는 capacitor.config.json) 파일. plugins 섹션 하위에, 옵션적으로 defaultChannel 테스트 빌드 생산 빌드의 경우 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.
    },
  },
};

업데이트된 config 파일을 iOS, Android, Electron 프로젝트로 복사하세요. 이 동기화 단계를 건너뛰면 이전에 구성된 채널을 계속 사용합니다. npx cap sync 주의

__CAPGO_KEEP_0에서 또는 Public CAPGO_KEEP_1__에서 웹 앱을 통해 설정할 수 있는 채널 옵션과 전략입니다.

CLI에서 또는 Public API에서 웹 앱을 통해 설정할 수 있는 채널 옵션과 전략입니다.

__CAPGO_KEEP_0__에서 또는 Public __CAPGO_KEEP_1__에서 웹 앱을 통해 설정할 수 있는 채널 옵션과 전략입니다.
__CAPGO_KEEP_0__에서 또는 Public __CAPGO_KEEP_1__에서 웹 앱을 통해 설정할 수 있는 채널 옵션과 전략입니다. iOS, Android__CAPGO_KEEP_0__에서 또는 Public __CAPGO_KEEP_1__에서 웹 앱을 통해 설정할 수 있는 채널 옵션과 전략입니다. Electron __CAPGO_KEEP_0__에서 또는 Public __CAPGO_KEEP_1__에서 웹 앱을 통해 설정할 수 있는 채널 옵션과 전략입니다.
__CAPGO_KEEP_0__에서 또는 Public __CAPGO_KEEP_1__에서 웹 앱을 통해 설정할 수 있는 채널 옵션과 전략입니다.
__CAPGO_KEEP_0__에서 또는 Public __CAPGO_KEEP_1__에서 웹 앱을 통해 설정할 수 있는 채널 옵션과 전략입니다.
Allow emulator devices: emulator 장치에 대한 업데이트를 허용 (테스트에 유용함).
Allow device self‑assignment: 앱이 런타임에 이 채널로 switch 할 수 있도록 함. setChannel If disabled, setChannel will fail for this channel.

Progressive rollouts

채널은 안정적인 번들을 유지하면서 stickily attached device cohort에 대한 별도의 rollout target를 점진적으로 노출할 수 있습니다. 채널을 전부 switch하지 않고도 pause, resume, promote, roll back, 자동 실패 응답을 구성할 수 있습니다. Progressive rollouts for the delivery model, dashboard workflow, API fields, and CLI commands.

Disable Auto Update strategies

options

주요 버전: 기기 기본 라인 밑에 있는 대상 번들의 주요 버전보다 높은 버전을 차단합니다 (version_build). 예시: 1.2.3 -> 2.0.0 차단; 1.2.3 -> 1.9.0 허용.
소수점 버전: 대상 번들의 주요 또는 소수점 버전이 version_build와 다르면 차단합니다. 예시: 1.2.3 -> 1.3.0 차단; 1.2.3 -> 1.2.4 허용.
패치: 가장 엄격한 모드입니다. 주요, 소수점, 또는 패치 번호의 변경은 모두 차단합니다. 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: 각 번들을 위한 최소 업데이트 버전 메타데이터가 필요합니다. CLI을 사용하여 구성하십시오. --min-update-version 또는 --auto-min-update-version. 만약 누락되면 채널은 오류로 간주되어 업데이트가 거부될 것입니다.
none: 모든 업데이트를 __CAPGO_KEEP_0__ 호환성에 따라 허용하십시오. 이러한 전략은 채널의 목표 번들을 원시 기준선과 비교합니다. __CAPGO_KEEP_0__으로 전달된 것과는 달리, __CAPGO_KEEP_0__으로 전달된 현재 다운로드된 번들을 비교하지 않습니다..

Disable updates strategy에 대한 자세한 내용과 예제는 /docs/__CAPGO_KEEP_0__/commands/#disable-updates-strategy에서 확인하십시오. version_build예(__CAPGO_KEEP_0__): version_name.

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

Example (CLI):

# 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

Your 앱에서 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
});

언제 setChannel() 이것이란:

백엔드 유효성 검사 (읽기 전용): Capgo 백엔드에 요청을 보내 채널이 허용되는지 유효성 검사를 하며 (자기 할당 권한 확인)
로컬 스토리지 업데이트: 유효성 검사가 통과되면, 채널은 장치의 로컬 스토리지에 저장된다. defaultChannel
즉시 효과: 다음 업데이트 체크는 새로운 채널을 즉시 사용한다 (대기 시간이 없음)

왜 이것이 중요합니까: 오래된 버전에서 setChannel() 채널 오버라이드가 백엔드 데이터베이스에 저장되었으며 (같은 Dashboard 또는 API 변경과 동일). 장치들은 백엔드 복제가 완료될 때까지 (2분 이내) 채널 변경이 유효해지기까지 기다려야했다. 이제 setChannel() 백엔드에서만 읽고 로컬 스토리지에만 저장하여 채널 Switch가 즉시 작동한다.

대시보드 가시성: Capgo에서 플러그인을 설정한 채널은 장치 오버라이드로 나타나지 않습니다. 채널 assignments은 API 또는 API에서만 생성한 것만 목록에 표시됩니다. 대시보드나 API를 사용하여 관리자가 볼 수 있는 오버라이드를 필요로 할 때 사용하세요.

보안 주의: 채널의 권한이 로컬에서 변경되어도(예: 자체 할당이 비활성화된 경우), 백엔드는 업데이트 확인 시 채널을 검증하여 보안을 유지합니다.

채널 변경 방법 비교:

방법	효과 시간	저장 위치	장치 오버라이드 UI에 표시	사용 사례
`setChannel()` 플러그인	즉시	장치만(로컬)	아니요	__CAPGO_KEEP_0__ 앱 내 채널 전환
디바이스 오버라이드	2분 이내	백엔드 데이터베이스	예	관리자 지정 디바이스 변경
API 채널 assignments	2분 이내	백엔드 데이터베이스	예	자동화된 백엔드 통합

사용자 경험을 최적화하기 위해 채널-switching UI를 구축할 때는 항상 플러그인의 setChannel() 메서드를 사용하세요.

지역 전용 채널 switching을 위한 최소 버전: 5.34.0, 6.34.0, 7.34.0, 또는 8.0.0 (대부분 버전에 따라 달라집니다). 각 부서 버전 번호는 모든 주요 버전에서 동일한 기능 집합을 나타냅니다 (예: X.34.0은 X가 5, 6, 7, 또는 8이면 동일한 기능을 포함합니다). 버전 태그를 위한 플러그인 설치 채널에 번들을 할당하는 방법

라이브 업데이트 배포를 위해, 새로운 JS 번들을 업로드하고 채널에 할당해야 합니다. 이 작업은 단일 단계로 수행할 수 있습니다.

To deploy a live update, you need to upload a new JS bundle build and assign it to a channel. You can do this in one step with the 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 __CAPGO_KEEP_0__. Development channel. Any apps configured to listen to that channel will receive the update the next time they check for one.

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

__CAPGO_KEEP_0__ 버전 관리 및 채널

It’s important to note that bundles in Capgo are global to your app, not specific to individual channels. The same bundle can be assigned to multiple channels.

When versioning your bundles, we recommend using semantic versioning with __CAPGO_KEEP_0__’s Semver Tester and pre-release identifiers for channel-specific builds. For example, a beta release might be versioned as __CAPGO_KEEP_0__. semantic versioning with Capgo’s Semver Tester It clearly communicates the relationship between builds. 1.2.3-beta.1.

is obviously a pre-release of __CAPGO_KEEP_0__.

__CAPGO_KEEP_0__의 버전 관리는 앱의 모든 채널에 적용됩니다. 동일한 버전이 여러 채널에 assign 될 수 있습니다. 1.2.3-beta.1 __CAPGO_KEEP_0__ 버전 관리를 사용할 때는 semantic versioning과 pre-release identifier를 사용하는 것을 추천합니다. 예를 들어, 베타 버전은 __CAPGO_KEEP_0__으로 versioning 될 수 있습니다. 1.2.3.
It allows for reusing version numbers across channels, reducing confusion.
It enables clear rollback paths. If you need to roll back from 1.2.3, you know 1.2.2 is the previous stable release.

Here’s an example of how you might align your bundle versions with a typical channel setup:

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

Using pre-release 식별자와 함께 semver 사용하는 것은 권장되는 방법이지만, 엄격히 필요하지는 않습니다. 버전 관리 방식은 팀의 개발 프로세스와 일치하는지 명확하게 전달하는 버전 관리 방식이 무엇인지 찾는 것이 중요합니다. 실시간 업데이트 롤백

실시간 업데이트 롤백

롤백할 채널의 이름을 클릭합니다.

롤백할 빌드를 찾고 crown 아이콘을 클릭합니다.
롤백 빌드
선택한 빌드는 즉시 해당 채널의 활성 빌드로 다시 설정됩니다. 앱은 업데이트를 확인할 때 다음 버전으로 업데이트됩니다.

Section titled “Rolling Back a Live Update”

배포 자동화

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

CI/CD 통합 __CAPGO_KEEP_0__ 라이브 업데이트 자동화에 대한 자세한 내용은 docs to learn more about automating Capgo live updates.

권한 제한 미리보기 섹션

조직 관리자가 미리보기 앱에 제한된 __CAPGO_KEEP_0__ 키를 생성하세요. __CAPGO_KEEP_0__ 키를 사용하여 CI가 임시 채널을 한 번에 하나씩 필요하지만 기존의 main/default 채널을 관리하지 않도록 API 키를 사용하여 CI가 임시 채널을 한 번에 하나씩 필요하지만 기존의 main/default 채널을 관리하지 않도록

API 키를 사용하여 CI가 임시 채널을 한 번에 하나씩 필요하지만 기존의 main/default 채널을 관리하지 않도록 앱 미리보기. 보시다시피 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 미리보기 채널을 생성하고 번들을 업로드하고 홍보하는 단일 흐름을 만듭니다. 정리 작업은 원자적이고 소유권 확인이 이루어지며, 키는 자신이 생성한 채널과 연결된, 공유되지 않은 번들을 삭제할 수만 있습니다. 기존의 기본 채널, 다른 미리보기 키의 채널, 또는 다른 키의 번들을 변경, 홍보, 또는 삭제할 수 없습니다.

리뷰어들이 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

앱 프리뷰 키는 앱 설정 권한이 없기 때문에 자체적으로 프리뷰를 활성화할 수 없습니다. GitHub 액션에서, __CAPGO_KEEP_1__에 secret-bearing 프리뷰 작업을 실행하고 pull_request, pull_request_target그리고 github.event.pull_request.head.repo.full_name == github.repository.

그것들을

Deploying to a Device

Install the Capgo SDK in your app
앱에 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__을 설치합니다.
앱을 사용자 지정 채널에 듣도록 구성합니다.
업데이트를 기다리기만 하면 됩니다.

For a more detailed walkthrough, see the 실시간 업데이트 배포 설명서. 업데이트 하세요!

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

채널은 단순히 개발 단계에만 사용할 수 있는 것이 아닙니다. 사용자 구분을 위한 강력한 도구로, 다음 기능을 지원합니다.

사용자 계층별로 기능 플래그
A/B 테스트
기능 출시를 위한 점진적 출시
베타 테스트 프로그램

이 고급 사용 사례를 구현하는 방법에 대한 설명서를 참조하세요: 기능 플래그 및 A/B 테스트를 위한 사용자 구분 방법: 계획 및 채널.

채널에서 계속 진행하세요

__CAPGO_KEEP_0__이 Channels을 사용 중이라면 Channels Channels과 연결하여 Channels Channels에서 구현 세부 정보를 위해 Channels Channels에서 구현 세부 정보를 위해 Beta Testing Solution Beta Testing Solution에서 제품 워크플로우를 위해 Version Targeting Solution Version Targeting Solution에서 제품 워크플로우를 위해 Capgo 환경 최적화 방법: 단일 모바일 앱 ID를 사용한 스테이징 실제 상황에서 Capgo 환경 최적화 방법: 단일 모바일 앱 ID를 사용한 스테이징

채널