채널

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

라이브 업데이트 채널은 특정 JS 번들 빌드의 앱이 공유될 장치에 구성된 모든 장치에 대한 업데이트입니다. Capgo Live Updates SDK 설치 앱 내에서, 지정된 채널에 구성된 모든 네이티브 바이너리는 앱이 시작될 때마다 사용 가능한 업데이트를 확인합니다. 채널을 변경하거나 이전 빌드로 롤백할 수 있습니다.

Channels control update eligibility, not bundle secrecy. Even if a channel is private or self-assignment is disabled, any unencrypted bundle uploaded to Capgo should still be treated as a public asset delivered to clients. Encryption protects the delivery path and authenticity of updates, but shipped bundles can still be reverse engineered from the distributed app with enough effort because the public key is part of the client. See 자세한 내용은 채널을 선택하는 방법 (순위)

채널을 선택하는 방법 (순위)

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

– 긴급 디버깅이나 단일 실제 사용자와 제어된 테스트를 위해 특정 장치 ID를 채널에 고정하세요. 항상 우선합니다. __CAPGO_KEEP_0__
Cloud override (per-device) via Dashboard or API – Created when you change the device’s channel in the dashboard or via API. Use for QA users switching between feature / PR channels or to reproduce a user issue. Reinstalling the binary does not clear it; deleting the device entry does.
Plugin setChannel() __CAPGO_TARGET_LANGUAGE__에서 앱이 호출할 때 생성됩니다. 백엔드가 대상 채널이 자체 할당을 허용하는지 확인하여 채널을 선택합니다. 선택한 채널은 즉시 적용되고 장치에 저장되며 Device Override UI에 표시되지 않습니다. setChannel() setChannel()을 사용한 즉시 채널 Switching

__CAPGO_TARGET_LANGUAGE__에서 작동 방식이 다릅니다: 백엔드에 접촉하여 validate setChannel() validate validate 채널이 허용되는지 확인하고(self-assignment이 해당 채널에 대해 활성화되어 있는지 확인) 채널을 저장한다. 장치에 저장 으로 defaultChannel이것은 새로운 채널이 즉시 다음 업데이트 체크부터 적용되기 때문에 기다리지 않아도 된다. 이전에는

채널 오버라이드 저장을 백엔드 데이터베이스(예: 대시보드 또는 __CAPGO_KEEP_0__ 변경)에 저장하고, 장치들은 데이터 복제가 완료될 때까지(2분 이내) 새로운 채널이 인식되기까지 기다려야 했다. 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() 백엔드에 저장되지 않기 때문에 __CAPGO_KEEP_0__ 대시보드의 Device Override 항목을 생성하지 않는다. create a Device Override entry in the Capgo dashboard. The Device Override UI only shows overrides created from the dashboard or the Public API.

Note: 업데이트 확인 시 채널이 로컬에서 설정된 후에도 불허된 채널이 된 경우에도 백엔드는 채널을 검증하므로 보안은 유지됩니다.

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

Capacitor config defaultChannel – 만약에 __CAPGO_KEEP_0__가 존재하고, force/override/local 채널이 없다면, 앱은 이 채널에서 시작합니다 (예를 들어, ). 테스트 빌드 및 내부 빌드에만 사용하여 테스터가 자동으로 프리-리리즈 채널에 접속되도록 합니다. 프로덕션 빌드는 일반적으로 이 설정을 비워둡니다. Cloud Default Channel (primary path ~99% of users) capacitor.config.* – 만약에 Dashboard에서 기본 채널을 설정하면, 모든 일반 사용자 (force, Dashboard/__CAPGO_KEEP_0__ override, plugin local channel, config defaultChannel이 없는 경우)는 이 채널에 연결됩니다. 즉시 배포 또는 롤백을 원한다면, 새로운 바이너리가 필요하지 않습니다. 플랫폼에 따라 기본 채널을 설정할 수 있습니다 (예를 들어, iOS만, Android만, Electron만). 각 기기는 자신의 플랫폼에 맞는 기본 채널에 연결됩니다. Cloud Default 채널을 비워두는 것은 허용되며, 이 경우 기기는 1-4 단계에 따라 업데이트를 받습니다. beta, qa, pr-123__CAPGO_KEEP_0__—it validates with the backend, then sets the channel locally for immediate effect.
__CAPGO_KEEP_0__ config – 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.

Best practice:

테스트層인 1–4을 예외로 처리하세요. 클라우드 기본값을 설정할 경우, 실제 사용자는 그에 따라 흐릅니다. 기본값을 설정하지 않으려면, 사용자가 어떻게 연결하는지(일반적으로 config 또는 per-device overrides를 통해) 의도적으로 결정하세요. defaultChannel Only configure
생산 환경에서 사용하지 않도록 하세요. 테스터에게만 배포하는 바이너리에서만 사용하세요. 기본값을 설정하지 않으면, 프로덕션 로직은 대시보드에서 중앙 집중화됩니다. defaultChannel Use
생산 환경에서 사용하지 않도록 하세요. QA 또는 특정한 디버깅 목적으로만 사용하세요. setChannel() 플랫폼(iOS/Android/Electron)을 통해 채널이 비활성화된 경우, 채널 선택 프로세스는 해당 채널을 건너뛰고 목록의 다음 채널로 진행합니다.

Summary: Force > 대시보드/__CAPGO_KEEP_0__ Override > 플러그인

Summary: Force > Dashboard/API Override > Plugin setChannel() > 클라우드 기본값. defaultChannel 기본 채널 동작

Default Channel Behavior

클라우드 기본 설정은 선택 사항이지만, 새로운 장치의 기본 경로로 사용됩니다. 기본 설정이 없으면, 강제 매핑, 오버라이드, 또는 defaultChannel Capacitor

설정에서만 업데이트를 받을 수 있습니다. 기본 설정을 지정할 때 다음 패턴을 기억하세요: 단일 기본 설정(가장 일반적인 경우)
– iOS, Android, Electron이 모두 활성화된 채널이 단일 기본 설정이 됩니다. 오버라이드가 없는 장치들은 이 채널에 연결됩니다. 플랫폼별 기본 설정 ios-production – 플랫폼별로 채널을 나누면 (예를 들어, android-production iOS만 활성화된 채널 electron-production Android만 활성화된 채널

Electron만 활성화된 채널 defaultChannel 각 플랫폼별로 기본 설정을 지정하세요. iOS 장치들은 iOS 기본 설정으로, Android 장치들은 Android 기본 설정으로, Electron 앱들은 Electron 기본 설정으로 연결됩니다. 또한 클라우드 기본 설정과 capacitor.config.* 동일한 결정层을 차지합니다. Cloudflare 기본값을 설정하면 Capacitor 구성에서 값의 복제가 필요하지 않습니다.—leave defaultChannel 생산 빌드용으로 빈칸을 남겨두세요. defaultChannel 테스터나 QA에게 배포할 바이너리용으로 예비 채널에서 시작하도록 하려면, Cloudflare 기본값이 다를 경우에도.

대시보드에서 언제든지 기본값을 변경할 수 있습니다. 기본값을 교체하면 새로운 기기들은 즉시 새로운 라우팅을 따르며 기존 기기는 다음에 체크인할 때 정상 순위 규칙을 따릅니다.

채널 설정

온보딩 중에 첫 번째 채널을 생성합니다(대부분의 팀은 이를 '생산'이라고 이름짓습니다). 그러나 아무것도 잠금되지 않습니다. 채널 이름을 변경하거나 삭제할 수 있습니다. 추가 채널을 추가하려면:

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

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

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

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

채널이 생성되면, 앱을 해당 채널에 맞게 구성해야 합니다. 이 예에서는 채널을 사용해 보겠습니다. Development channel.

파일을 열어보세요. capacitor.config.ts (또는 capacitor.config.json) 파일을 열어보세요. plugins section 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 프로젝트로 복사하세요. 이 동기화 단계를 건너뛰면, 이전에 구성된 채널을 계속 사용하는 native 프로젝트가 계속 사용됩니다.

장치나 오버라이드 적용을 나중에 강제로 지정할 수 있습니다. 이들은 즉시 구성 값에 우선합니다.

Channels have several options that control who can receive updates and how updates are delivered. The most important ones are below. You can configure these from the web app, the CLI, or the Public API.

채널 옵션 및 전략 섹션
채널은 업데이트를 받을 수 있는 사람과 업데이트가 전달되는 방법을 제어하는 여러 옵션을 가지고 있습니다. 가장 중요한 것은 아래에 나열되어 있습니다. 이들을 웹 앱, __CAPGO_KEEP_0__, 또는 Public __CAPGO_KEEP_1__에서 구성할 수 있습니다. iOS, Android기본 채널: 새로운 장치가 연결될 때 채널 또는 플랫폼에 특정한 채널을 표시할 수 있습니다. '기본 채널 동작'을 참조하십시오. Electron 플랫폼 필터:
장치당 채널당
네이티브 하의 자동 다운그레이드 비활성화: 장치의 네이티브 앱 버전이 채널의 배포본 버전보다 새로운 경우 업데이트를 보내지 않도록 합니다.
개발 빌드 허용: 개발 빌드에 업데이트를 허용합니다. 테스트에 유용합니다.
장치 자가 할당 허용: 앱이 런타임에 이 채널로 Switch 할 수 있도록 허용합니다. setChannel이 기능이 비활성화 된 경우 setChannel 이 채널에서 실패합니다.

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

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

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 동일하게 유지됩니다. 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모두 허용됩니다.
버전 호환성에 따라 업데이트를 허용합니다. 버전 호환성에 따라 업데이트를 허용합니다..

이 전략은 채널의 목표 배포본을 원시 기반이라는 __CAPGO_KEEP_0__으로 보낸 것과 비교합니다. version_build현재 다운로드 한 배포본 __CAPGO_KEEP_0__으로 보낸 것과는 다릅니다. version_name.

Disable updates 전략에 대한 자세한 내용과 예제는 /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()을 사용하는 경우

이 메소드는 앱이 런타임에 채널을 switch할 수 있도록 허용합니다. 이 기능은 특히: setChannel() QA/디버그 메뉴에서 테스터가 채널을 switch할 수 있도록 해주며

베타 프로그램 옵인 플로우
The
기능 플래그 구현
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
즉시 효과: 다음 업데이트 체크는 새로운 채널을 즉시 사용합니다 (replication 대기 없이)

왜 이것이 중요합니까: 이전 버전에서 setChannel() 저장소에 채널 오버라이드 저장 (같은 Dashboard 또는 API 변경과) setChannel() 장비는 백엔드 복제 (최대 2분)가 끝날 때까지 채널 변경이 적용되지 않았습니다. 이제

백엔드에서만 읽고 (유효성 검사용) 로컬에서만 저장하여 채널 Switch가 즉시 적용됩니다. A channel set with the plugin does not make the device appear as a Device Override in the Capgo UI. Only channel assignments created from the dashboard or the Public API are listed there. Use the dashboard or API when you need an admin-visible override.

플러그인으로 설정한 채널은 __CAPGO_KEEP_0__ UI에서 장비를 Device Override로 나타내지 않습니다. 대시보드 또는 Public __CAPGO_KEEP_1__에서만 생성한 채널 assignments만 목록에 표시됩니다. 대시보드 또는 __CAPGO_KEEP_2__를 사용하여 관리자가 보는 오버라이드가 필요할 때입니다. 보안 주의:

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

채널 변경 방법 비교:	방법	저장된 Where	기기 오버라이드 UI에서 표시됨	사용 사례
`setChannel()` 플러그인에서	즉시	기기만 (로컬)	아니요	사용자 앱 내 채널 Switching
기기 오버라이드 대시보드	2분 이내	백엔드 데이터베이스	예	특정 기기에 대한 관리자가 시작한 변경 사항
API 채널 할당	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이더라도 동일한 기능을 포함합니다). 플러그인 설치를 참조하세요. __CAPGO_KEEP_0__ 버전 태그입니다.

__CAPGO_KEEP_0__ 채널에 번들을 Assign합니다.

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__ 채널의 활성 빌드로 설정합니다. __CAPGO_KEEP_0__에서 설정된 채널에 연결된 앱은 업데이트를 받을 때까지 업데이트를 받지 않습니다. Development __CAPGO_KEEP_0__에서 빌드 채널 Assign을 할 수 있습니다. __CAPGO_KEEP_0__ 메뉴 아이콘을 클릭하고 Assign to Channel을 선택하여 빌드 채널을 선택할 수 있습니다.

Capgo 채널과 번들의 버전 관리

__CAPGO_KEEP_0__ 채널과 번들의 버전 관리

Capgo 채널과 번들의 버전 관리

버전 번호를 지정할 때, 우리는 __CAPGO_KEEP_0__의 Semver Tester와 채널에 따라 구분되는 빌드에 대한 전제 버전 식별자를 사용하는 의미적 버전 관리를 추천합니다. semantic versioning with Capgo’s Semver Tester 이 접근 방식에는 다음과 같은 이점이 있습니다. 1.2.3-beta.1.

빌드 간의 관계를 명확하게 전달합니다.

obviously는 __CAPGO_KEEP_0__의 이전 안정 버전입니다. 1.2.3-beta.1 채널 간에 버전 번호를 재사용할 수 있어 혼란을 줄입니다. 1.2.3.
rollback 경로를 명확하게 제공합니다. __CAPGO_KEEP_0__에서 rollback할 필요가 있을 때, 이전 안정 버전은
이전 안정 버전은 __CAPGO_KEEP_0__입니다. 1.2.3채널: 1.2.2 버전 번호를 지정할 때, 우리는 __CAPGO_KEEP_0__의 Semver Tester와 채널에 따라 구분되는 빌드에 대한 전제 버전 식별자를 사용하는 의미적 버전 관리를 추천합니다.

예를 들어, 베타 버전은 다음과 같이 버전이 지정될 수 있습니다.

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.4Using

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

Section titled “Rolling Back a Live Update”

배포 중인 업데이트에서 버그를 소개하거나 다시 되돌려야 하는 경우, 이전 빌드로 쉽게 되돌아갈 수 있습니다. 대시보드의 "채널" 섹션에서:

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

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

자동 배포

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

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

장치에 배포

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

Capgo SDK을 앱에 설치합니다.
원하는 채널을 듣기 위해 앱을 구성합니다.
업데이트를 할 채널에 빌드를 업로드하고 Assign합니다.
앱을 실행하고 업데이트를 기다립니다.

상세한_walkthrough를 보려면 라이브 업데이트를 배포하는 방법 guide. 업데이트를 즐기세요!

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

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

다양한 사용자 계층에 대한 기능 플래그
A/B 테스트
기능 출시를 위한 단계적 출시
베타 테스트 프로그램

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

채널에서 계속 진행하세요

채널을 사용하여 채널 라우팅과 단계적 출시를 계획하고 있다면 connect it with 채널 채널의 구현 세부 정보에 대해 채널 채널의 구현 세부 정보에 대해 베타 테스트 솔루션 베타 테스트 솔루션의 제품 워크플로에 대해 버전 목표 솔루션 버전 목표 솔루션의 제품 워크플로 및 Capgo 환경 최적화: 단일 모바일 앱 ID를 사용한 스테이징 Capgo 환경 최적화: 단일 모바일 앱 ID를 사용한 스테이징의 실제 상황에 대해