채널

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

채널이 처음이신가요? 짧은 채널 둘러보기 3개를 보면서 기본 라우팅, 디바이스 자체 할당, 콘솔 오버라이드가 실제로 동작하는 모습을 확인해 보세요.

이 @capgo/capacitor-updater 메서드 setChannel() 및 unsetChannel() 이 가이드의 내용은 Android와 iOS에서만 지원됩니다. 브라우저 미리보기에서는 채널 라우팅이 변경되지 않습니다.

Capgo의 채널 선택 방식 (우선순위)

디바이스가 Capgo에 업데이트를 요청하면, 사용할 채널은 다음 순서(우선순위 높은 순)로 결정됩니다:

강제 디바이스 매핑: 디바이스 ID가 특정 채널로 명시적으로 강제된 경우 ( 기기 채널 페이지의 탭), 해당 채널이 항상 우선합니다. 강제 매핑은 console/API 오버라이드입니다. Capgo은 마지막 오버라이드 기록 후 90일이 지나면 이를 제거합니다. 참고: 콘솔 및 API 오버라이드 만료.
Cloud 오버라이드 (Dashboard 또는 Public API): Dashboard나 Public API를 통해 기기의 채널을 변경하면 해당 기기 ID에 연결된 오버라이드가 기록됩니다. 앱을 재설치해도 하지 마세요 지워지지 않습니다. 오버라이드를 삭제해야 지워집니다. 동일한 90일 보관 기간이 적용됩니다.
플러그인 setChannel() (로컬): 현재 플러그인 버전에서는, setChannel() 백엔드 검증 후 기기에 채널을 저장합니다. 이는 Dashboard 오버라이드가 아닙니다. updater 8.51.0 이상의 Android 및 iOS에서는, persistDefaultChannelOnReinstall 기본값은 true, 따라서 OS가 앱 데이터를 복구할 때만 재설치 후에도 설정이 유지되며, persistDefaultChannelOnReinstall 유지됩니다 true. unsetChannel() 로컬 설정을 명시적으로 초기화하려면 사용하세요.
Capacitor 설정 defaultChannel (테스트 빌드 기본값): 내부 / beta / 테스트 빌드의 경우 다음을 설정할 수 있습니다. defaultChannel (레거시 키 channel)를 capacitor.config.* 에 설정하면 테스트 기기가 프리릴리스 채널(예: beta, pr-123)로 시작합니다. 설정이 없으면 기기는 클라우드 기본값을 따릅니다. 프로덕션 빌드에서는 보통 이 값을 설정하지 않습니다.
Cloud Default Channel (~99%의 사용자가 사용하는 기본 전략): 거의 모든 실제 사용자가 접속하는 메인 프로덕션 채널입니다. 강제 설정, 오버라이드 또는 로컬 설정이 없는 모든 새 기기는 setChannel(), 설정 없이도 defaultChannel 이 설정을 사용합니다. 설정을 변경하면 새로운 바이너리 없이도 몇 초 만에 모든 사용자에게 배포(또는 롤백)됩니다.

왜 기본 클라우드 설정 가 주요 방식인가요:

네이티브 바이너리를 다시 빌드하거나 배포할 필요 없이 즉시 배포 또는 롤백이 가능합니다.
iOS, Android, Electron의 동작을 한 곳에서 관리합니다.
더 안전합니다: 기본 설정을 전환하기 전에 번들이 존재하는지, 설정이 올바른지 미리 확인할 수 있습니다.
변경 사항 추적 가능 (팀원이 UI/logs에서 누가 무엇을 변경했는지 확인 가능). 설계 원칙: 상위 레이어(force / override / config)는 예외적인 경우에만 사용됩니다 (특정 사용자 디버깅, QA 전환, 테스트 빌드 기본값 설정 등). 일반 사용자는 cloud default로 연결됩니다.

변경 시 기본 클라우드 설정 채널의 영향 범위 새로 만들기 다음과 같은 일반 기기:

강제되지 않음
클라우드 오버라이드를 아직 설정하지 않으셨나요?
앱 레벨의 항목이 없나요? defaultChannel 정의됨

테스트 빌드에 다음이 포함된 경우 defaultChannel: 'beta' 그리고 나중에 클라우드 기본값을 다음으로 변경할 수 있습니다. production, devices that started on beta 설정(config)을 통해 지정된 상태로 유지되며, 더 높은 우선순위의 할당이 적용되거나 해당 설정이 포함되지 않은 바이너리를 배포할 때까지 지속됩니다. defaultChannel. Force, cloud override 또는 local setChannel() 할당을 삭제해도 설정값이 제거되지 않으며, 새 binary가 배포될 때까지 해당 fallback이 유지됩니다.

다음 작업 중 하나를 수행하지 않는 한, 디바이스는 현재 채널을 유지합니다:

다른 채널로 강제 전환 (console 또는 Public API).
dashboard 또는 Public API에서 cloud override 변경.
호출하세요 setChannel() (현재 plugin 버전에서의 local 할당).
현재 채널을 삭제 또는 아카이브 (이후 다음 체크 시 우선순위에 따라 다시 fallback 적용).
console/API override의 90일 만료 대기.
호출하세요 unsetChannel() local setChannel() 할당을 해제하려면 사용하세요. 이는 console/API override나 앱 설정된 defaultChannel; 다시 일반 우선순위가 적용됩니다.
앱을 재설치하면 이전 updater 버전이거나 앱 데이터가 복구되지 않은 경우 로컬 할당이 해제될 수 있습니다. Android 및 iOS의 updater 8.51.0 이상 버전에서는, persistDefaultChannelOnReinstall 기본값은 true, 따라서 복구된 앱 데이터는 이 옵션이 유지되는 동안에만 로컬 선택 사항을 보존할 수 있습니다. trueConsole/API 재정의(override)에는 영향을 받지 않습니다.

특정 플랫폼에 대해 채널이 비활성화된 경우(iOS / Android / Electron 토글 참조), 해당 채널이 선택될 상황이었다면 선택을 건너뛰고 다음 규칙으로 넘어갑니다.

참고: 설정 defaultChannel 을 변경하려면 새로운 binary가 필요합니다. 일반적인 운영 제어용이 아닌 테스트/QA 용도로만 신중하게 사용하세요.

Capacitor 설정 예시

// Example: a TestFlight or internal QA build defaults to the beta channel.
const config = {
  plugins: {
    CapacitorUpdater: {
      defaultChannel: 'beta', // Test build default. Omit in production so users attach to cloud default.
      // legacy key: channel
    },
  },
};
export default config;

나중에 대시보드 기본값을 다음과 같이 변경하더라도, production이미 다른 채널에 연결된 기기(config, override 또는 force 사용)는 자동으로 이동하지 않습니다. 새로 연결된 기기나 override/force 설정을 해제한 기기만 변경 사항이 적용됩니다.

채널 관리

먼저 채널 페이지를 살펴보겠습니다. 다음 순서로 접속할 수 있습니다. 앱을 클릭한 뒤, 그 다음, channels 탭을 클릭하세요..

채널 생성하기

보시는 것처럼 오른쪽 하단에 플러스(+) 버튼이 있습니다. (1 (이미지 참조) 클릭하면 새 채널을 생성할 수 있는 모달이 열립니다.

클릭한 후에는 Add 목록에 새 채널이 나타납니다.

misconfigured는 무슨 뜻인가요?

때때로 채널 설정이 유효하지 않을 수 있습니다. 이 경우 큰 경고 메시지가 표시되며 Misconfigured 열에 다음과 같이 표시됩니다 Yes 하나 이상의 채널에 대해. 자세한 내용은 다음에서 확인하세요 여기

채널 삭제하기

웹 앱에서 채널을 삭제하려면, 채널 앱 탭을 열고 해당 채널 행을 찾으세요. 작업 열에서 휴지통 아이콘을 클릭한 다음, 삭제 확인 대화 상자에서 클릭하세요.

휴지통 아이콘이 보이지 않는다면, 해당 앱에 대한 channel.delete 권한이 없는 것입니다. 조직 또는 앱 관리자에게 채널 삭제 권한이 있는 역할을 요청하거나, 권한이 있는 API 키를 사용하여 채널을 삭제하세요:

npx @capgo/cli@latest channel delete <channel-name> <app-id>

조직 및 앱에 종속된 앱 미리보기 key can atomically delete only the non-public preview channel and bundle it created with channel delete <preview-channel> <app-id> --delete-bundle기존의 기본/메인 채널, 다른 프리뷰 키의 채널 또는 다른 키의 번들은 변경하거나 삭제할 수 없습니다. 자세한 내용은 API 키 의 최소 권한 설정 섹션을 참조하세요.

채널 관리

채널 이름을 클릭하면 채널 페이지가 열립니다. 모달이 아닌 탭이 포함된 전체 페이지입니다.

채널 탭

대시보드: 이 채널의 현재 번들 채택률 및 설치 통계입니다.
정보: 아래의 채널 설정과 점진적 배포 및 Test Update API 기능이 포함됩니다.
기기: 콘솔에서 생성된 강제 매핑 또는 Public API만 표시됩니다. 현재 채널을 사용하는 모든 기기나 사용했던 기기를 모두 나열하지는 않습니다. setChannel(). 참조 콘솔 및 API 오버라이드 만료.
히스토리: 이 채널의 설정 및 번들 변경 사항입니다.
미리보기: 연결된 bundle을 브라우저 및 네이티브 환경에서 미리 볼 수 있습니다. 미리 보기를 활성화하려면 앱 정보 먼저.

정보 설정

해당 정보 탭에 머무르세요. 설정 순서는 다음과 같습니다:

먼저, 기본 다운로드 채널 은(는) 토글이 아닌 상태 배지입니다. 활성 이 채널이 새 기기의 클라우드 기본값이라는 뜻입니다. 클릭하여 App 설정에서 관리 기본값을 변경하세요. 앱 정보플랫폼별 기본값(iOS용, Android용, Electron용)은 같은 섹션을 참조하세요.

두 번째는 IOS 설정입니다. 이 값이 false이면 iOS 기기에서 이 채널의 업데이트를 다운로드할 수 없습니다.

세 번째는 Android 설정입니다. 이 값이 false이면 Android 기기에서 이 채널의 업데이트를 다운로드할 수 없습니다.

네 번째는 Electron 설정입니다. 이 값이 false이면 Electron 앱에서 이 채널의 업데이트를 다운로드할 수 없습니다.

다섯 번째는 Disable auto downgrade under native 설정입니다. 이 값이 true이면 네이티브 버전에서 다운그레이드하는 것이 불가능해집니다. 즉, 이미 1.2.0 버전을 App Store 또는 Play Store에 업로드한 상태에서 채널 버전을 1.1.0 로 설정하려고 하면 업데이트(다운그레이드)가 실패합니다.

여섯 번째는 Disable auto update입니다. 이 설정은 상당히 복잡하므로 자세한 내용은 확인할 수 있습니다. 여기

일곱 번째는 Download format 설정입니다. 디바이스가 전체 zip을 다운로드할지, 변경된 delta 파일만 다운로드할지, 아니면 둘 중 최적의 방식을 선택할지 결정합니다. 참고하세요. 다운로드 형식.

여덟 번째는 Allow development build입니다. 이 값이 true이면 development build에서 이 채널의 업데이트를 다운로드할 수 있습니다. 그렇지 않으면 prod false로 설정하면 거부됩니다. 주로 테스트 용도로 사용됩니다.

아홉 번째는 Allow production build입니다. 이 설정이 false이면 프로덕션(스토어) 빌드가 이 채널로부터 업데이트를 받지 못합니다. 실제 사용자가 이용하는 채널이라면 이 설정을 켜두세요.

열 번째는 Allow Emulators입니다. 이 설정이 false이면 Capgo에서 에뮬레이터로부터 오는 모든 업데이트 요청을 차단합니다. 주로 테스트 목적으로 사용됩니다.

열한 번째는 Allow physical devices입니다. 이 설정이 false이면 Capgo에서 실제 폰이나 태블릿으로부터 오는 업데이트 요청을 거부합니다. 프로덕션 채널에서는 이 설정을 켜두세요.

열두 번째는 Allow devices to self dissociate/associate입니다. 이 설정이 true이면 setChannel 메서드를 Android 및 iOS에서 사용할 수 있습니다. 만약 false로 설정된 상태에서 해당 채널로 setChannel 을 호출하려고 하면 호출에 실패합니다.

API 테스트 업데이트

하단의 정보 탭을 확장하면 API 테스트 업데이트. Capgo에 이 채널의 샘플 디바이스를 대상으로 하는 curl 명령어가 표시됩니다. /updates 이 채널의 샘플 디바이스용입니다.

캐싱으로 인해 API에 변경 사항이 반영되기까지 최대 60초가 걸릴 수 있습니다. 채널 테스트가 불가능할 경우 콘솔에 경고가 표시됩니다: 해당 채널에는 최소 하나 이상의 플랫폼(iOS 또는 Android), production build, 실제 디바이스가 필요하며, 기본 다운로드 채널이거나 디바이스 self-assignment를 허용해야 합니다.

업데이트 알림 보내기

연결된 bundle을 변경하면 콘솔에서 다음을 요청할 수 있습니다: 업데이트 알림 보내기. 이를 통해 silent push를 큐에 추가하여 해당 채널의 기기들이 즉시 새 bundle을 확인하도록 합니다. 먼저 앱의 Notifications 탭에서 Android 및 iOS push 자격 증명을 설정하세요.

콘솔 및 API 오버라이드 만료

강제 매핑 및 Dashboard/Public API 채널 override는 제거됩니다 90일 마지막 override 쓰기 이후에 발생합니다. 마지막 기기 체크인은 해당 타이머를 초기화하지 않습니다. 이 정리 작업 후에도 유지되는 할당을 설정하려면, defaultChannel Capacitor config에 설정하거나(재설치 시 유지되며, 변경하려면 새 binary 필요) 또는 setChannel() Android 또는 iOS 앱에서 다음을 사용하여 호출하세요 @capgo/capacitor-updater 5.34.0+, 6.34.0+, 7.34.0+, 또는 8.0.0+ 플러그인의 major version용입니다. 이 버전들은 할당 정보를 로컬에 저장하므로 90일 정리 대상에서 제외됩니다. 이전 버전은 동일한 정리 대상인 백엔드 override를 작성합니다. updater 8.51.0 이상의 Android 및 iOS에서는, persistDefaultChannelOnReinstall 기본값은 true, 따라서 운영 체제가 앱 데이터를 복원할 때만 로컬 선택도 재설치 후 유지될 수 있고 persistDefaultChannelOnReinstall 유지됩니다 true를 통한 재설치는 persistDefaultChannelOnReinstall: false 앱 데이터가 복원되어도 해당 로컬 선택을 지울 수 있습니다. 사용하세요 unsetChannel() 해당 로컬 선택을 명시적으로 지우려면.

Capgo 채널의 Devices 탭에서 Override retention 팝오버가 표시된 모습: 콘솔 override는 90일 후 만료됩니다 — 채널 Devices 탭의 Override retention 설정입니다. 채널에 device ID를 강제로 지정할 때도 동일한 안내가 표시됩니다.

이는 ...와는 별개입니다: 디바이스 인벤토리 보관 주기. Inventory는 Capgo에 90일 동안 연결되지 않은 디바이스를 제거합니다. Override cleanup은 디바이스가 여전히 활성 상태여도 매핑을 제거합니다. 자세한 내용: Console 및 API override는 90일 후 만료됩니다.

다운로드 형식

채널을 열고 해당 정보 탭에 머무르세요. 다운로드 형식 는 설정 목록의 Disable auto update 아래에 있습니다.

이 설정은 해당 채널의 디바이스가 업데이트를 확인할 때 Capgo가 전송할 형식을 결정합니다. Zip + delta는 특정 형식을 강제해야 하는 경우가 아니라면 그대로 두세요.

콘솔의 레이블	CLI / API 값	다운로드 방식
Zip + delta (기본값)	`all`	각 디바이스는 지원 가능한 최적의 패키지를 받습니다. Delta를 지원하는 플러그인 버전을 사용하는 디바이스는 번들에 delta 파일이 있는 경우 변경된 delta 파일만 다운로드합니다. Delta를 지원하지 않는 구버전 플러그인을 사용하거나 delta 파일 없이 업로드된 번들의 경우에만 전체 zip 파일을 다운로드합니다.
Full zip만 가능	`zip`	delta 파일이 존재하더라도 모든 디바이스가 전체 번들 zip 파일을 다운로드합니다.
Delta 전용	`delta`	변경된 delta 파일만 다운로드합니다. Delta를 지원하지 않는 구버전 플러그인을 사용하는 디바이스는 번들에 zip 파일이 있는 경우 전체 zip 파일을 받습니다.
스토어 빌드에서 Full zip만 제공	`zip_from_builtin`	디바이스가 스토어 빌드 버전을 유지하는 동안에만 Full zip을 제공합니다. 첫 live update 이후에는 Capgo이 다시 zip + delta 방식을 제공합니다.
스토어 빌드에서 Delta만 제공	`delta_from_builtin`	디바이스가 스토어 빌드 버전을 유지하는 동안에만 Delta를 제공합니다. 첫 live update 이후에는 Capgo이 다시 zip + delta 방식을 제공합니다.

사용하면 Zip + delta는, 일부 전체 zip 다운로드가 발생하는 것은 정상입니다. 이는 Delta를 지원하지 않는 이전 Native Build 버전의 플러그인을 사용하는 기기에서 발생합니다(해당 메이저 버전의 5.10.0, 6.25.0, 또는 7.0.35 이하 버전). 델타 업데이트.

이 스토어 빌드 는 Capgo 업데이트가 적용되기 전, App Store 또는 Play Store 바이너리에 포함된 웹 에셋을 의미합니다. from store build only 모드를 사용하면 스토어 빌드 이후 첫 업데이트는 전체 zip 또는 delta로만 제한하고, 이후 업데이트부터는 두 방식 모두 사용하도록 설정할 수 있습니다.

Capgo는 zip 전용 채널과 delta 전용 번들을 서로 매칭하지 않으며, 그 반대의 경우도 마찬가지입니다. 콘솔, CLI, 그리고 API 채널 저장을 거부하고 누락된 패키지를 upload 하거나 모드를 전환하라는 메시지를 표시합니다.

CLI에서 동일한 값을 설정할 수 있습니다. 채널이 이미 존재해야 합니다:

npx @capgo/cli@latest channel set production com.example.app --update-package zip

유효한 값: all, zip, delta, zip_from_builtin, delta_from_builtin.

단계적 배포

채널 정보 탭에는 다음이 포함됩니다: 점진적 롤아웃 다음이 포함된 섹션: 롤아웃 대상 및 Stable 폴백, 배포 대상 변경, 비율 적용, 및 작업 롤아웃 완료, 롤아웃 롤백, rollout 활성화, Rollout 비활성화, Rollout 일시 중지, 그리고 Rollout 재개.

Capgo 채널의 점진적 롤아웃 제어 — 채널 정보 탭 상단에서 점진적 배포(Progressive rollout)를 제어할 수 있습니다.

먼저 단계적 배포 관련 가이드를 읽어보세요. 해당 가이드에는 업로드 라우팅(자동 (권장) / 롤아웃 대상 / stable 교체; CLI --stable / API target: "stable" 로 덮어쓰기), 이 채널은 점진적 배포(progressive rollout)를 사용합니다 bundle-link 대화 상자 및 안전한 워크플로우를 제공합니다 Observe 및 로그 인사이트.

Channels에서 계속하기

사용 중이라면 채널 채널 라우팅과 단계적 배포를 계획하려면, 다음을 연결하세요: 채널 Channels의 구현 세부 사항은 다음을 참고하세요: 채널 Channels의 구현 세부 사항은 다음을 참고하세요: Beta Testing 솔루션 Beta Testing Solution의 제품 워크플로우를 위해, 버전 타겟팅 솔루션 Version Targeting Solution의 제품 워크플로우를 위해, 그리고 Capgo 환경 베스트 프랙티스: 하나의 Mobile App ID로 스테이징하기 Capgo Environment Best Practices: Staging with One Mobile App ID의 실무 사례를 위해.