채널

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

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

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

강제 기기 매핑 (대시보드) – 특정 기기 ID를 채널에 수동으로 고정합니다. 긴급한 디버깅이나 단일 실제 사용자와의 제어된 테스트에 사용합니다. 이것이 항상 우선입니다.
대시보드 또는 API를 통한 클라우드 오버라이드 (기기별) – 대시보드나 API에서 기기의 채널을 변경할 때 생성됩니다. 기능/PR 채널 간 전환하는 QA 사용자나 사용자 문제를 재현하는 데 사용합니다. 바이너리 재설치로는 지워지지 않으며, 기기 항목 삭제로 지워집니다.

플러그인 버전 5.34.0, 6.34.0, 7.34.0 또는 8.0.0부터 (메이저 버전에 따라), setChannel()이 다르게 작동합니다: 백엔드에 연결하여 채널이 허용되는지 검증하고 (해당 채널에 대해 자가 할당이 활성화되어 있는지 확인), 그런 다음 채널을 defaultChannel로 기기에 로컬로 저장합니다. 이는 새 채널이 다음 업데이트 확인에 즉시 적용된다는 것을 의미합니다—복제를 기다릴 필요가 없습니다.

이전에는 setChannel()이 채널 오버라이드를 백엔드 데이터베이스에 저장했습니다 (대시보드나 API 변경과 동일). 기기는 새 채널이 인식되기 전에 데이터 복제를 기다려야 했습니다 (최대 2분). 새로운 동작은 백엔드에서만 읽고 (검증용) 로컬에 저장하여 채널 전환을 즉시 만듭니다.

참고: 채널이 로컬에 설정된 후 허용되지 않게 되더라도, 백엔드는 업데이트 확인 시 여전히 채널을 검증하므로 보안이 유지됩니다.

중요: 대시보드나 API를 통해 채널 변경이 이루어지면, 모든 엣지 서버가 변경을 반영하기까지 최대 2분의 복제 지연이 여전히 있습니다. 즉시 채널 전환을 위해서는 앱 코드에서 setChannel()을 사용하세요—백엔드와 검증한 다음 로컬에서 채널을 설정하여 즉시 효과를 냅니다.

Capacitor 설정 defaultChannel (테스트 빌드 기본값) – capacitor.config.*에 있고 강제/오버라이드가 없으면, 앱은 이 채널에서 시작합니다 (예: beta, qa, pr-123). 테스터가 자동으로 프리릴리스 채널에 도착하도록 TestFlight/내부 빌드용입니다. 프로덕션 빌드는 보통 이를 비워둡니다.
클라우드 기본 채널 (주요 경로 ~99% 사용자) – 대시보드에서 기본 채널을 표시하면, 모든 일반 최종 사용자 (강제, 오버라이드, 설정 defaultChannel 없음)가 여기에 연결됩니다. 즉시 롤아웃하거나 롤백하려면 변경하세요—새 바이너리 필요 없음. 플랫폼별 기본값이 있는 경우 (iOS 전용 하나, Android 전용 하나), 각 기기는 해당 플랫폼에 맞는 기본값에 도착합니다. 클라우드 기본값을 비워두는 것도 허용됩니다; 이 경우 기기가 업데이트를 받으려면 1-3 단계에서 일치해야 합니다.

모범 사례:

1-3을 예외/테스트 레이어로 취급하세요; 클라우드 기본값을 설정하면 실제 사용자가 그곳으로 흐르게 됩니다. 설정하지 않기로 선택하면, 사용자가 어떻게 연결되는지 의도적으로 결정하세요 (일반적으로 설정의 defaultChannel 또는 기기별 오버라이드를 통해).
테스터에게 명시적으로 배포하는 바이너리에만 defaultChannel을 구성하세요. 비워두면 프로덕션 로직이 대시보드에서 중앙 집중화됩니다.
프로덕션에서 setChannel()을 드물게 사용하세요—주로 QA나 타겟 진단용.

채널이 선택되어야 할 때 플랫폼 (iOS/Android 토글)에서 비활성화되면, 선택 프로세스는 이를 건너뛰고 목록에서 계속됩니다.

요약: 강제 > 오버라이드 > 설정 defaultChannel > 클라우드 기본값.

기본 채널 동작

클라우드 기본값 설정은 선택 사항이지만, 보통 새 기기를 위한 포괄 경로 역할을 합니다. 없으면, 강제 매핑, 오버라이드 또는 Capacitor 설정의 defaultChannel에서 일치하는 기기만 업데이트를 받습니다. 기본값을 표시하기로 선택할 때 이러한 패턴을 염두에 두세요:

단일 기본값 (가장 일반적) – 채널에 iOS와 Android가 모두 활성화되어 있으면, 유일한 기본값이 됩니다; 오버라이드가 없는 모든 기기가 여기에 연결됩니다.
플랫폼별 기본값 – 플랫폼별로 채널을 분리하는 경우 (예: iOS만 활성화된 ios-production과 Android만 활성화된 android-production), 각각을 해당 플랫폼의 기본값으로 표시합니다. iOS 기기는 iOS 기본값으로, Android 기기는 Android 기본값으로 갑니다.

클라우드 기본값과 capacitor.config.*의 defaultChannel은 모두 같은 결정 레이어를 차지한다는 것을 기억하세요. 클라우드 기본값을 설정하면, Capacitor 설정에서 값을 복제할 필요가 없습니다—프로덕션 빌드에서 defaultChannel을 비워두세요. 클라우드 기본값이 다르더라도 비프로덕션 채널에서 시작하길 원할 때 테스터나 QA에게 의도적으로 배포하는 바이너리를 위해 defaultChannel을 예약하세요.

대시보드에서 언제든지 기본값을 변경할 수 있습니다. 기본값을 바꾸면, 새 기기는 즉시 새 라우팅을 따르고 기존 기기는 다음 체크인 시 일반 우선순위 규칙을 따릅니다.

채널 설정하기

온보딩 중 첫 번째 채널을 만듭니다 (대부분의 팀은 “Production”이라고 이름 짓습니다), 하지만 아무것도 잠겨 있지 않습니다—언제든지 채널 이름을 바꾸거나 삭제할 수 있습니다. 나중에 추가 채널을 추가하려면:

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

채널 이름은 원하는 대로 지정할 수 있습니다. 일반적인 전략은 다음과 같이 개발 단계에 맞춰 채널을 지정하는 것입니다:

Development - 로컬 기기나 에뮬레이터에서 라이브 업데이트 테스트용
QA - QA 팀이 광범위한 배포 전에 업데이트를 확인하기 위한 용도
Staging - 프로덕션과 유사한 환경에서 최종 테스트용
Production - 최종 사용자가 앱 스토어에서 받는 버전용

앱에서 채널 구성하기

채널을 생성한 후에는 앱이 적절한 채널을 수신하도록 구성해야 합니다. 이 예시에서는 Development 채널을 사용하겠습니다.

capacitor.config.ts (또는 capacitor.config.json) 파일을 엽니다. plugins 섹션에서 테스트 빌드 (내부/QA)용으로 defaultChannel을 선택적으로 설정합니다. 프로덕션 빌드의 경우, 명시적으로 오버라이드되지 않는 한 기기가 클라우드 기본값을 사용하도록 생략하는 것이 좋습니다.

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      // QA/TestFlight 빌드용 – 테스터가 자동으로 Development 채널에서 시작합니다.
      defaultChannel: 'Development',
      // 프로덕션 빌드는 보통 이를 생략하여 사용자가 클라우드 기본 채널에 연결됩니다.
    },
  },
};

다음으로, 웹 앱을 빌드하고 npx cap sync를 실행하여 업데이트된 구성 파일을 iOS와 Android 프로젝트에 복사합니다. 이 동기화 단계를 건너뛰면, 네이티브 프로젝트는 이전에 구성된 채널을 계속 사용하게 됩니다.

채널 옵션 및 전략

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

기본 채널: 새 기기가 연결될 채널 또는 플랫폼별 채널을 선택적으로 표시합니다. 라우팅 시나리오는 “기본 채널 동작”을 참조하세요.
플랫폼 필터: 채널별로 iOS 및/또는 Android 기기로의 전달을 활성화하거나 비활성화합니다.
네이티브 아래 자동 다운그레이드 비활성화: 기기의 네이티브 앱 버전이 채널의 번들보다 최신일 때 업데이트 전송을 방지합니다 (예: 기기가 1.2.3이고 채널이 1.2.2인 경우).
개발 빌드 허용: 개발 빌드에 대한 업데이트를 허용합니다 (테스트에 유용).
에뮬레이터 기기 허용: 에뮬레이터/시뮬레이터에 대한 업데이트를 허용합니다 (테스트에 유용).
기기 자가 할당 허용: 앱이 런타임에 setChannel을 사용하여 이 채널로 전환할 수 있게 합니다. 비활성화되면 이 채널에 대해 setChannel이 실패합니다.

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

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

major: 크로스 메이저 업데이트 차단 (0.0.0 → 1.0.0). 마이너 및 패치 업데이트는 여전히 허용.
minor: 크로스 마이너 업데이트 (예: 1.1.0 → 1.2.0) 및 메이저 차단. 패치 업데이트는 여전히 허용. 참고: 0.1.0 → 1.1.0은 차단하지 않음.
patch: 매우 엄격함. 동일한 메이저 및 마이너 내에서 증가하는 패치 버전만 허용. 예: 0.0.311 → 0.0.314 ✅, 0.1.312 → 0.0.314 ❌, 1.0.312 → 0.0.314 ❌.
metadata: 각 번들에 최소 업데이트 버전 메타데이터 필요. CLI에서 --min-update-version 또는 --auto-min-update-version을 사용하여 구성. 없으면 채널이 잘못 구성된 것으로 표시되고 설정될 때까지 업데이트가 거부됩니다.
none: semver 호환성에 따라 모든 업데이트 허용.

자세한 내용과 예시는 /docs/cli/commands/#disable-updates-strategy에서 업데이트 비활성화 전략을 참조하세요.

예시 (CLI):

# Production 채널에서 메이저 업데이트 차단
npx @capgo/cli@latest channel set production com.example.app \
  --disable-auto-update major

# 기기가 Beta 채널에 자가 할당할 수 있도록 허용
npx @capgo/cli@latest channel set beta com.example.app --self-assign

앱에서 setChannel() 사용하기

setChannel() 메서드를 사용하면 앱이 런타임에 프로그래밍 방식으로 채널을 전환할 수 있습니다. 다음에 특히 유용합니다:

테스터가 채널 간 전환할 수 있는 QA/디버그 메뉴
베타 프로그램 옵트인 플로우
기능 플래그 구현
A/B 테스트 시나리오

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// 베타 채널로 전환
await CapacitorUpdater.setChannel({ channel: 'beta' });

// 선택적으로 전환 후 즉시 업데이트 확인 트리거
await CapacitorUpdater.setChannel({
  channel: 'beta',
  triggerAutoUpdate: true
});

setChannel()이 호출되면:

백엔드 검증 (읽기 전용): Capgo 백엔드에 요청을 보내 채널이 허용되는지 검증합니다 (자가 할당 권한 확인)
로컬 저장소 업데이트: 검증이 통과하면, 채널이 기기의 로컬 저장소에 defaultChannel로 저장됩니다
즉시 효과: 다음 업데이트 확인은 새 채널을 즉시 사용합니다 (복제 대기 없음)

이것이 중요한 이유: 이전 버전에서 setChannel()은 채널 오버라이드를 백엔드 데이터베이스에 저장했습니다 (대시보드나 API 변경과 동일). 기기는 채널 변경이 적용되기 전에 백엔드 복제를 기다려야 했습니다 (최대 2분). 이제 setChannel()은 백엔드에서만 읽고 (검증용) 로컬에 저장하여 채널 전환을 즉시 만듭니다.

보안 참고: 채널 권한이 로컬에 설정된 후 변경되더라도 (예: 자가 할당이 비활성화됨), 백엔드는 업데이트 확인 시 여전히 채널을 검증하여 보안을 보장합니다.

채널 변경 방법 비교:

방법	효과 시간	저장 위치	사용 사례
플러그인의 `setChannel()`	즉시	기기만 (로컬)	앱 내 사용자 시작 채널 전환
대시보드 기기 오버라이드	최대 2분	백엔드 데이터베이스	특정 기기에 대한 관리자 시작 변경
API 채널 할당	최대 2분	백엔드 데이터베이스	자동화된 백엔드 통합

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

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

채널에 번들 할당하기

라이브 업데이트를 배포하려면 새로운 JS 번들 빌드를 업로드하고 채널에 할당해야 합니다. Capgo CLI를 사용하여 한 번에 이 작업을 수행할 수 있습니다:

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

이렇게 하면 빌드된 웹 자산을 업로드하고 새 번들을 Development 채널의 활성 빌드로 설정합니다. 해당 채널을 수신하도록 구성된 모든 앱은 다음 업데이트 확인 시 업데이트를 받게 됩니다.

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

번들 버전 관리와 채널

Capgo의 번들은 개별 채널에 특정되지 않고 앱 전체에 전역적이라는 점을 주의해야 합니다. 동일한 번들을 여러 채널에 할당할 수 있습니다.

번들 버전 관리 시, 채널별 빌드에 대해 semver 시맨틱 버저닝과 사전 릴리스 식별자를 사용하는 것을 권장합니다. 예를 들어, 베타 릴리스는 1.2.3-beta.1과 같이 버전을 지정할 수 있습니다.

이 접근 방식에는 여러 이점이 있습니다:

빌드 간의 관계를 명확하게 전달합니다. 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 등

시맨틱 버저닝과 사전 릴리스 식별자 사용은 권장되는 접근 방식이지만 필수는 아닙니다. 중요한 것은 빌드 간의 관계를 명확하게 전달하고 팀의 개발 프로세스에 부합하는 버전 관리 체계를 찾는 것입니다.

라이브 업데이트 롤백하기

버그가 있거나 되돌려야 하는 라이브 업데이트를 배포한 경우, 이전 빌드로 쉽게 롤백할 수 있습니다. 대시보드의 “Channels” 섹션에서:

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

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

배포 자동화하기

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

Capgo 라이브 업데이트 자동화에 대해 자세히 알아보려면 CI/CD 통합 문서를 확인하세요.

기기에 배포하기

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

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

자세한 설명은 라이브 업데이트 배포 가이드를 참조하세요. 즐거운 업데이트 되세요!

고급 채널 사용: 사용자 세분화

채널은 개발 단계 이상의 용도로 사용할 수 있습니다. 다음과 같은 기능을 가능하게 하는 사용자 세분화를 위한 강력한 도구입니다:

다양한 사용자 티어에 대한 기능 플래그
A/B 테스트
점진적 기능 롤아웃
베타 테스트 프로그램

이러한 고급 사용 사례를 구현하는 방법은 가이드에서 알아보세요: How to Segment Users by Plan and Channels for Feature Flags and A/B Testing.