Page/area: Capgo marketing website. Role: Short UI label or navigation item. Seen in: component doc/SignupCta.astro, component Hero.astro. Message key `hero_title_line2` (Hero Title Line2).
설치 단계와 이 플러그인의 전체 마크다운 가이드를 포함한 설정 프롬프트를 복사하세요.
설치, 동기화, 소스 가이드를 포함합니다. Ionic AppFlow와 유사한 접근 방식과 같습니다.이것은 업데이트 관리가 단순화되고 빠른 배포가 가능하며 호환성 문제를 방지하는 것을 보장합니다.
개요
개요 제목Capgo의 버전 대상 시스템은 사용자에게:
- 네이티브 앱 버전에 따라 호환 가능한 업데이트를 자동으로 제공합니다. 자동으로 호환 가능한 업데이트를 사용자에게 제공합니다.
- 버전 타겟팅 버전 타겟팅
- 다중 앱 버전 관리 복잡한 논리를 사용하지 않고 여러 앱 버전을 동시에 관리
- 특정 사용자 그룹으로 업데이트를 무중단으로 배포 버전 타겟팅의 중요성 (특히 AppFlow 사용자에게)
버전 타겟팅의 중요성 (특히 AppFlow 사용자에게)
Ionic AppFlow와 익숙한 경우Ionic AppFlow를 사용하는 경우, 사용자가 호환되지 않는 업데이트만을 받도록 보장하는 것이 매우 중요합니다. AppFlow는 __CAPGO_KEEP_0__ 패키지를 __CAPGO_KEEP_1__ 네이티브 앱 버전과 자동으로 매핑하여 호환되지 않는 자바스크립트가 더 오래된 네이티브 __CAPGO_KEEP_1__ 버전으로 전달되는 것을 방지했습니다. __CAPGO_KEEP_0__은 동일한 안전 보장 조치를 제공합니다., you know how critical it is to ensure users receive only compatible updates. AppFlow automatically matched live update bundles to native app versions, preventing incompatible JavaScript from being delivered to older native code.
Capgo은 동일한 안전 보장 약정을 제공합니다.Live Update
- More detailed control over version matching
- 다양한 전략 (채널, semver, 원본 제약)
- 버전 분포에 대한 더 나은 시야
- API 및 CLI 관리와 함께 API
이 접근 방식은 특히 다음과 같은 경우에 유용합니다.
- 사용자가 앱의 다른 주요 버전을 사용하고 있습니다 (예: v1.x, v2.x, v3.x)
- 파괴적인 변경 사항을 출시하는 동안 뒤로compatibility를 유지해야 하는 경우
- 새로운 번들을 사용하여 더 오래된 네이티브 code를 깨뜨리지 않도록 원치 않는 경우
- 사용자를 하나의 버전에서 다른 버전으로 점진적으로 이동하는 경우
- AppFlow에서 마이그레이션하고자 하는 경우 업데이트 안전성을 유지하고자 하는 경우
작동 방식
“작동 방식”Capgo은 사용자와 호환 가능한 업데이트와 매칭하기 위해 다중 층급 접근 방식을 사용합니다:
- 자연어 버전 제한: 호환되지 않는 자연어 버전으로부터 패키지를 배달하는 것을 방지합니다
- 채널 기반 라우팅: 다중 앱 버전을 다른 업데이트 채널로 라우팅합니다
- 의미 버전 제어: 주요/소수/패치 경계를 넘어 업데이트를 자동으로 차단합니다
- 장치 수준 오버라이드: 특정 장치 또는 사용자 그룹을 대상으로합니다
버전 매칭 흐름
버전 일치 흐름graph TD A[User Opens App] --> B{Check Device Override} B -->|Override Set| C[Use Override Channel] B -->|No Override| D{Check local plugin channel} D -->|setChannel value| E[Use local setChannel channel] D -->|No local channel| F{Check defaultChannel in App} F -->|Has defaultChannel| G[Use App's defaultChannel] F -->|No defaultChannel| H[Use Cloud Default Channel] C --> I{Check Version Constraints} E --> I G --> I H --> I I -->|Compatible| J[Deliver Update] I -->|Incompatible| K[Skip Update]채널 기반 버전 라우팅 전략 1
채널 기반 버전 라우팅 전략 1권장하는 방법 권장하는 방법 관리하는 주요 버전 업데이트 및 깨진 변경 사항
예시 시나리오
앱 v1.x- App v1.x 채널
productionchannel - App v2.x (50,000 사용자와 버그 수정)
v2채널 - App v3.x (10,000 베타 사용자)
v3채널
Implementation
ImplementationStep 1: 각 주요 버전의 채널을 구성하십시오.
Copy to clipboard// capacitor.config.ts for version 1.x buildsimport { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = { appId: 'com.example.app', appName: 'Example App', plugins: { CapacitorUpdater: { autoUpdate: 'atBackground', defaultChannel: 'production', // or omit for default } }};
export default config;// capacitor.config.ts for version 2.x buildsconst config: CapacitorConfig = { appId: 'com.example.app', appName: 'Example App', plugins: { CapacitorUpdater: { autoUpdate: 'atBackground', defaultChannel: 'v2', // Routes v2 users automatically } }};// capacitor.config.ts for version 3.x buildsconst config: CapacitorConfig = { appId: 'com.example.app', appName: 'Example App', plugins: { CapacitorUpdater: { autoUpdate: 'atBackground', defaultChannel: 'v3', // Routes v3 users automatically } }};2단계: 채널 만들기
2단계: 채널 만들기 섹션# Create channels for each major versionnpx @capgo/cli channel add productionnpx @capgo/cli channel add v2npx @capgo/cli channel add v3
# Enable self-assignment so apps can switch channelsnpx @capgo/cli channel set production --self-assignnpx @capgo/cli channel set v2 --self-assignnpx @capgo/cli channel set v3 --self-assign3단계: 버전별 패키지 업로드
3단계: 버전별 패키지 업로드 섹션# For v1.x users (from v1-maintenance branch)git checkout v1-maintenancenpm run buildnpx @capgo/cli bundle upload --channel production
# For v2.x users (from v2-maintenance or main branch)git checkout mainnpm run buildnpx @capgo/cli bundle upload --channel v2
# For v3.x users (from beta/v3 branch)git checkout betanpm run buildnpx @capgo/cli bundle upload --channel v3혜택
혜택 섹션- Zero code 변경 - 채널 라우팅이 자동으로 발생합니다
- 분리 - 각 버전에는 자신의 업데이트 PIPELINE이 있습니다
- flexible targeting - 특정 버전 그룹에 업데이트를 푸시합니다
- 안전한 롤아웃 - 불일치 버전에는 절대 깨지는 변경 사항이 없습니다
전략 2: 의미적 버전 제어
Strategy 2: Semantic Versioning ControlsCapgo의 내장 semantic versioning controls 버전 경계를 넘지 않는 업데이트를 방지하기 위해
주요 버전을 넘어 업데이트를 자동으로 비활성화
Terminal 창# Create a channel that blocks major version updatesnpx @capgo/cli channel add stablenpx @capgo/cli channel set stable --disable-auto-update major이 설정은 의미다:
- 앱 버전 1.2.3 업데이트를 받을 수 있습니다. 1.9.9
- 업데이트를 받을 수 있습니다. Not 버전을 자동으로 받지 않습니다. 2.0.0 자동으로 받지 않습니다.
- 기존 네이티브 code에서 발생하는 변경 사항을 막습니다.
- 버전 비교는 네이티브 베이스 라인으로 전송된 것을 사용합니다.
version_build
세부 조작 옵션
세부 조작 옵션 섹션# Block target bundles outside the native major.minor line (1.2.x won't get 1.3.0)npx @capgo/cli channel set stable --disable-auto-update minor
# Block target bundles outside the exact native MAJOR.MINOR.PATCH core (1.2.3 won't get 1.2.4)npx @capgo/cli channel set stable --disable-auto-update patch
# Allow all updatesnpx @capgo/cli channel set stable --disable-auto-update none전략 3: 원본 버전 제한
Strategy 3: Native Version Constraints__CAPGO_KEEP_0__의 경우, 각 번들에 최소 native 앱 버전 (min_update_version)을 지정하여 Capgo이 최신 버전의 native 바이너리만을 기기에 전달하도록 합니다.
이것은 채널 메타데이터 strategy (--disable-auto-update metadata)을 사용합니다. 또는 --min-update-version or --auto-min-update-version 업로드 시. --native-version CLI 플래그가 없습니다.
채널에서 메타데이터 목표 설정을 활성화하십시오.
“채널에서 메타데이터 목표 설정을 활성화하십시오.”라는 제목의 섹션# one-time: require min_update_version metadata on uploads to this channelnpx @capgo/cli@latest channel set production --disable-auto-update metadata최소 네이티브 버전 설정
업로드 시, 최소 네이티브 버전을 설정하십시오.섹션 제목: “업로드 시, 최소 네이티브 버전을 설정하십시오.”
# This bundle requires native version 2.0.0 or highernpx @capgo/cli@latest bundle upload \ --channel production \ --min-update-version "2.0.0"업로드할 번들에 대해, 받을 수 있는 최소 네이티브 버전을 지정하십시오: " 또는 네이티브 패키지 호환성에서 Capgo이 바닥을 설정하십시오:
npx @capgo/cli@latest bundle upload \ --channel production \ --auto-min-update-version사용 사례
사용 사례-
새로운 네이티브 플러그인 필요
터미널 창 # Bundle needs Camera plugin added in v2.0.0npx @capgo/cli@latest bundle upload \--channel production \--min-update-version "2.0.0" -
Live Update API 변경
터미널 창 # Bundle uses new Capacitor 6 APIsnpx @capgo/cli@latest bundle upload \--channel production \--min-update-version "3.0.0" -
네이티브 __CAPGO_KEEP_0__ 변경 사항
터미널 창 # one-time: enable metadata gating on betanpx @capgo/cli@latest channel set beta --disable-auto-update metadata# Test bundle only on latest native versionnpx @capgo/cli@latest bundle upload \--channel beta \--min-update-version "2.5.0"
점진적인 마이그레이션
전략 4: 자동 다운그레이드 방지전략 4: 자동 다운그레이드 방지
채널 설정에서 활성화
채널 설정에서 활성화Capgo 대시보드에서:
- 로 이동하세요 채널 채널을 선택하세요
- 활성화 자연스러운 환경에서 자동으로 버전 다운그레이드 차단
- 원본 버전으로 자동 다운그레이드 차단
또는 CLI를 통해
npx @capgo/cli@latest channel set production --no-downgrade버전 목표
버전 목표: 예시- 사용자의 기기: 네이티브 버전 1.2.5
- 채널 번들: 버전 1.2.3
- 결과: 업데이트가 차단됨 (다운그레이드일 경우)
이것은 유용할 때:
- 사용자가 앱 스토어에서 최신 버전을 수동으로 설치한 경우
- 보안 패치의 최신 버전을 항상 사용하도록 보장해야 할 때
- 회귀 버그를 방지하고 싶을 때
기기 수준 목표 5:
기기 수준 목표 5:특정 장치 또는 사용자 그룹에 대한 채널 할당을 강제로 변경합니다.
테스트를 위해 특정 버전 강제로 사용
테스트 버전 강제 사용import { CapacitorUpdater } from '@capgo/capacitor-updater'
// Force beta testers to use v3 channelasync function assignBetaTesters() { const deviceId = await CapacitorUpdater.getDeviceId()
// Check if user is beta tester if (isBetaTester(userId)) { await CapacitorUpdater.setChannel({ channel: 'v3' }) }}페이지/영역: Capgo 마케팅 웹사이트. 역할: UI 레이블. 표시되는 곳: page agents/[slug].astro. 메시지 키 `agents_page_copy_label` (Agents Page Copy Label).
장치 오버라이드Capgo 대시보드에서
- Go to 가기 장치
- Click → 장치 찾기 또는 버전 설정
- 특정 채널 또는 버전으로 오버라이드
- 기기에서 업데이트를 받는 오버라이드 소스
완전한 AppFlow-Style 워크플로
Complete AppFlow-Style Workflow다음 예제는 모든 전략을 combination하는 완전한 예제입니다.
1. 초기 설정 (App v1.0.0)
1. 초기 설정 (App v1.0.0)# Create production channel, then enable metadata min-version gatingnpx @capgo/cli@latest channel add productionnpx @capgo/cli@latest channel set production \ --disable-auto-update metadata \ --no-downgradeconst config: CapacitorConfig = { plugins: { CapacitorUpdater: { autoUpdate: 'atBackground', defaultChannel: 'production', } }};2. 앱 버전 2.0.0에서 발생하는 변경 사항
2. 앱 버전 2.0.0에서 발생하는 변경 사항 섹션# Create v2 channel for new versionnpx @capgo/cli@latest channel add v2npx @capgo/cli@latest channel set v2 \ --disable-auto-update metadata \ --no-downgrade \ --self-assign
# Create git branch for v1 maintenancegit checkout -b v1-maintenancegit push origin v1-maintenance// capacitor.config.ts for v2.0.0const config: CapacitorConfig = { plugins: { CapacitorUpdater: { autoUpdate: 'atBackground', defaultChannel: 'v2', // New users get v2 channel } }};2. 두 버전 모두에 업데이트를 푸시합니다
2. 두 버전 모두에 업데이트를 푸시하는 방법 섹션# Update v1.x users (bug fix)git checkout v1-maintenance# Make changesnpx @capgo/cli@latest bundle upload \ --channel production \ --min-update-version "1.0.0"
# Update v2.x users (new feature)git checkout main# Make changesnpx @capgo/cli@latest bundle upload \ --channel v2 \ --min-update-version "2.0.0"4. 버전 분포 모니터링
4. 버전 분포 모니터링 섹션Capgo 대시보드를 사용하여:
- 버전 v1과 v2 사용자 수
- 버전별 패키지 채택률
- 버전별 오류 및 충돌률
5. 오래된 버전 폐기
5. 오래된 버전 폐기 섹션버전 v1 사용량이 임계값 이하로 떨어지면:
# Stop uploading to production channel# Optional: Delete v1 maintenance branchgit branch -d v1-maintenance
# Move all remaining users to default# (They'll need to update via app store)채널 우선순위
채널 우선순위여러 채널 설정이 존재할 때, Capgo은 다음 우선순위를 사용합니다.
- 기기 우선순위 (대시보드 또는 API) - 우선순위가 가장 높고 기기 우선순위 UI에서 표시됩니다.
- 로컬 플러그인 채널 via
setChannel()- 기기에서만 저장되고 Device Override UI에서 표시되지 않습니다. - defaultChannel capacitor.config.ts
- 기본 채널 (클라우드 설정) - 우선순위가 가장 낮음
최선의 방법
제목: 최선의 방법1. 항상 Major Versions에 대해 defaultChannel을 설정합니다.
제목: 1. 항상 Major Versions에 대해 defaultChannel을 설정합니다.// ✅ Good: Each major version has explicit channel// v1.x → production// v2.x → v2// v3.x → v3
// ❌ Bad: Relying on dynamic channel switching// All versions → production, switch manually2. 의미적 버전 관리 사용
2. 의미적 버전 관리 사용# ✅ Good1.0.0 → 1.0.1 → 1.1.0 → 2.0.0
# ❌ Bad1.0 → 1.1 → 2 → 2.53. 별도 branch 유지
3. 별도 branch 유지# ✅ Good: Separate branches per major versionmain (v3.x)v2-maintenance (v2.x)v1-maintenance (v1.x)
# ❌ Bad: Single branch for all versions4. 배포 전 테스트
4. 배포 전 테스트# one-time: create beta and enable metadata gating# (production is set up in the complete workflow above)npx @capgo/cli@latest channel add betanpx @capgo/cli@latest channel set beta --disable-auto-update metadata
# Test on beta channel firstnpx @capgo/cli@latest bundle upload \ --channel beta \ --auto-min-update-version
# Monitor for issues, then promote to productionnpx @capgo/cli@latest bundle upload \ --channel production \ --auto-min-update-version5. 버전 분포 확인
버전 분포 확인을 위해 주기적으로 대시보드를 확인하세요.사용자가 최신 네이티브 버전으로 업그레이드하고 있는지 확인하세요.
- 고장난 버전이 여전히 높은 트래픽을 받고 있는지 확인하세요.
- 구 버전을 사용하는 채널을 폐기해야 하는지 확인하세요.
- Ionic AppFlow와의 비교
Ionic AppFlow로 이전하는 팀에게는 __CAPGO_KEEP_0__의 버전 대상 설정이 어떻게 다른지 설명해 드립니다.
Ionic AppFlowIonic AppFlow Ionic AppFlowCapgo의 버전 대상 설정은 다음과 같습니다.
| 기능 | Ionic AppFlow | Capgo |
|---|---|---|
| 버전 기반 라우팅 | 자연스러운 버전 기반 | 자연스러운 버전을 통해 defaultChannel + 여러 전략 |
| Semantic 버전 | 기본 지원 | 고급으로 --disable-auto-update (주/부/정) |
| 자연스러운 버전 제약 | 수동 구성 | 내장 --min-update-version / --auto-min-update-version 메타데이터 채널과 함께 |
| 채널 관리 | 웹 UI + CLI | 웹 UI + CLI + API |
| 장치 오버라이드 | 장치 수준 제한 | Full control via Dashboard/API |
| 다운그레이드 방지 | 예 | 예 --no-downgrade |
| 다중 버전 유지 | 수동 브랜치/채널 관리 | 채널 우선 자동화 |
| 자체 호스팅 | 아니요 | 예 (전체 제어) |
| 버전 분석 | 기본 | 세부 버전별 메트릭 |
문제 해결
문제 해결업데이트를 받지 않는 사용자
업데이트를 받지 않는 사용자다음 사항을 확인하세요.
-
채널 assignments: 디바이스가 올바른 채널에 있는지 확인하세요.
const channel = await CapacitorUpdater.getChannel()console.log('Current channel:', channel) -
버전 제약 조건: 번들에 원시 버전 요구 사항이 있는지 확인하세요.
- 대시보드 → 패키지 → "자연어 버전" 열을 확인하세요
-
Semver 설정: 채널의
disable-auto-update설정터미널 창 npx @capgo/cli channel list -
컨텍스트: Capgo 마케팅 웹사이트. 역할: UI 레이블. 위치: 페이지 agent/[slug].astro. 메시지 키 `agents_page_copy_label` (Agent 페이지 복사 레이블).디바이스 오버라이드
- : 디바이스가 수동 오버라이드가 있는지 확인하세요
대시보드 → 디바이스 → 디바이스 검색 → 채널/버전 확인
잘못된 버전으로 패키지 전달- 잘못된 버전으로 패키지 전달 섹션 제목입니다. : 올바른 채널을 확인하세요.
capacitor.config.ts - 업로드 된 패키지 확인: 올바른 채널에 업로드 된 배포본을 확인하세요.
- Live Update 버전 대상 설정: 확인
--min-update-version(또는--auto-min-update-versioncontext--disable-auto-update metadata
: 업로드 된 배포본이 설정된 채널이 사용하는 버전을 확인하세요.
Breaking Changes Affecting Old Versions- Section titled “Breaking Changes Affecting Old Versions”Immediate Fix
- : 영향을 받은 기기에서 안전한 배포본으로 업데이트하세요.
- 장기 수정: 버전별 채널을 만들고 별도의 branch를 유지합니다.
- 예방: 대표적인 기기에서 업데이트를 테스트하고 롤아웃하기 전에 항상 업데이트를 테스트합니다.
Ionic AppFlow에서 마이그레이션
Ionic AppFlow에서 마이그레이션하는 경우: __CAPGO_KEEP_0__에서 Ionic AppFlow와 유사하게 동작하며, 향상된 유연성을 제공합니다. 개념 매핑, 버전 대상 설정은 Capgo에서 Live Update와 유사하게 작동하며 유연성이 향상되었습니다.
Ionic AppFlow에서
__CAPGO_KEEP_0__| 장기 수정 | Capgo 동등한 개념 | 참고 |
|---|---|---|
| 배포 채널 | Capgo 채널 | 동일한 개념, 더 강력한 기능 |
| 자연스러운 버전 잠금 | --min-update-version / --auto-min-update-version | 더 세분화된 제어 |
| 채널 우선순위 | 채널 우선순위 (override → 클라우드 → 기본) | 더 투명한 우선순위 |
| 배포 대상 | 채널 + semver 제어 | 다양한 전략이 제공됩니다. |
| 제품 채널 | production 채널 (또는任意 이름) | flexible한 이름 |
| Git 기반 배포 | CLI branch에서 번들 업로드 | 동일한 워크플로우 |
| 자동 버전 일치 | defaultChannel + 버전 제약조건 | 여러 전략을 지원하는 업데이트 |
AppFlow 사용자용 주요 차이점
제목 "AppFlow 사용자용 주요 차이점"- 더욱 많은 제어: Capgo은 여러 전략 (채널, semver, 네이티브 버전) 을 제공하여 combination 할 수 있습니다
- 더 나은 시각: 버전 분포 및 호환성 문제를 보여주는 Dashboard
- API 접근: 버전 대상에 대한 완전한 프로그래밍 제어
- 자체 호스팅: 동일한 버전 로직을 사용하여 자체 업데이트 서버를 실행하는 옵션
이동 단계
이동 단계 섹션- AppFlow 채널을 맵핑하세요 Capgo 채널 (일반적으로 1:1)으로
- 버전 관리
defaultChannel에서capacitor.config.ts각 메이저 버전 - 버전 관리 규칙을 설정 버전 경계에서 자동 차단을 원하신다면
- 버전별 패키지를 업로드 using
--min-update-version(채널은 메타데이터 전략을 사용해야 함) - 버전 분포를 모니터링 에서 Capgo 대시보드
고급 패턴
버전별로 점진적인 출시버전별 기능 플래그
버전별 A/B 테스트// Gradually migrate v1 users to v2async function migrateUsers() { const deviceId = await CapacitorUpdater.getDeviceId() const rolloutPercentage = 10 // Start with 10%
// Hash device ID to get deterministic percentage const hash = hashCode(deviceId) % 100
if (hash < rolloutPercentage) { // User is in rollout group - migrate to v2 await CapacitorUpdater.setChannel({ channel: 'v2' }) }}고급 패턴
버전별로 점진적인 출시// Enable features based on native versionasync function checkFeatureAvailability() { const info = await CapacitorUpdater.getDeviceId() const nativeVersion = info.nativeVersion
if (compareVersions(nativeVersion, '2.0.0') >= 0) { // Enable features requiring v2.0.0+ enableNewCameraFeature() }}버전별 기능 플래그
버전별 A/B 테스트// Run A/B tests within same native versionasync function assignABTest() { const nativeVersion = await getNativeVersion()
if (nativeVersion.startsWith('2.')) { // Only A/B test on v2 users const variant = Math.random() < 0.5 ? 'v2-test-a' : 'v2-test-b' await CapacitorUpdater.setChannel({ channel: variant }) }}개요
개요Capgo은 여러 버전별 업데이트 전달을 위한 전략을 제공합니다.
- 채널 기반 라우팅: 자동으로 메이저/마이너/패치 버전 경계를 넘지 않도록 버전 분리
defaultChannel - Semantic Versioning: 메이저/마이너/패치 버전 경계를 넘지 않도록 업데이트를 방지
- 네이티브 버전 제약: 네이티브 버전의 최소 버전을 요구
- 다운그레이드 방지: 새로운 네이티브 버전으로 업데이트된 버전을 전달하지 않음
- 기기 설정: 테스트 및 목표 설정을 위한 수동 제어
이 전략들을结合하면 AppFlow-style 자동 업데이트 전달과 더 많은 유연성과 제어가 가능합니다. 앱의 버전 관리 및 배포 워크플로에 가장 적합한 방법을 선택하세요.
자세한 정보는 특정 기능에 대한 문서를 참조하세요:
버전 목표 설정에서 계속
버전 목표 설정에서 계속Live Update 버전 목표 설정 버전 목표 설정 채널 채널 채널 채널 채널 채널 채널에서 구현 세부 정보 베타 테스트 솔루션 베타 테스트 솔루션에서 제품 워크플로우 버전 타겟팅 솔루션의 제품 워크플로우에 대해.