버전 대상

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

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

__CAPGO_KEEP_0__의 버전 대상 시스템은 다음과 같은 기능을 제공합니다.

Capgo’s version targeting system allows you to:

파괴적인 변경 사항을 호환되지 않는 앱 버전에서
여러 앱 버전을 동시에 복잡한 로직 없이 관리할 수 있습니다.
AppFlow 이관 가이드 __CAPGO_KEEP_0__의 버전 대상 시스템은 다음과 같은 기능을 제공합니다.
업데이트를 사용자 세그먼트에 순수하게 배포하세요 특정 사용자 세그먼트에 업데이트를 배포하세요

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

Ionic AppFlow 을 이미 알고 있다면,업데이트가 호환되지 않는 JavaScript가 더 오래된 네이티브 code에 전달되는 것을 방지하기 위해 네이티브 앱 버전과 동적 업데이트 번들을 자동으로 일치시켰다는 것을 알고 있을 것입니다.

Capgo는 동일한 안전 보장 보장을 제공하며, 추가 기능도 제공합니다:버전 일치에 대한 더 세밀한 제어

다중 전략 (채널, semver, 네이티브 제약)
버전 배포에 대한 더 나은 시각화
__CAPGO_KEEP_0__ provides the same safety guarantees
API와 CLI은 대시보드 관리와 함께 제어합니다.

이 접근 방식은 특히 다음과 같은 경우에 유용합니다:

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

How It Works

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

__CAPGO_KEEP_0__와 __CAPGO_KEEP_1__ control alongside dashboard management: __CAPGO_KEEP_0__을 불합리한 네이티브 버전으로 전달하는 것을 방지하세요.
채널 기반 라우팅: 다중 앱 버전을 다른 업데이트 채널로 라우팅하세요.
의미적 버전 제어: 메이저/마이너/패치 경계를 넘어서 업데이트를 자동으로 차단하세요.
장치 기반 오버라이드: 특정 장치 또는 사용자 그룹을 대상으로 하세요.

버전 매칭 흐름

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

이것은 관리하는 버전 업데이트와 주요 버전 업데이트를 위한

recommended approach

delivery model과 유사합니다. Example Scenario production Section titled “Example Scenario”
App v1.x (100,000 users) → v2 channel
App v2.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

장점 제목

code - 채널 라우팅은 자동으로 발생합니다.
Clear separation - 각 버전에는 자신의 업데이트 PIPELINE이 있습니다.
Flexible targeting - 특정 버전 그룹으로 업데이트를 푸시합니다.
Safe rollouts - 불일치하는 버전에 도달하는 변경 사항은 없습니다.

Strategy 2: Semantic Versioning Controls

Use Capgo의 내장 Semantic versioning controls을 사용하여 버전 경계를 넘지 않는 업데이트를 방지합니다. __CAPGO_KEEP_0__

메이저 버전 간에 자동 업데이트 차단

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

이 설정은 의미합니다.

앱 버전 __CAPGO_KEEP_0__의 사용자 1.2.3 __CAPGO_KEEP_0__ 버전까지 1.9.9
__CAPGO_KEEP_0__의 사용자는 NOT __CAPGO_KEEP_0__ 버전 2.0.0 자동으로
Prevents breaking changes from reaching older native code
__CAPGO_KEEP_0__ 사용을 위해 native baseline을 전송합니다. version_build

__CAPGO_KEEP_0__ Granular Control Options

# 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

__CAPGO_KEEP_0__

네이티브 버전 제약 조건을 지정하여 불일치하는 장치로 배포를 방지합니다.

네이티브 버전 Delay 조건 사용

업로드할 때, 최소 네이티브 버전을 지정할 수 있습니다.

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

사용 사례

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

# 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

__CAPGO_KEEP_0__ 채널 assignments을 특정 기기 또는 사용자 그룹에 대해 강제로 변경할 수 있습니다.

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

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' })
  }
}

기기 대시보드 Override

Capgo 대시보드에서:

前往 기기 → 기기를 찾으세요
클릭 채널 설정 또는 버전 설정
__CAPGO_KEEP_0__을 특정 채널 또는 버전으로 오버라이드합니다.
오버라이드된 소스에서 업데이트를 받는 장치

완전한 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. 애플리케이션 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
    }
  }
};

2. 두 버전 모두에 업데이트를 푸시하기

# 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 대시보드를 사용하여 추적:

버전 1과 버전 2의 사용자 수
버전별 패키지 채택률
버전별 오류 또는 충돌

5. 오래된 버전 폐기

터미널 창

# 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은 다음 우선순위를 사용합니다.

디바이스 오버라이드 (대시보드 또는 API) - 가장 높은 우선순위이며 디바이스 오버라이드 UI에서 표시됩니다.
로컬 플러그인 채널 via setChannel() - 디바이스에만 저장되고 디바이스 오버라이드 UI에서 표시되지 않습니다.
defaultChannel capacitor.config.ts에서
기본 채널 (Cloudflare 설정) - 가장 낮은 우선순위

from the app는 채널을 백엔드와 검증한 후, 기기에서 로컬로 저장합니다.

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. Semantic Versioning을 사용하세요

# ✅ 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, here’s how Capgo’s version targeting compares:

기능	아이오닉 앱 플로우	Capgo
버전 기반 라우팅	자연스러운 버전에 따라 자동	자연스러운 버전을 통해 `defaultChannel` + 여러 전략
Semantic 버전	기본 지원	고급으로 `--disable-auto-update` (major/minor/patch)
자연스러운 버전 제약	__CAPGO_KEEP_0__ 설정을 AppFlow 대시보드에서 수동으로 구성합니다.	내장 `--native-version` CLI 플래그
채널 관리	웹 UI + CLI	웹 UI + CLI + API
기기 오버라이드	기기 수준 제한된 제어	API를 통해 대시보드에서 전체 제어
다운그레이드 방지	예	__CAPGO_KEEP_0__를 통해 예 `--disable-downgrade`
다중 버전 유지	수동 branch/channel 관리	채널 우선 순위로 자동화
자체 호스팅	아니오	예 (전체 제어)
버전 분석	기본	버전별 세부 메트릭

문제 해결

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

다음 사항을 확인하세요.

채널 assignments: 디바이스가 올바른 채널에 있는지 확인하세요.

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

버전 제약 조건: 번들에 네이티브 버전 요구 사항이 있는지 확인하세요.
- DASHBOARD → BUNDLES → "자연 버전" 열 확인
SEMVER 설정: 채널의 disable-auto-update 설정
터미널 창
```
npx @capgo/cli channel list
```
디바이스 오버라이드: 디바이스가 수동 오버라이드가 있는지 확인
- DASHBOARD → 디바이스 → 디바이스 검색 → 채널/버전 확인

잘못된 버전으로 패키지 전달

잘못된 버전으로 패키지 전달: 올바른 채널을 확인하세요. capacitor.config.ts
Check Bundle Upload: 올바른 채널로 업로드된 것을 확인하세요.
Inspect Native Version: 확인 --native-version flag가 올바르게 사용되었는지 확인하세요.

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

즉시 수정: 영향을 받은 기기에게 안전한 버전으로 업그레이드하세요.
- 대시보드 → 기기 → bulk select → 버전 설정
장기적인 수정: 버전별 채널을 만들고 별도의 branch를 유지하세요
예방: 업데이트 테스트는 대표적인 기기에서 롤아웃 전 항상 진행하세요

Ionic AppFlow에서 마이그레이션

If you’re migrating from Ionic AppFlow, 버전 대상 설정은 Capgo에서 매우 유사하게 작동하며, 향상된 유연성을 제공합니다.

개념 매핑

__CAPGO_KEEP_0__ Equivalent	Capgo Equivalent	메모
배포 채널	Capgo 채널	같은 개념, 더 강력한 기능
네이티브 버전 잠금	`--native-version` 기호	더 세부적인 제어
채널 우선순위	채널 우선순위 (override → cloud → default)	더 투명한 우선순위
배포 대상	채널 + semver 제어	다양한 전략이 제공됩니다
생산 채널	`production` 채널 (또는任意 이름)	이름이 자유롭습니다
Git 기반 배포	CLI branch에서 업로드하는 패키지	동일한 워크플로우
자동 버전 일치	`defaultChannel` + 버전 제약	다중 전략을 지원한 보강

AppFlow 사용자들을 위한 주요 차이점

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

이동 단계

앱 플로우 채널을 맵핑하세요 Capgo 채널 (일반적으로 1:1)으로
버전별로 defaultChannel 설정 capacitor.config.ts 각 주요 버전
semver 규칙 구성 버전 경계에서 자동 차단을 원한다면
버전별로 __CAPGO_KEEP_0__ --native-version flag를 사용하여
버전별 분포를 Capgo 대시보드에서

고급 패턴

버전별 점진적인 출시

// 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
Semantic Versioning: 메이저/마이너/패치 버전 경계를 넘지 않도록 업데이트를 방지합니다
네이티브 버전 제약: 번들에 대한 최소 네이티브 버전을 요구합니다
자동 다운그레이드 방지: 새로운 네이티브 버전으로 업그레이드된 후 이전 버전의 번들을 전달하지 않습니다
기기 설정: 수동 제어를 통한 테스트 및 목표 설정

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

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

변경 사항 안내서 - 세부 채널 버전 전략
채널 관리 - 채널 구성 참조
업데이트 동작 - 원시 버전 지연 및 조건

버전 목표 설정에서 계속

__CAPGO_KEEP_0__ 사용 중이라면 __CAPGO_KEEP_1__을 사용하여 채널 라우팅 및 단계별 출시를 계획하고, __CAPGO_KEEP_1__을 __CAPGO_KEEP_2__와 연결하세요. __CAPGO_KEEP_2__ __CAPGO_KEEP_2__의 구현 세부 정보를 확인하세요. __CAPGO_KEEP_2__ __CAPGO_KEEP_2__의 구현 세부 정보를 확인하세요. __CAPGO_KEEP_2__ __CAPGO_KEEP_2__의 구현 세부 정보를 확인하세요. __CAPGO_KEEP_3__ __CAPGO_KEEP_3__의 제품 워크플로우를 확인하세요. __CAPGO_KEEP_4__ __CAPGO_KEEP_4__의 제품 워크플로우를 확인하세요. __CAPGO_KEEP_0__