버전 대상

이 가이드는 사용자의 네이티브 앱 버전에 따라 최신 호환 가능한 번들을 자동으로 제공하는 방법을 설명합니다. Ionic AppFlow의 접근 방식과 유사합니다.Ionic AppFlow에서 마이그레이션하는 경우?

Migrating from Ionic AppFlow?

If you’re coming from Ionic AppFlow, this guide is especially important for you. AppFlow automatically matched updates to native versions, and Capgo provides the same capability with even more control and flexibility. See the AppFlow Migration Guide for step-by-step migration instructions.

Overview

Capgo’s version targeting system allows you to:

• 자동 업데이트를 사용하여 사용자별로 native 앱 버전에 맞춰 업데이트를 제공합니다.
• 파괴적인 변경 사항 이용 가능한 앱 버전에 도달하지 않도록 방지합니다.
• 여러 앱 버전을 동시에 복잡한 로직 없이 관리합니다.
• 업데이트를 사용자 세그먼트에 원활하게 배포하세요 특정 사용자 세그먼트에 업데이트를 배포하세요

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

Ionic AppFlow 을 이미 알고 있다면,, 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 provides the same safety guarantees버전 대상 설정의 중요성 (AppFlow 사용자에게 특히 중요합니다)

• 버전 대상 설정의 중요성 (AppFlow 사용자에게 특히 중요합니다)
• 버전 대상 설정의 중요성 (AppFlow 사용자에게 특히 중요합니다)
• 버전 대상 설정의 중요성 (AppFlow 사용자에게 특히 중요합니다)
• 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:

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

버전 일치 흐름

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

자동 라우팅

사용자가 앱을 열 때, 그들이 설치한 앱 패키지에 따라 자동으로 지정된 채널에 연결됩니다. 자바스크립트 __CAPGO_KEEP_0__ 변경이 필요하지 않습니다! defaultChannel in their installed app bundle. No JavaScript code changes required!

혜택 섹션

• Zero code changes - 채널 라우팅은 자동으로 발생합니다.
• Clear separation - 각 버전에는 자신의 업데이트 PIPELINE이 있습니다.
• Flexible targeting - 특정 버전 그룹으로 업데이트를 푸시합니다.
• Safe rollouts - 불일치하는 버전으로의 업데이트는 절대 발생하지 않습니다.

Strategy 2: Semantic Versioning Controls

Use Capgo’s built-in Semantic 버전 제어를 사용하여 버전 경계를 넘어 업데이트를 방지합니다. Section titled “Strategy 2: Semantic Versioning Controls”]} (Note: The last string is a heading title, so it is translated as is, without any changes.)

주요 버전 간에 자동 업데이트 차단

# 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 자동으로
• code 버전의 깨지지 않은 변경 사항이 더 오래된 네이티브 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 updates
npx @capgo/cli channel set stable --disable-auto-update none

Semantic Versioning Required

이 전략은 앱 버전의 semver를 따르세요. 버전 번호가 형식에 따라야 합니다. MAJOR.MINOR.PATCH 전략 3: 네이티브 버전 제약

__CAPGO_KEEP_0__

네이티브 버전 요구 사항을 지정하여 불일치하는 장치로 배포를 방지합니다.

네이티브 버전 지연 조건 사용

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

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

작동 방식

네이티브 버전 1.x의 장치에서는 이 배ंडल을 받지 않습니다. 2.0.0 이상의 장치만 받을 수 있습니다. 새로운 네이티브 API 또는 플러그인 요구가 있는 업데이트에 적합합니다.

사용 사례

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

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

2. 네이티브 API 변경 사항

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

3. 점진적인 마이그레이션

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

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

사용자들이 현재 네이티브 버전보다 이전 버전의 패키지를 받는 것을 방지합니다.

채널 설정에서 활성화

Capgo 대시보드에서:

1. 로 이동하세요 채널 → 채널 선택
2. 활성화 자연어에서 자동 다운그레이드 비활성화
3. 변경 사항 저장

또는 CLI에서:

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

__CAPGO_KEEP_0__

• __CAPGO_KEEP_2__ 1.2.5
• __CAPGO_KEEP_3__ 1.2.3
• __CAPGO_KEEP_4____CAPGO_KEEP_5__

이 기능은 사용자가 앱 스토어에서 최신 버전을 설치한 경우에 유용합니다.

• 사용자에게 항상 최신 보안 패치를 제공해야 하거나
• 사용자가 앱 스토어에서 최신 버전을 설치한 경우에
• 회귀 버그를 방지하고 싶을 때

__CAPGO_KEEP_0__

특정 장치 또는 사용자 그룹에 대한 채널 할당을 강제로 Override합니다.

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

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 대시보드에서:

1. 가장 장치 → 장치 찾기
2. 클릭 채널 설정 or 버전 설정
3. __CAPGO_KEEP_0__에 특정 채널 또는 버전으로 대체
4. __CAPGO_KEEP_0__에서 대체된 소스에서 업데이트를 받는 장치

업데이트 테스트

__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

capacitor.config.ts

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

2. 앱 버전 2.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. 오래된 버전 폐기

버전 1 사용량이 임계값 이하로 떨어질 때:

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

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

우선 순위 예시

사용자의 앱이 defaultChannel: 'v2' 그러나 사용자의 기기를 'beta' 대시보드에서 설정한 경우, 사용자는 'beta' 채널에서 업데이트를 받게 됩니다.

Device Override UI는 대시보드 또는 Public API에서만 설정된 override만 표시합니다. setChannel() 앱에서 호출하면 채널을 백엔드와 검증하고, 기기에 저장합니다.

최선의 방법

1. 메이저 버전에서 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 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 대시보드에서 수동으로 구성합니다.	__CAPGO_KEEP_0__ 내장 --native-version CLI 플래그
채널 관리	웹 UI + CLI	웹 UI + CLI + API
장치 오버라이드	장치 수준 제한된 제어	API를 통해 대시보드에서 전체 제어
다운그레이드 예방	예	__CAPGO_KEEP_0__를 통해 예 --disable-downgrade
다양한 버전 유지	수동 브랜치/채널 관리	채널 우선 순위로 자동화
자체 호스팅	아니요	예 (전체 제어)
버전 분석	기본	버전별 세부 메트릭

AppFlow 일치 및 그 이상

Capgo 제공 모든 버전 대상 기능 AppFlow가 제공했던 모든 버전 대상 기능에 더해 추가 제어 메커니즘을 제공합니다. AppFlow의 자동 버전 매칭에 의존하셨다면, Capgo도 더 많은 유연성을 제공하면서 안전합니다.

문제 해결

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

다음 사항을 확인하세요.

1. 채널 assignments: 장치가 올바른 채널에 있습니다.

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

2. 버전 제약 조건: 번들에 네이티브 버전 요구 사항이 있는지 확인하세요.

   • DASHBOARD → BUNDLES → "자연 버전" 열 확인

3. SEMVER 설정: 채널의 disable-auto-update 설정

   npx @capgo/cli channel list

4. 디바이스 오버라이드: 디바이스가 수동 오버라이드가 있는지 확인

   • DASHBOARD → 디바이스 → 디바이스 검색 → 채널/버전 확인

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

1. 기본 채널 검토: 올바른 채널을 확인하세요. capacitor.config.ts
2. Check Bundle Upload: 올바른 채널로 업로드 된 배포본을 확인하세요.
3. Inspect Native Version: 확인 --native-version flag가 올바르게 사용되었는지 확인하세요.

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

1. 즉시 수정: 영향을 받은 기기에게 안전한 배포본을 강제로 적용하세요.
   • 대시보드 → 기기 → bulk 선택 → 버전 설정
2. 장기적인 수정: 버전별 채널을 만들고 별도의 branch를 유지하세요
3. 예방: 업데이트를 대표 기기에서 테스트하기 전에 롤아웃하세요

Ionic AppFlow에서 마이그레이션

Ionic AppFlow , 버전 대상이 __CAPGO_KEEP_0__에서 매우 유사하게 작동합니다. improved flexibility:, version targeting works very similarly in Capgo, with improved flexibility:

Ionic AppFlow 개념

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

AppFlow 사용자용 주요 차이점

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

이동 단계

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

완전한 마이그레이션 가이드

완전한 마이그레이션 지침을 포함하여 SDK 대체 및 API 매핑을 위한 지침을 보려면 AppFlow to Capgo 마이그레이션 가이드.

고급 패턴

버전별로 __CAPGO_KEEP_0__

// 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()
  }
}

__CAPGO_KEEP_0__ 버전별로 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 })
  }
}

Summary

Capgo provides multiple strategies for version-specific update delivery:

1. Channel-Based Routing: 자동 버전 분리 via defaultChannel
2. Semantic Versioning: 메이저/마이너/패치 버전 경계를 넘지 않도록 업데이트 방지
3. Native Version Constraints: 네이티브 버전의 최소 버전을 요구하는 번들
4. Auto-Downgrade Prevention: 새로운 네이티브 버전으로는 더 오래된 번들을 전달하지 않도록 방지
5. 기기 오버라이드: 수동 제어를 통한 테스트 및 목표 설정

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

자세한 정보를 원하시면:

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

버전 목표 설정에서 계속

If you are using __CAPGO_KEEP_0__ 버전 목표 설정 __CAPGO_KEEP_0__을 사용하여 채널 라우팅과 단계별 롤아웃을 계획하고, __CAPGO_KEEP_0__과 연결하세요. __CAPGO_KEEP_0__ __CAPGO_KEEP_0__의 구현 세부 정보를 Channels에서 확인하세요. __CAPGO_KEEP_0__ __CAPGO_KEEP_0__의 구현 세부 정보를 Channels에서 확인하세요. __CAPGO_KEEP_0__ __CAPGO_KEEP_0__의 구현 세부 정보를 Channels에서 확인하세요. 베타 테스트 솔루션 __CAPGO_KEEP_0__의 제품 워크플로우를 Beta Testing Solution에서 확인하세요. 버전 목표 설정 솔루션 __CAPGO_KEEP_0__