내용으로 건너뛰기

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은 사용자와 호환 가능한 업데이트와 매칭하기 위해 다중 층급 접근 방식을 사용합니다:

  1. 자연어 버전 제한: 호환되지 않는 자연어 버전으로부터 패키지를 배달하는 것을 방지합니다
  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

채널 기반 버전 라우팅 전략 1

권장하는 방법 권장하는 방법 관리하는 주요 버전 업데이트 및 깨진 변경 사항

예시 시나리오

앱 v1.x
  • App v1.x 채널 production channel
  • App v2.x (50,000 사용자와 버그 수정) v2 채널
  • App v3.x (10,000 베타 사용자) v3 채널

Implementation

Implementation

Step 1: 각 주요 버전의 채널을 구성하십시오.

Copy to clipboard
// 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단계: 채널 만들기

2단계: 채널 만들기 섹션
터미널 창
# Create channels for each major version
npx @capgo/cli channel add production
npx @capgo/cli channel add v2
npx @capgo/cli channel add 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단계: 버전별 패키지 업로드

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 - 특정 버전 그룹에 업데이트를 푸시합니다
  • 안전한 롤아웃 - 불일치 버전에는 절대 깨지는 변경 사항이 없습니다

전략 2: 의미적 버전 제어

Strategy 2: Semantic Versioning Controls

Capgo의 내장 semantic versioning controls 버전 경계를 넘지 않는 업데이트를 방지하기 위해

주요 버전을 넘어 업데이트를 자동으로 비활성화

Terminal 창
복사
# Create a channel that blocks major version updates
npx @capgo/cli channel add stable
npx @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 updates
npx @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 channel
npx @capgo/cli@latest channel set production --disable-auto-update metadata

섹션 제목: “업로드 시, 최소 네이티브 버전을 설정하십시오.”

터미널 창
# This bundle requires native version 2.0.0 or higher
npx @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

사용 사례

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

    터미널 창
    # Bundle needs Camera plugin added in v2.0.0
    npx @capgo/cli@latest bundle upload \
    --channel production \
    --min-update-version "2.0.0"
  2. Live Update API 변경

    터미널 창
    # Bundle uses new Capacitor 6 APIs
    npx @capgo/cli@latest bundle upload \
    --channel production \
    --min-update-version "3.0.0"
  3. 네이티브 __CAPGO_KEEP_0__ 변경 사항

    터미널 창
    # one-time: enable metadata gating on beta
    npx @capgo/cli@latest channel set beta --disable-auto-update metadata
    # Test bundle only on latest native version
    npx @capgo/cli@latest bundle upload \
    --channel beta \
    --min-update-version "2.5.0"

점진적인 마이그레이션

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

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

채널 설정에서 활성화

채널 설정에서 활성화

Capgo 대시보드에서:

  1. 로 이동하세요 채널 채널을 선택하세요
  2. 활성화 자연스러운 환경에서 자동으로 버전 다운그레이드 차단
  3. 원본 버전으로 자동 다운그레이드 차단

또는 CLI를 통해

또는 __CAPGO_KEEP_0__에서:
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 channel
async 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 대시보드에서

  1. Go to 가기 장치
  2. Click → 장치 찾기 또는 버전 설정
  3. 특정 채널 또는 버전으로 오버라이드
  4. 기기에서 업데이트를 받는 오버라이드 소스

완전한 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 gating
npx @capgo/cli@latest channel add production
npx @capgo/cli@latest channel set production \
--disable-auto-update metadata \
--no-downgrade
capacitor.config.ts
const config: CapacitorConfig = {
plugins: {
CapacitorUpdater: {
autoUpdate: 'atBackground',
defaultChannel: 'production',
}
}
};

2. 앱 버전 2.0.0에서 발생하는 변경 사항

2. 앱 버전 2.0.0에서 발생하는 변경 사항 섹션
터미널 창
# Create v2 channel for new version
npx @capgo/cli@latest channel add v2
npx @capgo/cli@latest channel set v2 \
--disable-auto-update metadata \
--no-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. 두 버전 모두에 업데이트를 푸시합니다

2. 두 버전 모두에 업데이트를 푸시하는 방법 섹션
터미널 창
# Update v1.x users (bug fix)
git checkout v1-maintenance
# Make changes
npx @capgo/cli@latest bundle upload \
--channel production \
--min-update-version "1.0.0"
# Update v2.x users (new feature)
git checkout main
# Make changes
npx @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 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() - 기기에서만 저장되고 Device Override UI에서 표시되지 않습니다.
  3. defaultChannel capacitor.config.ts
  4. 기본 채널 (클라우드 설정) - 우선순위가 가장 낮음

최선의 방법

제목: 최선의 방법

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 manually

2. 의미적 버전 관리 사용

2. 의미적 버전 관리 사용
터미널 창
# ✅ Good
1.0.0 → 1.0.1 → 1.1.0 → 2.0.0
# ❌ Bad
1.0 → 1.1 → 2 → 2.5

3. 별도 branch 유지

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. 배포 전 테스트

4. 배포 전 테스트
터미널 창
# one-time: create beta and enable metadata gating
# (production is set up in the complete workflow above)
npx @capgo/cli@latest channel add beta
npx @capgo/cli@latest channel set beta --disable-auto-update metadata
# Test on beta channel first
npx @capgo/cli@latest bundle upload \
--channel beta \
--auto-min-update-version
# Monitor for issues, then promote to production
npx @capgo/cli@latest bundle upload \
--channel production \
--auto-min-update-version

사용자가 최신 네이티브 버전으로 업그레이드하고 있는지 확인하세요.

  • 고장난 버전이 여전히 높은 트래픽을 받고 있는지 확인하세요.
  • 구 버전을 사용하는 채널을 폐기해야 하는지 확인하세요.
  • Ionic AppFlow와의 비교

Ionic AppFlow로 이전하는 팀에게는 __CAPGO_KEEP_0__의 버전 대상 설정이 어떻게 다른지 설명해 드립니다.

Ionic AppFlow

Ionic AppFlow Ionic AppFlowCapgo의 버전 대상 설정은 다음과 같습니다.

기능Ionic AppFlowCapgo
버전 기반 라우팅자연스러운 버전 기반자연스러운 버전을 통해 defaultChannel + 여러 전략
Semantic 버전기본 지원고급으로 --disable-auto-update (주/부/정)
자연스러운 버전 제약수동 구성내장 --min-update-version / --auto-min-update-version 메타데이터 채널과 함께
채널 관리웹 UI + CLI웹 UI + CLI + API
장치 오버라이드장치 수준 제한Full control via Dashboard/API
다운그레이드 방지예예 --no-downgrade
다중 버전 유지수동 브랜치/채널 관리채널 우선 자동화
자체 호스팅아니요예 (전체 제어)
버전 분석기본세부 버전별 메트릭

문제 해결

문제 해결

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

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

다음 사항을 확인하세요.

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

    const channel = await CapacitorUpdater.getChannel()
    console.log('Current channel:', channel)
  2. 버전 제약 조건: 번들에 원시 버전 요구 사항이 있는지 확인하세요.

    • 대시보드 → 패키지 → "자연어 버전" 열을 확인하세요
  3. Semver 설정: 채널의 disable-auto-update 설정

    터미널 창
    npx @capgo/cli channel list
  4. 컨텍스트: Capgo 마케팅 웹사이트. 역할: UI 레이블. 위치: 페이지 agent/[slug].astro. 메시지 키 `agents_page_copy_label` (Agent 페이지 복사 레이블).디바이스 오버라이드

    • : 디바이스가 수동 오버라이드가 있는지 확인하세요

대시보드 → 디바이스 → 디바이스 검색 → 채널/버전 확인

잘못된 버전으로 패키지 전달
  1. 잘못된 버전으로 패키지 전달 섹션 제목입니다. : 올바른 채널을 확인하세요. capacitor.config.ts
  2. 업로드 된 패키지 확인: 올바른 채널에 업로드 된 배포본을 확인하세요.
  3. Live Update 버전 대상 설정: 확인 --min-update-version (또는 --auto-min-update-versioncontext --disable-auto-update metadata

: 업로드 된 배포본이 설정된 채널이 사용하는 버전을 확인하세요.

Breaking Changes Affecting Old Versions
  1. Section titled “Breaking Changes Affecting Old Versions”Immediate Fix
    • : 영향을 받은 기기에서 안전한 배포본으로 업데이트하세요.
  2. 장기 수정: 버전별 채널을 만들고 별도의 branch를 유지합니다.
  3. 예방: 대표적인 기기에서 업데이트를 테스트하고 롤아웃하기 전에 항상 업데이트를 테스트합니다.

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 사용자용 주요 차이점"
  1. 더욱 많은 제어: Capgo은 여러 전략 (채널, semver, 네이티브 버전) 을 제공하여 combination 할 수 있습니다
  2. 더 나은 시각: 버전 분포 및 호환성 문제를 보여주는 Dashboard
  3. API 접근: 버전 대상에 대한 완전한 프로그래밍 제어
  4. 자체 호스팅: 동일한 버전 로직을 사용하여 자체 업데이트 서버를 실행하는 옵션
  1. AppFlow 채널을 맵핑하세요 Capgo 채널 (일반적으로 1:1)으로
  2. 버전 관리 defaultChannel 에서 capacitor.config.ts 각 메이저 버전
  3. 버전 관리 규칙을 설정 버전 경계에서 자동 차단을 원하신다면
  4. 버전별 패키지를 업로드 using --min-update-version (채널은 메타데이터 전략을 사용해야 함)
  5. 버전 분포를 모니터링 에서 Capgo 대시보드

버전별 기능 플래그

버전별 A/B 테스트
// 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은 여러 버전별 업데이트 전달을 위한 전략을 제공합니다.

  1. 채널 기반 라우팅: 자동으로 메이저/마이너/패치 버전 경계를 넘지 않도록 버전 분리 defaultChannel
  2. Semantic Versioning: 메이저/마이너/패치 버전 경계를 넘지 않도록 업데이트를 방지
  3. 네이티브 버전 제약: 네이티브 버전의 최소 버전을 요구
  4. 다운그레이드 방지: 새로운 네이티브 버전으로 업데이트된 버전을 전달하지 않음
  5. 기기 설정: 테스트 및 목표 설정을 위한 수동 제어

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

자세한 정보는 특정 기능에 대한 문서를 참조하세요:

버전 목표 설정에서 계속

버전 목표 설정에서 계속

Live Update 버전 목표 설정 버전 목표 설정 채널 채널 채널 채널 채널 채널 채널에서 구현 세부 정보 베타 테스트 솔루션 베타 테스트 솔루션에서 제품 워크플로우 버전 타겟팅 솔루션의 제품 워크플로우에 대해.