Capgo version_build vs version_name: 설정 단계

Capgo의 버전 이름은 처음에는 다소 혼란스러울 수 있습니다: version_build 는 네이티브 앱의 기준이 되는 반면, version_name 는 기기 내 번들을 추적합니다. 이 차이를 정확히 이해하면 번들 배포 전 특정 기기가 OTA 업데이트를 받을 수 있는지 없는지 미리 확인할 수 있습니다.

자사 플랫폼을 포함한 5개 라이브 업데이트 플랫폼의 트러블슈팅 페이지를 분석한 결과, 당사 문서는 7개의 명확한 version_build 불일치 코드를 제공하는 반면, 나머지 4개 플랫폼은 각각 5개, 2개, 2개, 0개에 그쳤습니다. 명확한 코드가 많을수록 version_build 불일치 발생 시 추측에 의존하지 않고 빠르게 문제를 해결할 수 있습니다.

목차

• 1단계: Capgo에서 version_build와 version_name 찾기
• 2단계: Native baseline과 다운로드된 bundle 식별하기
• 3단계: 네이티브 앱 버전의 출처 확인하기
• 4단계: Capgo가 수신하는 bundle 버전 설정 및 검증
• 5단계: 업데이트 배포 전 채널 적합성 테스트하기
• 6단계: 버전 불일치 진단 및 릴리스 재현성 확보하기
• 자주 묻는 질문
• 결론

1단계: Capgo에서 version_build와 version_name 찾기

먼저, 이 두 가지를 하나의 앱 설치에 대한 서로 다른 정보로 취급하세요. version_build 기기에 설치된 네이티브 앱 버전을 Capgo에 알려줍니다. version_name 기기가 다운로드한 JavaScript bundle을 Capgo에 알려줍니다. 두 값은 서로 다를 수 있으며, 이는 일반적인 상황입니다.

Capgo의 버전 모델에서 네이티브 버전은 업데이트 대상 여부를 결정하는 기준점입니다. Capgo은 채널에 할당된 번들을 이 네이티브 기준점과 비교합니다. 기기에 설치된 번들 버전은 현재 웹 code를 식별하는 데 도움이 되지만, 채널 버전 규칙의 네이티브 기준점을 대체하지는 않습니다.

문제 해결 전, Capgo 콘솔의 Devices 페이지에서 해당 기기를 조회하여 두 값을 모두 기록하세요. 그런 다음 채널의 타겟 번들과 비교해 보세요. Capgo 채널 규칙은 채널의 타겟 버전이 어떻게 확인되는지 설명합니다 version_build.

릴리스 노트나 테스트 보고서에는 이 세 가지 값을 별도 컬럼으로 구분하세요. 팀에서 단순히 “앱 버전”이라고만 적으면 잘못된 쌍을 비교하기 쉽습니다. 업데이트 대상 여부를 확인하려면 타겟 번들을 다음 항목과 비교하세요. version_build. 설치된 웹 code의 경우, 다음을 확인하세요. version_name.

Capgo의 명명 방식은 빌드 번호를 의미하는 “build”를 자주 사용하는 Android 관례와 다르게 느껴질 수 있습니다. 여기서는 이름이 암시하는 바가 아니라 Capgo 역할을 기준으로 필드를 파악하세요. 이 작은 습관이 릴리스 과정의 혼선을 방지합니다.

2단계: Native Baseline 및 다운로드된 번들 식별

버전 값을 변경하기 전에, 어떤 code가 Native이고 어떤 code가 번들로 제공되는지 식별하세요. Native 앱은 설치된 iOS 또는 Android 바이너리입니다. 번들에는 Capacitor 앱이 OTA 업데이트를 통해 받을 수 있는 웹 에셋이 포함됩니다.

Baseline과 함께 배포된 Native 앱을 가정해 봅시다. 1.2.3. 이후의 웹 수정 사항은 bundle로 upload됩니다. 1.2.4. Capgo는 채널의 타겟 bundle이 native baseline에 허용되는지 확인합니다. 1.2.3. 조건이 충족되면 디바이스가 해당 bundle을 download할 수 있습니다. 설치 후, version_name 디바이스의 bundle이 업데이트됩니다. native baseline은 설치된 binary에 계속 유지됩니다.

사용자가 앱 스토어의 구버전 build를 사용 중이지만 웹 bundle은 최신인 경우 이 차이가 중요합니다. bundle은 native binary를 교체하지 않고도 변경할 수 있지만, OTA 업데이트로 앱에 포함되지 않은 native code를 추가할 수는 없습니다. 변경 사항에 새로운 plugin이나 native 설정이 필요하다면, bundle upload를 대체 수단으로 생각하지 말고 native build를 계획하세요.

값이 일치하지 않는 것 같다면 다음을 빠르게 확인해 보세요:

• 테스트 디바이스에 설치된 native binary를 확인합니다.
• Capgo가 native baseline으로 받는 version 값을 찾습니다.
• 디바이스의 채널에 할당된 bundle version을 확인합니다.
• 설치된 bundle version을 위 두 값과 별도로 기록합니다.

다음 항목을 통해 native baseline을 추측하지 마세요: package.json 빌드 프로세스에서 해당 값을 native version이나 Capgo 설정에 의도적으로 복사하지 않는 한, JavaScript 프로젝트 버전과 스토어에 설치된 앱 버전은 서로 다를 수 있습니다. 가장 정확한 기준은 앱이 실제로 Capgo에 전송하는 값입니다.

베이스라인과 현재 bundle의 이름을 식별할 수 있게 되면, 다음 단계는 각 값이 어떤 소스 파일에서 오는지 추적하는 것입니다. 이 과정에서 플랫폼 간의 차이가 드러나곤 합니다.

3단계: native app version의 출처 확인하기

신뢰할 수 있는 version_build를 위해, Capacitor 앱이 보고하는 native version을 찾으세요. Capgo의 버전 문서는 iOS와 Android의 서로 다른 소스 키를 설명하며, 여기서 추출된 native 값을 OTA 비교를 위한 베이스라인으로 사용합니다.

iOS의 경우

확인 CFBundleShortVersionString 앱의 Info.plist에서 확인하세요. 대부분의 Xcode 프로젝트에서 해당 키는 $(MARKETING_VERSION)로 설정되어 있으므로, 실제로 수정해야 하는 값은 target의 Marketing Version입니다. 템플릿이나 빌드 시 덮어씌워질 수 있는 파일만 보지 말고, 빌드된 앱 내의 값을 반드시 확인하세요.

팀에서 Xcode 프로젝트는 업데이트했지만 앱에 반영되는 값은 업데이트하지 않은 경우, 로컬 프로젝트 뷰에서는 정상으로 보여도 실제 설치된 바이너리는 다른 값을 보고할 수 있습니다. 생성된 native app의 버전과 릴리스 프로세스에서 예상하는 값을 비교해 보세요.

Android의 경우

확인하세요 defaultConfig.versionName Android 앱의 Gradle 설정을 확인하세요. 해당 native version name은 Capgo의 OTA 비교 시 사용됩니다. 이를 Android build code이나 관련 없는 JavaScript 패키지 버전과 혼동하지 마세요. 이 확인 과정에서 가장 중요한 것은 네이티브 앱이 어떤 version name을 전송하느냐입니다.

버전 정책을 공유하면 두 플랫폼의 정렬을 유지하는 데 도움이 되지만, 이미 하나의 소스를 공유하고 있다고 가정해서는 안 됩니다. iOS와 Android는 별도의 파일, 빌드 단계 또는 출시 타이밍을 가질 수 있습니다. 특히 한 플랫폼의 스토어 출시 일정이 다르다면, 출시 확인 단계에서 최종 값을 비교하세요.

일부 앱은 다음과 같이 네이티브 버전을 명시적으로 설정합니다: capacitor.config.ts 업데이터 설정(updater configuration)의 version 값을 통해 설정합니다. Capgo Semver Tester 이 도구는 이 네이티브 베이스라인을 설정값 또는 네이티브 앱 메타데이터에서 가져올 수 있는 값으로 설명합니다. 만약 앱에서 네이티브 메타데이터를 오버라이드한다면, 스토어 버전이 소스라고 오해하지 않도록 해당 선택 사항을 문서화하세요.

각 플랫폼에 대해 소스 파일, 결정된 값(resolved value), 그리고 해당 값이 포함된 빌드를 기록해 두세요. 이렇게 하면 출시 후, 즉 저장소(repository)에 테스터 기기에 설치된 앱보다 더 높은 버전이 이미 포함되어 있는 상황에서도 불일치 원인을 더 쉽게 추적할 수 있습니다.

실제 빌드에서 읽어들이는 소스만 변경하세요. 오래된 파일을 수정하면 code 리뷰는 완료된 것처럼 보이지만, 실제 패키징된 네이티브 버전은 변경되지 않은 상태로 남을 수 있습니다.

4단계: Capgo가 수신하는 번들 버전 설정 및 확인

bundle version은 설치된 native binary가 아닌 JavaScript 업데이트를 나타냅니다. Capgo는 명시적인 bundle version이 없을 때 version 의 package.json 필드에서 해당 버전을 가져올 수 있습니다. CLI의 --bundle 옵션을 사용하면 upload 시 전송할 버전을 설정할 수 있습니다.

한 가지 경로를 선택하여 릴리스 프로세스를 명확히 하세요. 만약 package.json 가 소스라면, upload 전에 해당 필드의 버전을 올리세요. 만약 CI가 CLI를 통해 bundle version을 전달한다면, 해당 작업의 릴리스 로그에 결정된 버전을 출력하도록 만드세요. 두 경로를 혼용하면 채널에 왜 특정 값이 전달되었는지 파악하기 어려워집니다.

익숙한 major.minor.patch 형태의 semantic versioning을 사용하세요. 예를 들면 1.2.3와 같습니다. Capgo channel 전략은 해당 버전의 구성 요소를 사용하여 타겟 bundle이 native baseline에 적합한지 결정합니다. Capgo와 같은 pre-release 접미사는 채널별 빌드를 구분하는 데 도움이 되지만, 버전 파싱이 가능하도록 릴리스 도구 전반에서 일관성을 유지해야 합니다. -beta.1 채널별 build를 구분하는 데 도움이 될 수 있지만, 버전 정보는 릴리스 도구 전반에서 파싱이 가능하도록 일관되게 유지해야 합니다.

배포 전 버전을 올리는 방식을 신중히 결정하세요:

• 동일한 릴리스 라인 내에서 호환 가능한 웹 수정 사항은 patch 변경을 사용하세요.
• 새로운 호환 기능 라인에 속하는 변경 사항이라면 minor 버전을 사용하세요.
• 호환성 경계가 바뀌어 이전 Native code에서 번들을 지원하지 않을 수 있다면 major 버전을 사용하세요.

이 라벨들은 팀 컨벤션일 뿐, OTA를 통해 네이티브 기능을 추가하는 수단이 아닙니다. 버전 번호만으로는 번들이 네이티브 앱에서 안전한지 증명할 수 없습니다. 실제 호환성 결정은 바이너리에 포함된 code 및 의존성에 맞춰 관리하세요.

upload 전, 패키지 버전이나 CLI 값을 upload 후 번들에 표시되는 버전과 비교하세요. 또한 번들이 배포될 채널도 확인해야 합니다. 이름이 올바른 번들이라도 의도하지 않은 채널에 upload하면 잘못된 테스트 결과가 나올 수 있습니다.

잘못되었거나 일관성 없는 문자열은 추측하지 말고 반드시 확인해야 합니다. 검증된 릴리스 값을 유지하고, 소스를 수정한 뒤, 배포하기 전에 해결된 버전을 테스트하세요.

이 Capgo CLI 명령어 레퍼런스 upload를 스크립트에 연결할 때 유용합니다. 번들 버전이 릴리스 명령어의 입력값 중 하나이기 때문입니다.

5단계: 업데이트 배포 전 채널 적합성 테스트

채널 적합성은 어떤 번들이 더 최신인지 추측하는 것이 아니라 비교를 통해 결정됩니다. Capgo은 채널의 타겟 번들을 다음으로 전송된 네이티브 베이스라인과 비교합니다: version_build현재 다운로드된 번들인 version_name은 해당 채널 규칙의 베이스라인이 아닙니다.

예를 들어, 설치된 네이티브 앱의 버전이 1.2.3이고, 현재 번들 버전이 1.2.4인 경우를 가정해 봅시다. 만약 채널이 1.2.5를 가리킨다면, 현재 번들이 아닌 네이티브 기준 버전과 1.2.3비교하여 1.2.4대상 버전을 평가해야 합니다. 허용되는 대상 버전은 채널의 업데이트 전략에 따라 달라집니다.

Capgo에서는 네이티브 기준 버전에 따라 업데이트를 제한하는 major 및 minor와 같은 전략을 설명합니다. major 전략을 사용하면 더 높은 major 버전을 가진 대상은 차단될 수 있습니다. minor 전략을 사용하면 기준 버전의 major 또는 minor 라인을 변경하는 대상은 차단될 수 있습니다. 모든 최신 번들이 수락될 것이라고 가정하지 말고, 설정된 전략을 확인하세요.

배포할 정확한 조합을 테스트하세요:

1. 타겟 사용자가 사용하는 것과 동일한 Native Build를 설치합니다.
2. Capgo로 전송된 네이티브 기준 버전을 확인합니다.
3. 테스트 기기를 대상 채널에 할당합니다.
4. 채널 타겟과 버전 전략을 확인하세요.
5. 업데이트를 요청하고 기기에서의 결과를 확인하세요.

사용자층이 여러 스토어 버전을 사용 중이라면 다른 native baseline에서도 동일한 체크를 수행하세요. 최신 build에서 작동하는 bundle이라도 이전 binary에서는 차단될 수 있으며, 이는 의도된 안전 규칙일 수 있습니다.

광범위한 배포를 위해서는 테스트 채널이나 제한적 롤아웃으로 시작하세요. 대상을 확대하기 전에 예상치 못한 업데이트 대상 선정 결과를 모니터링해야 합니다. Capgo의 채널 모델을 사용하면 팀이 릴리스 채널을 통해 bundle을 직접 제어할 수 있습니다. 릴리스 노트에 각 채널의 타겟과 의도된 native 라인을 명확히 기재하세요.

테스트 기기가 업데이트되지 않는다면, 다시 upload하기 전에 채널 할당과 버전 값을 확인하세요. 동일한 bundle을 반복해서 게시한다고 해서 baseline 불일치 문제가 해결되지는 않습니다.

6단계: 버전 불일치 진단 및 재현 가능한 릴리스 만들기

값이 예상과 다를 경우 순서대로 추적하세요. 먼저 기기의 native 앱 버전을 확인합니다. 그다음 설정 override가 baseline을 변경했는지 확인하세요. 마지막으로 Capgo이 수신한 bundle 버전과 채널 타겟을 비교합니다. 이 과정을 통해 잘못된 소스 값과 설정대로 작동 중인 채널 규칙을 구분할 수 있습니다.

주요 원인으로는 버전 업(bumping) 등이 있습니다. package.json 네이티브 버전은 그대로 둔 채 다른 릴리스 브랜치에서 특정 플랫폼을 빌드하거나, 다른 채널에 할당된 기기를 테스트하는 과정에서 혼선이 생길 수 있습니다. 모든 숫자를 단순히 “빌드 버전”이라고 부르는 것도 혼란의 원인입니다. 어떤 값이 네이티브 버전인지, 어떤 값이 업로드된 번들인지, 그리고 현재 설치된 버전은 무엇인지 명확히 기록해 두세요.

CI/CD 환경에서는 버전 입력값을 명시적으로 관리해야 합니다. 파이프라인이 제어된 소스에서 의도한 릴리스 버전을 읽어오도록 하고, 이를 upload 명령에 전달하거나 업로드 단계 전에 package 필드를 업데이트하세요. 결정된 네이티브 베이스라인과 번들 타겟을 작업 출력(job output)에 기록해야 합니다. 빌드 서버가 확인할 수 없는 개발자의 로컬 상태에 의존하는 것은 피해야 합니다.

필수 버전이 누락되었거나 팀에서 허용하지 않는 형식인 경우 실패하는 릴리스 게이트를 사용하세요. 그 다음, 프로모션 전에 올바른 채널로 테스트 업로드를 실행합니다. Capgo는 CLI 기반의 배포 흐름을 지원하므로, 팀은 기존 CI/CD 작업에 bundle upload를 포함하여 가시적인 커맨드 로그를 유지할 수 있습니다.

이 값들을 Android WebView 엔진 버전과 혼동하지 마세요. 저희 @capgo/capacitor-webview-version-checker plugin은 기기의 WebView 엔진이 구버전인지 확인하고 네이티브 업데이트 prompt를 표시할 수 있습니다. 이는 다음 문제와는 별개이므로, version_build 및 version_name, 네이티브 베이스라인과 채널의 타겟 번들을 확인하는 과정을 대체하지 않습니다.

레거시 스키마에서 마이그레이션할 때는 모든 기존 값을 한꺼번에 변경하지 마세요. 먼저 기존 native version을 native baseline에 매핑해야 합니다. 그다음 업로드된 web release를 bundle version에 매핑하세요. 사용자를 채널로 유도하기 전에, 기존 앱 빌드 샘플로 채널 전략을 테스트해야 합니다.

소스 커밋, native version, 업로드된 bundle version, 채널, 테스트 결과를 포함한 짧은 릴리스 기록을 유지하세요. 릴리스를 중단하거나 롤백해야 할 때, 이 기록은 팀이 어떤 번들이 어디로 배포되었는지 파악하는 데 도움이 됩니다. 또한 다음 배포 시 누군가의 기억에 의존하지 않고도 재현 가능한 배포를 가능하게 합니다.

자주 묻는 질문

Capgo에서 version_build와 version_name의 차이점은 무엇인가요?

version_build 는 native app baseline이며, version_name 는 현재 다운로드된 bundle version입니다. Capgo는 채널의 타겟 번들이 업데이트 대상인지 확인할 때 native baseline을 사용합니다. 어떤 native app이 설치되어 있고 어떤 web bundle을 가지고 있는지 구분할 수 있도록, 로그와 릴리스 노트에서 이 두 값을 분리하여 관리하세요.

version_name이 OTA 업데이트 허용 여부를 제어하나요?

아니요, Capgo의 채널 버전 전략은 타겟 번들을 다음 항목과 비교합니다: version_build, 즉 native baseline입니다. version_name 는 현재 다운로드된 번들을 식별합니다. 기기에 업데이트가 전달되지 않는다면, 현재 번들 값을 변경하기 전에 해당 기기의 baseline, 채널 타겟, 그리고 설정된 전략을 확인하세요.

Capgo는 native version을 어디에서 가져오나요?

iOS에서 Capgo는 CFBundleShortVersionString, 보통 Xcode에서 자동으로 채워지는 값입니다. MARKETING_VERSION. Android의 경우, 네이티브 버전은 다음에서 가져옵니다. defaultConfig.versionName. Capacitor 설정에서 updater 버전을 명시하면 앱이 전송하는 값이 달라질 수 있으므로, 빌드된 앱을 반드시 확인하세요.

Capgo는 번들 버전을 어디에서 가져올까요?

Capgo는 명시적인 번들 버전을 전달하지 않을 때, version 의 package.json 명시적인 bundle 버전을 전달하지 않을 때의 동작입니다. CLI를 사용하여 버전을 직접 지정할 수도 있습니다. --bundle 필드를 사용할 수 있습니다. 또한 Capgo의

결론

사용하세요: version_build Native Build 베이스라인 및 version_name 는 네이티브 기준값으로,