버전 대상화

Copy a setup prompt with the install steps and the full markdown guide for this plugin.

이 가이드는 사용자의 네이티브 앱 버전에 따라 최신 호환 가능한 번들을 자동으로 제공하는 방법을 설명합니다. 이것은 Ionic AppFlow의 접근 방식과 유사합니다.이것은 단순화된 업데이트 관리 및 빠른 롤아웃을 제공하며 호환성 문제를 방지합니다.

개요

Capgo의 버전 대상 시스템은 다음을 제공합니다.

자동으로 사용자에게 호환 가능한 업데이트를 제공합니다. 사용자의 네이티브 앱 버전에 따라
인종 불일치 앱 버전으로부터 파괴적인 변경 사항을 방지합니다.
다중 앱 버전 관리 __CAPGO_KEEP_0__
업데이트를 복잡한 논리를 사용하지 않고 동시에 배포 특정 사용자 세그먼트에 업데이트를 배포

버전 대상 설정의 중요성 (AppFlow 사용자에게 특히 중요합니다)

Ionic AppFlow과 익숙하다면 , 사용자에게만 호환 가능한 업데이트만 제공할 수 있는지 확인하는 것이 얼마나 중요한지 알 것입니다. AppFlow는 live update bundles를 native app 버전과 자동으로 매칭하여, 더 이상의 native __CAPGO_KEEP_0__에 호환되지 않는 JavaScript가 배포되는 것을 방지했습니다.code는 동일한 안전 보장 기능을 제공하며, 추가 기능도 제공합니다.

Capgo provides the same safety guarantees여러 가지 전략 (채널, semver, native 제약 조건)

버전 대상 설정의 중요성 (AppFlow 사용자에게 특히 중요합니다)
버전 대상 설정은 사용자에게 호환 가능한 업데이트만 제공할 수 있는지 확인하는 데 중요합니다.
버전 분포에 대한 더 나은 시각
API과 CLI은 대시보드 관리와 함께 제어합니다.

이 접근 방식은 특히 유용합니다:

사용자가 앱의 다른 주요 버전 (예: v1.x, v2.x, v3.x)에 있습니다.
파괴적인 변경 사항을 출시하는 동안 뒤로compatibility를 유지해야 할 때
새로운 번들을 사용하여 더 오래된 네이티브 code를 깨뜨리지 않도록 원치 않을 때
사용자를 하나의 버전에서 다른 버전으로 점진적으로 마이그레이션하는 경우
AppFlow에서 마이그레이션하고 동일한 업데이트 안전성을 유지하고 싶을 때 이것이 어떻게 작동하는지

“이것이 어떻게 작동하는지”라는 제목의 섹션

Capgo uses a multi-layered approach to match users with compatible updates:

원본 버전 제한: 불일치한 원본 버전으로 배포되는 패키지를 방지합니다
채널 기반 라우팅: 앱 버전을 다르게 업데이트하는 채널을 다르게 라우팅합니다
의미적 버전 제어: 메이저/마이너/패치 경계를 넘어 업데이트를 자동으로 차단합니다
장치 기반 오버라이드: 특정 장치 또는 사용자 그룹을 대상으로 합니다

버전 일치 흐름

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: 채널 기반 버전 라우팅

이것은 권장하는 방법 파괴적인 변경 사항과 주요 버전 업데이트를 관리하는 데 사용되는 접근 방식입니다. AppFlow의 배포 모델과 유사합니다.

예시 시나리오

App v1.x (100,000 명의 사용자) → production 채널
App v2.x (50,000 명의 사용자와 파괴적인 변경 사항) → v2 채널
App v3.x (10,000 beta 사용자) → v3 채널

구현

1단계: 각 주요 버전의 채널을 구성하기

// capacitor.config.ts for version 1.x builds
import { 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 builds
const 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 builds
const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example App',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'v3', // Routes v3 users automatically
    }
  }
};

2단계: 채널 만들기

# Create channels for each major version
npx @capgo/cli channel create production
npx @capgo/cli channel create v2
npx @capgo/cli channel create v3

# Enable self-assignment so apps can switch channels
npx @capgo/cli channel set production --self-assign
npx @capgo/cli channel set v2 --self-assign
npx @capgo/cli channel set v3 --self-assign

3단계: 버전별 패키지 업로드

# For v1.x users (from v1-maintenance branch)
git checkout v1-maintenance
npm run build
npx @capgo/cli bundle upload --channel production

# For v2.x users (from v2-maintenance or main branch)
git checkout main
npm run build
npx @capgo/cli bundle upload --channel v2

# For v3.x users (from beta/v3 branch)
git checkout beta
npm run build
npx @capgo/cli bundle upload --channel v3

혜택

Zero code 변경 없음 - 채널 라우팅이 자동으로 발생합니다.
명확한 구분 - 각 버전에는 자신의 업데이트 PIPELINE이 있습니다.
flexible targeting - 특정 버전 그룹에 업데이트를 푸시합니다.
안전한 롤아웃 - 불일치 버전에 변경 사항이 절대 도달하지 않습니다.

Strategy 2: Semantic Versioning Controls

Capgo의 내장 세마틱 버전 제어 기능을 사용하세요. __CAPGO_KEEP_0__

__CAPGO_KEEP_1__

# Create a channel that blocks major version updates
npx @capgo/cli channel create stable --disable-auto-update major

__CAPGO_KEEP_5__

__CAPGO_KEEP_6__ 1.2.3 __CAPGO_KEEP_7__ 1.9.9
__CAPGO_KEEP_8__ __CAPGO_KEEP_9__ __CAPGO_KEEP_10__ 2.0.0 __CAPGO_KEEP_11__
code를 깨는 변경 사항이 더 오래된 네이티브 code에 도달하는 것을 방지합니다.
native baseline을 전송한 비교를 사용합니다. 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 updates
npx @capgo/cli channel set stable --disable-auto-update none

Strategy 3: Native Version Constraints

bundle을 배포하는 기기와 호환되지 않는 기기를 방지하기 위해 bundle에 최소 native 버전 요구 사항을 지정하세요.

nativeVersion Delay Condition 사용

터미널 창

# This bundle requires native version 2.0.0 or higher
npx @capgo/cli bundle upload \
  --channel production \
  --native-version "2.0.0"

기기에서 native 버전 1.x를 사용하는 경우 이 배포를 받지 않습니다. 2.0.0 이상의 기기만이 이 배포를 받습니다. 새로운 native API 또는 플러그인을 필요로 하는 업데이트에 이상적입니다.

새로운 네이티브 플러그인 필요

# Bundle needs Camera plugin added in v2.0.0
npx @capgo/cli bundle upload --native-version "2.0.0"

네이티브 API 변경 사항

# Bundle uses new Capacitor 6 APIs
npx @capgo/cli bundle upload --native-version "3.0.0"

점진적인 마이그레이션

# Test bundle only on latest native version
npx @capgo/cli bundle upload \
  --channel beta \
  --native-version "2.5.0"

자동 다운그레이드 방지 전략 4

사용자가 현재 네이티브 버전보다 이전 버전의 패키지를 받지 않도록 방지합니다.

채널 설정에서 활성화

Capgo 대시보드에서:

다음으로 이동 채널 → 채널을 선택하세요
활성화 네이티브 버전 하향 조정 자동 비활성화
변경 사항 저장

또는 CLI에서:

npx @capgo/cli channel set production --disable-downgrade

예시

사용자의 기기: 네이티브 버전 1.2.5
채널 번들: 버전 1.2.3
결과: 다운그레이드가 될 경우 업데이트가 차단됩니다

이것은 유용할 때:

사용자가 앱 스토어에서 최신 버전을 수동으로 설치했습니다
사용자가 항상 최신 보안 패치를 보장해야 할 때
회귀 버그를 방지하고 싶을 때

기기 수준 타겟팅 전략 5

특정 기기 또는 사용자 그룹에 대한 채널 할당을 재정의합니다.

테스트를 위해 특정 버전 강제

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

// Force beta testers to use v3 channel
async function assignBetaTesters() {
  const deviceId = await CapacitorUpdater.getDeviceId()

  // Check if user is beta tester
  if (isBetaTester(userId)) {
    await CapacitorUpdater.setChannel({ channel: 'v3' })
  }
}

대시보드 기기 재정의

In the Capgo dashboard:

기기 → 기기를 찾으세요. 클릭하세요.
대시보드 기기 재정의 채널 설정 or 버전 설정
특정 채널 또는 패키지 버전으로 대체
대체된 원천에서 업데이트를 받는 장치

완전한 AppFlow-Style 워크플로우

다음은 모든 전략을结合한 완전한 예제입니다.

1. 초기 설정 (App v1.0.0)

# Create production channel with semver controls
npx @capgo/cli channel create production \
  --disable-auto-update major \
  --disable-downgrade

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'production',
    }
  }
};

2. 릴리스 브레이킹 변경 (App v2.0.0)

# Create v2 channel for new version
npx @capgo/cli channel create v2 \
  --disable-auto-update major \
  --disable-downgrade \
  --self-assign

# Create git branch for v1 maintenance
git checkout -b v1-maintenance
git push origin v1-maintenance

// capacitor.config.ts for v2.0.0
const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'v2', // New users get v2 channel
    }
  }
};

3. 두 버전 모두 업데이트를 푸시

# Update v1.x users (bug fix)
git checkout v1-maintenance
# Make changes
npx @capgo/cli bundle upload \
  --channel production \
  --native-version "1.0.0"

# Update v2.x users (new feature)
git checkout main
# Make changes
npx @capgo/cli bundle upload \
  --channel v2 \
  --native-version "2.0.0"

4. 버전 분포 모니터링

Capgo 대시보드를 사용하여 다음을 추적합니다.

버전 v1과 v2의 사용자 수
버전별 패키지 수락률
버전별 오류 또는 충돌 수

5. 오래된 버전 폐기

버전 v1의 사용률이 임계값 이하로 떨어지면:

# Stop uploading to production channel
# Optional: Delete v1 maintenance branch
git branch -d v1-maintenance

# Move all remaining users to default
# (They'll need to update via app store)

__CAPGO_KEEP_0__ 채널 순위

여러 채널 구성이 존재할 때, Capgo는 다음 순위를 사용합니다.

기기 우선순위 (API 대시보드 또는 기기 우선순위) - 가장 높은 우선순위이며 기기 우선순위 UI에서 표시됩니다.
로컬 플러그인 채널 via setChannel() - 기기에서만 저장되고 기기 우선순위 UI에서 표시되지 않습니다.
기본 채널 capacitor.config.ts에서 기본 채널입니다.
__CAPGO_KEEP_0__ (Cloud setting) - 가장 낮은 우선순위

앱에서

Best Practices - 최선의 방법들

// ✅ 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 manually

2. 의미 있는 버전을 사용하세요

# ✅ Good
1.0.0 → 1.0.1 → 1.1.0 → 2.0.0

# ❌ Bad
1.0 → 1.1 → 2 → 2.5

3. 분리된 branch 를 유지하세요

# ✅ Good: Separate branches per major version
main (v3.x)
v2-maintenance (v2.x)
v1-maintenance (v1.x)

# ❌ Bad: Single branch for all versions

4. 롤아웃 전에 테스트하세요

# Test on beta channel first
npx @capgo/cli bundle upload --channel beta

# Monitor for issues, then promote to production
npx @capgo/cli bundle upload --channel production

5. 버전 분포 확인

정기적으로 대시보드를 확인하세요:

사용자가 최신 네이티브 버전으로 업그레이드하고 있는지 확인하세요.
고래 버전이 여전히 높은 트래픽을 받고 있는지 확인하세요.
기존 채널을 deprecated해야 하나요?

Ionic AppFlow와의 비교

Ionic AppFlow로 이주하는 팀에 대해 설명합니다. Ionic AppFlow로 이주하는 팀에 대해 설명합니다., Capgo의 버전 대상 설정 방법입니다.

기능	Ionic AppFlow	Capgo
버전 기반 라우팅	자연스러운 버전 기반	자연스러운 버전 기반 `defaultChannel` + 여러 전략
Semantic 버전	기본 지원	고급 `--disable-auto-update` (major/minor/patch)
원본 버전 제약	앱 플로우 대시보드에서 수동 구성	내장 `--native-version` CLI
채널 관리	웹 UI + CLI	웹 UI + CLI + API
디바이스 오버라이드	디바이스 수준 제한	대시보드/ API
다운그레이드 방지	예	Yes via `--disable-downgrade`
다중 버전 유지	수동 branch/channel 관리	채널 우선 자동 관리
자체 호스팅	No	Yes (전체 제어)
버전 분석	기본	버전별 상세 메트릭

오류 해결

업데이트를 받지 않는 사용자

다음 사항을 확인하세요.

채널 assignments: 장치가 올바른 채널에 있는지 확인하세요.

const channel = await CapacitorUpdater.getChannel()
console.log('Current channel:', channel)

버전 제약 조건: __CAPGO_KEEP_0__을 확인합니다.
- 대시보드 → 번들 → '자연어 버전' 열을 확인합니다.
Semver 설정: __CAPGO_KEEP_0__의 설정을 확인합니다. disable-auto-update 터미널 창
클립보드 복사
```
npx @capgo/cli channel list
```
: 기기에 대한 수동 오버라이드가 있는지 확인합니다.대시보드 → 기기 → 기기를 검색 → 채널/버전을 확인합니다.
- 잘못된 버전으로 번들이 전달되었습니다.

잘못된 버전으로 번들이 전달되었습니다.

기본 채널 검토: 올바른 채널을 확인하세요 capacitor.config.ts
배포 업로드 확인: 업로드 된 배포가 올바른 채널에 업로드 되었는지 확인하세요
자연어 버전 검사: 확인 --native-version 기존 버전에 영향을 미치는 변경 사항

기존 버전에 영향을 미치는 변경 사항

: 영향을 받은 기기에서 안전한 배포로 업데이트하세요대시보드 → 기기 → bulk 선택 → 버전 설정
- Dashboard → Devices → Bulk select → Set Version
장기적인 해결책버전별 채널을 만들고 별도의 branch를 유지하세요
예방업데이트를 rollout하기 전에 대표적인 기기에서 항상 테스트하세요

Ionic AppFlow에서 마이그레이션

Ionic AppFlow에서 __CAPGO_KEEP_0__로의 마이그레이션 시, 버전 대상이 매우 유사합니다. 더 나은 유연성을 제공합니다. 개념 매핑, version targeting works very similarly in Capgo, with improved flexibility:

AppFlow Concept

__CAPGO_KEEP_0__	Capgo 동등한 개념	Notes
배포 채널	Capgo 채널	같은 개념, 더 강력한 기능
원본 버전 잠금	`--native-version` 기호	더 세분화된 제어
채널 우선순위	채널 우선순위 (override → cloud → 기본)	더 투명한 우선순위
배포 대상	__CAPGO_KEEP_0__ 채널 + semver 제어	여러 전략이 사용 가능합니다.
생산 채널	`production` 채널 (또는 임의의 이름)	가변적인 이름
Git 기반 배포	CLI branch에서 번들 업로드	같은 워크플로우
자동 버전 일치	`defaultChannel` + 버전 제약	여러 전략을 사용한 향상

AppFlow 사용자에게 필요한 차이점

더 많은 제어: Capgo은 여러 전략 (채널, semver, 네이티브 버전)이 결합될 수 있는 여러 전략을 제공합니다.
더 나은 시각화: 버전 분포 및 호환성 문제를 보여주는 대시보드
API 접근: 버전 대상에 대한 프로그램적인 제어
자체 호스팅: 동일한 버전 로직을 사용하여 자신의 업데이트 서버를 실행하는 옵션

이동 단계

AppFlow 채널을 맵핑하세요 Capgo 채널 (일반적으로 1:1)
__CAPGO_KEEP_1__ defaultChannel __CAPGO_KEEP_2__ capacitor.config.ts __CAPGO_KEEP_3__
__CAPGO_KEEP_4__ __CAPGO_KEEP_5__
__CAPGO_KEEP_6__ __CAPGO_KEEP_7__ --native-version __CAPGO_KEEP_8__
__CAPGO_KEEP_9__ in Capgo dashboard

고급 패턴

버전별 점진적인 롤아웃

// Gradually migrate v1 users to v2
async 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 version
async 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 version
async 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
: 메이저/마이너/패치 버전 간 업데이트를 방지: 네이티브 버전 제약 조건
: 번들에 대한 최소 네이티브 버전을 요구: 자동으로 다운그레이드 방지
__CAPGO_KEEP_0__: 새로운 네이티브 버전으로 전달되는 더 오래된 번들을 절대 전송하지 마세요.
Device Overrides: 테스트 및 목표 설정을 위해 수동 제어

이러한 전략을结合하면 AppFlow-style 자동 업데이트 전송과 더 많은 유연성과 제어가 가능합니다. 앱의 버전 관리 및 배포 워크플로에 가장 적합한 방법을 선택하세요.

특정 기능에 대한 자세한 내용:

Breaking Changes Guide - 세부적인 채널 버전 관리 전략
Channel Management - 채널 구성 참조
Update Behavior - 네이티브 버전 지연 및 조건

Keep going from Version Targeting

__CAPGO_KEEP_0__이 사용 중이라면 버전 목표 설정 __CAPGO_KEEP_0__을 버전 목표 설정과 연결하여 채널 채널에서 채널 라우팅과 단계별 롤아웃 구현에 대한 세부 정보를 참조하세요. 채널 채널에서 채널 라우팅과 단계별 롤아웃 구현에 대한 세부 정보를 참조하세요. 채널 채널에서 채널 라우팅과 단계별 롤아웃 구현에 대한 세부 정보를 참조하세요. 베타 테스트 솔루션 베타 테스트 솔루션에서 제품 워크플로우에 대한 정보를 참조하세요. 버전 목표 설정 솔루션 버전 목표 설정 솔루션의 제품 워크플로에 대해.