본문 바로가기

버전 타겟팅

각 네이티브 버전에 실행할 수 있는 번들만 전송하세요

사용자는 스토어에서 각자 원하는 시점에 업데이트하므로, 앱의 여러 네이티브 버전이 동시에 배포되어 있을 수 있습니다. Capgo는 각 번들의 네이티브 의존성을 확인하고 버전 규칙에 따라 업데이트를 차단하며, 각 네이티브 버전을 자체 채널로 라우팅할 수 있습니다.

upload 전 native 호환성 확인

bundle compatibility는 프로젝트의 native 패키지와 채널에 배포된 bundle을 비교합니다. CI 환경에서 새로운 binary가 필요한 upload를 중단하려면 --fail-on-incompatible 옵션을 추가하세요.

네이티브 호환성 문서

모든 bundle에 native 버전 하한선 설정

채널에 metadata 전략을 적용하고 --auto-min-update-version으로 upload하세요. native 버전이 bundle의 하한선보다 낮은 기기는 업데이트를 건너뛰고 현재 bundle을 유지합니다.

버전 타겟팅 문서

semver 라인별 업데이트 차단

--disable-auto-update major, minor, 또는 patch 옵션을 사용하면 기기가 현재 native 버전 라인을 벗어난 bundle을 받는 것을 방지할 수 있습니다. 이 규칙은 버전 번호만 비교하며, native code은 검사하지 않습니다.

업데이트 유형 및 버전 차단

네이티브 버전별 채널

각 Native Build의 Capacitor 설정에서 defaultChannel을 v2나 v3처럼 지정하세요. 각 라인은 자체 bundle을 가지며, 이전 라인은 마지막으로 정상 작동한 bundle을 그대로 유지할 수 있습니다.

버전 타겟팅 문서

작동 방식

여러 네이티브 버전을 운영하는 팀이 Capgo로 배포하는 방법

live update 라인과 스토어 라인을 병행 운영할 수 있는 CI 설정입니다. 아래 모든 명령은 Capgo CLI 문서에서 가져왔습니다.

  1. 커밋에 Native Build가 필요한지 확인

    build needed는 네이티브 패키지와 채널을 비교합니다. 스토어 릴리스가 필요한 경우 yes를 출력하고 code 1로 종료하며, live update만으로 충분하면 no를 출력합니다.

    npx @capgo/cli@latest build needed com.example.app --channel production
    build needed 레퍼런스

  2. 채널을 메타데이터 전략으로 전환

    한 번만 하면 됩니다. 이후 각 bundle은 최소 네이티브 버전을 담고, 그보다 낮은 기기는 bundle을 건너뜁니다.

    npx @capgo/cli@latest channel set production com.example.app \
  --disable-auto-update metadata
    버전 타겟팅 문서

  3. 매일 Live Update 업로드

    모든 업로드에서 --auto-min-update-version을 유지하세요. --fail-on-incompatible은 번들이 채널에 없는 네이티브 code를 필요로 하면 작업을 중단합니다.

    npx @capgo/cli@latest bundle upload --channel production \
  --auto-min-update-version \
  --fail-on-incompatible
    네이티브 호환성 문서

  4. 새 네이티브 릴리스용 번들 업로드

    새 바이너리가 배포되면 --fail-on-incompatible 없이 번들을 업로드하세요. Capgo가 최소 버전 기준을 높여 이전 빌드는 이를 건너뛰고, 이후 검사는 새 네이티브 패키지와 비교합니다.

    npx @capgo/cli@latest bundle upload --channel production \
  --auto-min-update-version
    네이티브 및 OTA 채널 워크플로우

Appflow 마이그레이션

Ionic Appflow에서 넘어오셨나요?

Appflow는 라이브 업데이트를 네이티브 버전에 맞춰 매칭해 줬습니다. Capgo에서는 채널과 버전 규칙으로 같은 결과를 얻을 수 있습니다:

  1. v1, v2와 같이 각 네이티브 라인별로 채널을 생성하세요.
  2. 각 Native Build의 Capacitor 설정에서 defaultChannel을 해당 채널로 설정하세요.
  3. 각 번들을 해당 번들이 빌드된 네이티브 라인의 채널에 업로드하세요.
  4. 업로드할 때 --auto-min-update-version을 유지해, 더 새로운 네이티브 code가 필요한 번들이 이전 빌드를 건너뛰게 하세요.
Appflow 마이그레이션 가이드
네이티브 라인별 채널 
// capacitor.config.ts in your 2.x native builds
plugins: {
  CapacitorUpdater: {
    defaultChannel: 'v2',
  },
},

# ship a fix to 2.x users only
npx @capgo/cli@latest bundle upload --channel v2 \
  --auto-min-update-version

# 1.x devices stay on their channel's current bundle

자주 있는 상황

새로운 Native plugin

2.0 바이너리에 카메라 plugin을 추가했다면, 이를 사용하는 bundle을 --auto-min-update-version 옵션과 함께 upload하세요. 그러면 사용자가 2.0을 설치할 때까지 1.x 기기는 해당 bundle을 건너뜁니다.

네이티브 호환성 문서

점진적 노출

--rollout 옵션으로 특정 채널의 일부 사용자에게만 bundle을 전송하고, 설치 및 실패 데이터를 지켜본 뒤 승격하거나 롤백하세요.

Progressive rollouts 문서

구버전 지원 종료

v1 채널로의 upload를 중단하세요. 해당 채널의 기기들은 마지막으로 정상 작동한 bundle을 유지하고, v2는 계속 업데이트를 받습니다.

버전 타겟팅 문서

Native 버전별 개별 채널 매핑

실제 서비스 중인 세 가지 Native 버전의 구성 예시입니다.

  • Native 3.x
    v3
    새 bundle
  • Native 2.x
    v2
    수정 사항만
  • Native 1.x
    v1
    새 bundle 없음

v3에는 기능을, v2에는 수정 사항을 배포하고, v1에는 아무것도 배포하지 않습니다. v1 기기는 마지막으로 정상 작동한 bundle을 유지합니다.

Capacitor로 빌드된 앱

공개 앱은 구버전과 신버전 Native를 모두 지원해야 합니다

공공 서비스, 의료, 기상 앱은 구형 Android 버전과 다양한 기기 세대를 지원해야 할 수 있습니다. Version targeting을 사용하면 모든 사용자에게 하나의 업데이트 경로를 강제하지 않고도 각 Native Build를 최신 호환 웹 번들에 유지할 수 있습니다.

e-Título 앱 아이콘 소셜

e-Título

폭넓은 공공 기기 호환성이 필요한 시민 신분증 앱.

Google Play 설치 수
5,490만
스토어 평점
4.8
Conecte SUS 앱 아이콘 의료

연결하기

구형 및 신형 네이티브 셸에 서로 다른 web bundle이 필요할 수 있는 헬스 앱.

Google Play 설치 수
2,770만
스토어 평점
4.6
Windy.com - 날씨 예보 앱 아이콘 날씨

Windy.com - 날씨 예보

버전에 따라 기기 기능과 지도 성능이 달라질 수 있는 날씨 앱.

Google Play 설치 수
3,290만
스토어 평점
4.7

고객 사례

Capgo로 배포하는 팀들의 이야기

5.0/5 개발 팀 평점 9,400+ 팀 리뷰 보기

no-tone @ Webincode

Webincode 개발자

“Device ID를 특정 그룹에 추가하고 변경 사항을 해당 그룹에만 푸시할 수 있다는 점이 정말 큰 도움이 됩니다.”

Nate van Jole

Private CTO

“설정은 하루도 안 걸렸습니다. 채널 기반 롤아웃 덕분에 프로덕션 사용자에게 배포되기 전에 제 기기에서 먼저 테스트할 수 있었습니다.”

Sergiu S의 사진

Sergiu S

drivolino GmbH 리드 개발자

“Capgo Capacitor Updater 플러그인 덕분에 업데이트 배포 방식이 완전히 바뀌었습니다. 며칠씩 걸리던 작업이 이제는 단 몇 분 만에 끝납니다.”

자주 묻는 질문

실제 배포된 버전 관련 FAQ

사용자마다 스토어 앱 업데이트 시점이 다른 팀을 위한 솔루션입니다.

네이티브 앱을 업데이트하지 않는 사용자는 어떻게 되나요?

사용자의 네이티브 버전과 호환되는 bundle만 계속 받게 됩니다. metadata 전략을 사용하면 최소 네이티브 버전이 사용자 버전보다 높은 bundle은 건너뛰고, 현재 bundle을 그대로 유지합니다.

버전 타겟팅 문서

--disable-auto-update만으로 크래시를 막을 수 있나요?

아니요. 버전 규칙은 버전 번호만 비교하므로, minor 또는 patch 릴리스에 포함된 네이티브 변경 사항은 그대로 배포됩니다. 네이티브 패키지를 확인하는 --fail-on-incompatible 또는 --auto-min-update-version을 사용하세요.

네이티브 호환성 문서

CI는 변경 사항에 스토어 릴리스가 필요한지 어떻게 알 수 있나요?

channel에 대해 build needed 또는 bundle releaseType을 실행하세요. 둘 다 네이티브 패키지 metadata를 비교합니다. ios/, android/ 또는 capacitor.config 아래의 모든 변경을 감지하지는 못하므로, 해당 경로는 git에서도 gate로 막아두세요.

CI에서 OTA 또는 네이티브 빌드 선택

Ionic Appflow에서 이전하려고 합니다. 버전이 일치하는 업데이트를 계속 유지할 수 있나요?

네. defaultChannel을 사용하여 네이티브 라인별로 채널을 사용하거나, --auto-min-update-version을 사용하는 메타데이터 전략을 활용하면 됩니다. Appflow 마이그레이션 가이드에서 설정 방법을 안내해 드립니다.

Appflow 마이그레이션 가이드

이미 호환되지 않는 번들이 배포되었다면 어떻게 하나요?

채널을 히스토리 상의 마지막 호환 번들로 다시 지정하거나, 내장된 번들을 강제 사용하도록 설정한 뒤 Native Build를 배포하세요. notifyAppReady()는 시작에 실패한 번들을 롤백하지만, 호환되는 네이티브 code를 완전히 대체할 수는 없습니다.

롤백 문서

모든 네이티브 버전이 실행 가능한 번들을 유지하도록 관리하세요

14일 무료 체험 기간 동안 메타데이터 전략과 CI 호환성 체크를 설정해 보세요. 신용카드 등록은 필요 없습니다.