채널

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

__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):

장치 매핑 강제 (대시보드) – 특정 장치 ID를 채널에 매핑하여 긴급 디버깅 또는 단일 실제 사용자와 제어된 테스트에 사용합니다. 항상 우선합니다.
Cloud override (per-device) via Dashboard or API – 대시보드 또는 API에서 장치의 채널을 변경할 때 생성됩니다. QA 사용자가 기능/PR 채널 또는 사용자 문제를 재현하기 위해 채널을-switching합니다. 바이너리 재설치를 통해 삭제되지 않으며 장치 항목을 삭제하면 삭제됩니다.
플러그인 setChannel() local channel – 앱이 호출했을 때 생성됩니다. setChannel() and the backend validates that the target channel allows self-assignment. The selected channel is stored locally on that device, takes effect instantly, and is not shown in the Device Override UI.

플러그인 버전 5.34.0, 6.34.0, 7.34.0, 또는 8.0.0부터 시작하여 (대부분의 버전에 따라), setChannel() 다음과 같이 작동합니다: 백엔드에 접속하여 채널이 허용되는지 확인하고(self-assignment이 해당 채널에 대해 활성화되어 있는지 확인), 그 채널을 장치에 저장합니다. 이것은 새로운 채널이 즉시 다음 업데이트 확인 시에 defaultChannel적용되며, 복제를 기다리지 않습니다. 이전에는,

__CAPGO_KEEP_0__ setChannel() API 데이터베이스 (Dashboard 또는 API 변경과 같은) 백엔드에 채널 오버라이드 저장하고, 장치들은 데이터 복제가 완료될 때까지 (2분 이내) 새로운 채널이 인식될 때까지 기다려야했습니다. 새로운 동작은 백엔드에서만 읽고 (유효성 검사) 지역 저장소에만 저장하여 채널 Switch가 즉시 작동합니다.

Because setChannel() __CAPGO_KEEP_0__는 지역 전용이므로 __CAPGO_KEEP_0__에 Device Override 항목을 생성하지 않습니다. Device Override UI는 Dashboard 또는 Public __CAPGO_KEEP_1__에서만 생성된 오버라이드만 표시합니다. create a Device Override entry in the Capgo dashboard. The Device Override UI only shows overrides created from the dashboard or the Public API.

채널이 지역적으로 설정된 후 허용되지 않게 된 경우에도 백엔드는 업데이트 확인 중에 채널을 유효성 검사하므로 보안이 유지됩니다. Important:

Dashboard 또는 __CAPGO_KEEP_0__를 통해 채널 변경이 이루어질 때에도 Edge 서버가 모든 변경을 반영하기까지 2분 이내의 복제 지연이 발생합니다. 즉시 채널 Switch를 사용하려면 API에서 API를 사용하세요—it은 백엔드와 유효성 검사를 수행한 후 지역 채널을 설정하여 즉시 효과를 낼 수 있습니다. setChannel() code 구성 (테스트 빌드 기본값)

Capacitor config defaultChannel __CAPGO_KEEP_0__ – 만약에 존재한다면 capacitor.config.* 와 강제/override/local 채널이 없다면, 앱은 이 채널에서 시작합니다 (예: ). 내부 테스트 / 테스트 플라이트 빌드에 의해서 테스터들이 자동으로 이 채널에 접속하게 됩니다. 일반적인 프로덕션 빌드는 이 설정을 비워둡니다. beta, qa, pr-123Cloud Default Channel (primary path ~99%의 사용자)
– 만약에 대시보드에서 기본 채널을 설정한다면, 모든 일반 사용자 (강제, 대시보드/override, 플러그인 local 채널, config defaultChannel이 없는 사용자)는 이 채널에 연결됩니다. 이 채널을 변경하면 즉시 배포하거나 되돌릴 수 있습니다. 새로운 바이너리가 필요하지 않습니다. 플랫폼에 따라 기본 채널을 설정할 수 있습니다 (예: iOS만, Android만, Electron만). 각 기기는 자신의 플랫폼에 맞는 기본 채널에 연결됩니다. Cloud Default 채널을 비워두는 것은 허용됩니다. 이 경우 기기는 1-4 단계를 따라야 업데이트 받을 수 있습니다. – If you mark a default channel in the dashboard, all normal end‑users (no force, no Dashboard/API override, no plugin local channel, no config defaultChannel) attach here. Change it to roll out or roll back instantly—no new binary. If you have platform-specific defaults (for example, one iOS-only, one Android-only, one Electron-only), each device lands on the default matching its platform. Leaving the cloud default unset is allowed; in that case the device must match on steps 1–4 to receive updates.

1-4 단계를 예외/테스트 계층으로 처리하세요. Cloud Default 채널을 설정하면 실제 사용자는 이 채널에 연결되어야 합니다. Cloud Default 채널을 설정하지 않으면, 사용자가 어떻게 연결되는지에 대해 명확하게 결정해야 합니다 (일반적으로 config 또는 per-device override를 통해).

Only configure defaultChannel 를 테스터에게 직접 배포하는 바이너리에서만 설정하세요. Cloud Default 채널을 비워두면 프로덕션 로직이 중앙에서 관리됩니다.
Use defaultChannel 를 프로덕션에서 적극적으로 사용하지 마세요. QA 또는 특정한 디버깅 목적으로만 사용하세요.
__CAPGO_KEEP_0__ setChannel() __CAPGO_KEEP_0__

iOS/Android/Electron 플랫폼을 위한 채널이 비활성화되어 선택될 경우, 목록을 계속 내리면서 선택 과정을 건너 뛰게 됩니다.

강제 > 대시보드/API Override > 플러그인 setChannel() 지역 채널 > 설정 defaultChannel > Cloud Default.

기본 채널 동작

기본 채널 동작 defaultChannel in the Capacitor config will receive updates. When you do choose to mark defaults, keep these patterns in mind:

__CAPGO_KEEP_0__ 단일 기본값 (가장 일반적인 경우)
– iOS, Android, Electron이 모두 활성화된 채널이 단일 기본값이 됩니다. 오버라이드가 없는 장치들은 이 채널에 연결됩니다. 플랫폼별 기본값 ios-production iOS만 활성화된 경우, android-production Android만 활성화된 경우, electron-production Electron만 활성화된 경우, 각 플랫폼의 기본값으로 표시합니다. iOS 기기는 iOS 기본값으로, Android 기기는 Android 기본값으로, Electron 앱은 Electron 기본값으로 이동합니다.

클라우드 기본값을 기억하십시오. defaultChannel 클라우드 기본값과 capacitor.config.* 두 개는 동일한 결정 계층을 차지합니다. 클라우드 기본값을 설정하면 Capacitor 구성에서 값을 중복해서 입력할 필요가 없습니다—생산 빌드용으로 빈칸을 남겨두십시오. defaultChannel 테스트자 또는 QA에게 비프로덕션 채널에서 시작하도록 하려면 클라우드 기본값과 다를 때도 배포하는 바이너리를 예비로 보관하십시오. defaultChannel 대시보드에서 언제든지 기본값을 변경할 수 있습니다. 기본값을 교체하면 새로운 기기는 즉시 새로운 라우팅을 따르며 기기는 다음에 체크인할 때 정상 우선순위 규칙을 따릅니다.

채널 설정

__CAPGO_KEEP_0__

‘채널’ 섹션으로 이동하여 Capgo 대시보드를 열어보세요
‘새로운 채널’ 버튼을 클릭하세요
채널 이름을 입력하고 ‘생성’ 버튼을 클릭하세요

채널 이름은 마음대로 지어도 됩니다. 일반적인 전략은 개발 단계와 채널을 매칭하는 것입니다.

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

채널을 앱에 구성하는 방법

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

파일을 열어 주세요 capacitor.config.ts (또는 capacitor.config.json) 파일을 열어 주세요. plugins 섹션 아래에, 옵션적으로 defaultChannel 테스트 빌드 (내부 / QA) 설정합니다. 프로덕션 빌드의 경우, Cloud Default를 사용하도록 하거나 명시적으로 재정의하지 않는 한, 기기에서 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 프로젝트에 업데이트된 config 파일을 클립보드에 복사하세요. 이 동기화 단계를 생략하면, 기존에 설정된 채널을 계속 사용하는 native 프로젝트가 계속 사용됩니다.

채널 옵션 및 전략

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

기본 채널: 새로운 기기를 연결할 때 채널 또는 플랫폼에 구애받지 않는 채널을 선택할 수 있습니다. 라우팅 시나리오에 대한 자세한 내용은 “기본 채널 동작”을 참조하세요.
플랫폼 필터: 전달을 허용하거나 차단할 수 있습니다. iOS, Android또는 Electron 채널당 기기 수.
원본: 네이티브에서 자동 다운그레이드 비활성화: 기기의 네이티브 앱 버전이 채널의 배달본보다 최신일 때 업데이트를 보내지 않습니다. (예: 기기 버전 1.2.3, 채널 버전 1.2.2).
개발 빌드 허용: 개발 빌드에 대한 업데이트를 허용합니다. (테스트에 유용합니다).
에뮬레이터 기기 허용: 테스트에 유용한 에뮬레이터/시뮬레이터에 대한 업데이트를 허용합니다.
기기 자체 할당 허용: 앱이 런타임에 이 채널로 Switch할 수 있도록 합니다. setChannel비활성화 시, setChannel 이 채널에서

진보적 롤아웃

채널은 안정적인 배달본을 유지하면서도 특정 기기 그룹에 롤아웃 대상으로 노출하는 것을 점진적으로 진행할 수 있습니다. 또한 채널을 전부 변경하지 않고도 중단, 재개, 승격, 롤백, 자동 실패 응답 구성이 가능합니다. 자세한 내용은 진보적 롤아웃 배달 모델, 대시보드 워크플로우, API field, 및 CLI 명령에 대한

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

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

주 버전: 대상 패키지의 주 버전이 기기 기본선에 대한 주 버전보다 높을 경우에 해당 패키지를 차단합니다. 예시:version_build차단; 1.2.3 -> 2.0.0 허용. 1.2.3 -> 1.9.0 소 버전: 대상 패키지의 주 버전 또는 소 버전이 기기 기본선의 주 버전 또는 소 버전과 다를 경우에 해당 패키지를 차단합니다. 예시:
차단; version_build허용. 1.2.3 -> 1.3.0 major: 기기 기본선의 주 버전보다 높은 대상 패키지의 주 버전을 차단합니다. 예시: 1.2.3 -> 1.2.4 is blocked; is allowed.
patch: 가장 엄격한 모드. 메이저, 마이너, 패치 번호의 변경을 모두 차단합니다.Only suffix 변경이 허용됩니다. 예시: MAJOR.MINOR.PATCH stays 동일합니다. 예시: 1.0.0-beta.1 -> 1.0.0-beta.2 is allowed, 1.0.0+build.1 -> 1.0.0+build.2 is allowed, 1.0.0 -> 1.0.1 is 차단됩니다.
metadata: 각 번들에 최소 업데이트 버전 메타데이터가 필요합니다. CLI을 사용하여 --min-update-version or --auto-min-update-versionIf 누락되면 채널이 미설정으로 표시되어 업데이트가 거부됩니다.
none: semver 호환성에 따라 모든 업데이트를 허용합니다..

이 전략은 채널의 대상 번들을 native baseline으로 비교합니다. version_build다운로드 한 현재 번들을 비교하지 않습니다. version_name.

더 많은 예시와 정보는 /docs/cli/commands/#disable-updates-strategy 에서 확인할 수 있습니다.

예(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 App에서 setChannel() 사용

Your App에서 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
즉시 효과: 새로운 채널을 사용하는 다음 업데이트 체크가 즉시 발생합니다 (복제 기다리지 않음)

왜 이것이 중요합니까: In older versions, setChannel() API에서 채널 오버라이드가 저장되었습니다 (다시보기를 위해 대시보드나 API 변경과 동일합니다). 장치들은 백엔드 복제가 완료될 때까지 (최대 2분) 채널 변경이 적용되기까지 기다려야했습니다. 이제는 setChannel() 백엔드에서만 읽어 (유효성 검사용) 로컬에 저장하여 채널 Switch가 즉시 적용됩니다.

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

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

채널 변경 방법 비교:

방법	효과 시간	저장 위치	장치 오버라이드 UI에 표시	사용 사례
`setChannel()` 플러그인에서	즉시	기기만 (로컬)	아니요	사용자 동의 없이 앱 내 채널-switching
앱 내 채널-switching 대시보드 기기 override	최대 2분	백엔드 데이터베이스	예	관리자 동의 없이 특정 기기 변경
API 채널 assignment	__CAPGO_KEEP_0__	백엔드 데이터베이스	예	자동화된 백엔드 통합

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

지역 전용 채널 Switching을 위한 최소 버전: 5.34.0, 6.34.0, 7.34.0, 또는 8.0.0 (대형 버전에 따라) 각 소수 버전 번호는 모든 대형 버전에서 동일한 기능 집합을 나타냅니다 (예: X.34.0은 X가 5, 6, 7, 또는 8이더라도 동일한 기능을 포함합니다). __CAPGO_KEEP_0__

버전 태그를 위한 플러그인 설치를 참조하세요.

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

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

Capgo 버전 관리 및 채널

__CAPGO_KEEP_0__의 번들은 앱에 전역적이며, 채널에 특정되지 않습니다. 동일한 번들이 여러 채널에 assign될 수 있습니다.

Capgo

__CAPGO_KEEP_0__ Capgo __CAPGO_KEEP_0__ 1.2.3-beta.1.

__CAPGO_KEEP_0__

__CAPGO_KEEP_0__ 1.2.3-beta.1 __CAPGO_KEEP_0__ 1.2.3.
__CAPGO_KEEP_0__
__CAPGO_KEEP_0__ 1.2.3__CAPGO_KEEP_0__ 1.2.2 __CAPGO_KEEP_0__

__CAPGO_KEEP_0__

Development __CAPGO_KEEP_0__ 1.2.3-dev.1, 1.2.3-dev.2__CAPGO_KEEP_0__
QA __CAPGO_KEEP_0__ 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사용

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

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

롤백할 채널의 이름을 클릭

롤백할 채널의 이름을 클릭
원하는 빌드를 찾고 crown 아이콘을 클릭하세요.
이동을 확인하세요

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

배포 자동화

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

CI/CD Integration 더 많은 정보를 얻기 위해 __CAPGO_KEEP_0__ 라이브 업데이트 자동화에 대한 문서를 확인하세요. docs to learn more about automating Capgo live updates.

최소 권한 PR 미리보기

CI 환경에서 Pull Request 당 하나의 임시 채널이 필요하지만 기존의 main/default 채널을 관리하지 않아야 할 때는 앱 미리보기 API

Have an organization administrator create a secure API key limited to the preview app and select 앱 미리보기관리자로 로그인하여 API Keys.
. pr-123See --default, --self-assign앱 미리보기 키 --delete-linked-bundle-on-upload.
CI 환경에서 Pull Request 당 하나의 임시 채널이 필요하지만 기존의 main/default 채널을 관리하지 않아야 할 때는

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 __CAPGO_KEEP_0__ 채널이 없으면 생성하고, __CAPGO_KEEP_0__를 업로드하고, 한 번의 흐름으로 __CAPGO_KEEP_0__를 승격합니다. 정리도 원자적이고 소유권을 확인합니다: 키는 자신이 생성한 채널과 연결된, 공유되지 않은 __CAPGO_KEEP_0__만 삭제할 수 있습니다. __CAPGO_KEEP_0__ 채널, 다른 미리보기 키의 채널, 또는 다른 키의 __CAPGO_KEEP_0__를 변경, 승격, 또는 삭제할 수 없습니다.

리뷰어들이 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 액션에서, GitHub를 실행하는 secret-bearing 미리보기 작업을 pull_request, __CAPGO_KEEP_0__ pull_request_target, __CAPGO_KEEP_0__와 제한하여 github.event.pull_request.head.repo.full_name == github.repository.

,

__CAPGO_KEEP_0__

Capgo를 이해한 후, 실제 기기에서 live 업데이트를 배포하기 위해 시작할 준비가 되었습니다. 기본 프로세스는 다음과 같습니다:SDK를 앱에 설치합니다.
앱을 원하는 채널에 연결하도록 구성하세요.
업데이트를 할 채널에 빌드를 업로드하고 Assign하세요.
앱을 실행하고 업데이트를 기다리세요!

상세한 설명을 원하시면 실시간 업데이트 배포 을 참조하세요. 업데이트 하세요!

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

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

사용자 계층별 기능 플래그
A/B 테스트
기능 롤아웃
Beta testing 프로그램

Learn how to implement these advanced use cases in our guide: Plan 및 채널을 통해 사용자를 구분하는 방법과 기능 플래그 및 A/B 테스트를 위한 방법.

Channels에서 계속

Channels를 사용 중이라면 Channels 채널 라우팅 및 스테이지드 롤아웃을 계획하는 데 사용하는 Channels를 Cloudflare와 연결하세요. Channels Channels와의 구현 세부 정보를 Channels에서 확인하세요. Channels Channels와의 구현 세부 정보를 Channels에서 확인하세요. Beta Testing Solution Beta Testing Solution을 위한 제품 워크플로우에 대해 Version Targeting Solution Version Targeting Solution을 위한 제품 워크플로우 및 Capgo 환경 최적화: 단일 모바일 앱 ID를 사용한 스테이징 Capgo 환경 최적화: 단일 모바일 앱 ID를 사용한 스테이징에 대한 실제 적용 사례.