Capgo의 버전 이름은 처음에는 거꾸로 느껴질 수 있습니다: version_build 는 네이티브 앱의 기준이 되며, version_name 는 기기에서 번들을 추적합니다. 이 차이를 제대로 이해하면 번들을 배포하기 전에 특정 기기가 OTA 업데이트를 받을지, 못 받을지 확인할 수 있습니다.
자사 플랫폼을 포함한 5개 라이브 업데이트 플랫폼의 트러블슈팅 페이지를 분석한 결과, 저희 문서에는 이름이 붙은 version_build 불일치 코드가 7개 있는 반면, 나머지 4개 플랫폼은 각각 5개, 2개, 2개, 0개였습니다. 이름이 붙은 코드가 많을수록 version_build 불일치가 발생했을 때 추측할 일이 줄어듭니다.
목차
- 1단계: Capgo에서 version_build 및 version_name 찾기
- 2단계: 네이티브 베이스라인과 다운로드된 번들 식별
- 3단계: 네이티브 앱 버전의 출처 확인
- 4단계: Capgo가 수신하는 번들 버전 설정 및 검증
- 5단계: 업데이트 배포 전 채널 적합성 테스트
- 6단계: 버전 불일치 진단 및 릴리스 재현성 확보
- 자주 묻는 질문
- 마치며
1단계: Capgo에서 version_build 및 version_name 찾기
먼저 이 둘을 하나의 앱 설치에 대한 서로 다른 사실로 보세요. version_build 기기에 설치된 네이티브 앱 버전을 Capgo에 알려줍니다. version_name 기기가 다운로드한 JavaScript 번들을 Capgo에 알려줍니다. 두 값은 서로 다를 수 있고, 흔히 예상되는 일입니다.
Capgo의 버전 모델에서 native version은 업데이트 대상 여부를 결정하는 기준점입니다. Capgo은 채널에 할당된 bundle을 이 native baseline과 비교합니다. 기기에 설치된 bundle version은 현재 웹 code를 식별하는 데 도움이 되지만, 채널 버전 규칙의 기준이 되는 native baseline을 대체하지는 않습니다.
문제 해결 전에 Capgo 콘솔의 Devices 페이지에서 기기를 조회해 두 값을 모두 기록하세요. 그런 다음 채널의 target bundle과 비교하세요. Capgo 채널 규칙은 채널의 target version이 무엇과 비교되어 확인되는지 설명합니다. version_build.
| 값 | 의미 | 답변에 활용 | 일반적인 출처 |
|---|---|---|---|
version_build |
Capgo로 전송된 Native app baseline | 이 native app이 채널의 target bundle을 받을 수 있나요? | Native app version 또는 명시적인 Capacitor 설정값 |
version_name |
현재 다운로드된 JavaScript bundle | 현재 어떤 번들 버전이 설치되어 있나요? | 업로드 시 결정된 번들 버전 |
| 채널 타겟 | 디바이스의 채널에 할당된 번들 | Capgo가 업데이트를 확인하는 버전은 무엇인가요? | 현재 채널 할당 |
릴리스 노트나 테스트 보고서에서는 세 값을 각각 별도 컬럼에 두세요. 팀에서 그냥 “앱 버전” 하나로 적으면 잘못된 쌍을 비교하기 쉽습니다. 적용 가능 여부를 확인하려면 타겟 번들을 다음 항목과 비교하세요. version_build. 설치된 웹 code의 경우, 다음을 확인하세요. version_name.
Capgo의 명명 방식은 팀이 증가하는 빌드 번호를 뜻할 때 “build”를 자주 쓰는 Android 관례와 다르게 보일 수 있습니다. 여기서는 이름이 암시하는 대로가 아니라 Capgo 역할을 기준으로 필드를 읽으세요. 이 작은 습관이 릴리스 현장의 혼선을 크게 줄여줍니다.
2단계: 네이티브 베이스라인과 다운로드된 번들 식별
버전 값을 변경하기 전에, 어떤 code가 네이티브이고 어떤 code이 번들로 제공되는지 파악하세요. 네이티브 앱은 설치된 iOS 또는 Android 바이너리입니다. 번들에는 Capacitor 앱이 OTA 업데이트를 통해 받을 수 있는 웹 에셋이 포함됩니다.
기준 버전으로 출시된 네이티브 앱을 가정해 봅시다. 1.2.3. 이후 웹 수정 사항은 bundle로 업로드됩니다 1.2.4. Capgo가 채널의 대상 bundle이 네이티브 베이스라인에 허용되는지 확인합니다 1.2.3. 대상이 충족되면 해당 bundle을 다운로드할 수 있습니다. 설치 후 version_name 기기에 있는 bundle이 반영됩니다. 네이티브 베이스라인은 설치된 바이너리와 연결된 상태를 유지합니다.
이 차이는 사용자가 구버전 앱 스토어 빌드를 사용 중인데 웹 번들이 더 최신인 경우 중요합니다. 번들은 네이티브 바이너리를 교체하지 않고도 변경될 수 있지만, OTA 업데이트는 앱에 포함되지 않았던 네이티브 code를 추가할 수 없습니다. 변경 사항에 새로운 플러그인이나 네이티브 설정이 필요하면 번들 업로드를 대안으로 삼기보다 네이티브 빌드를 계획하세요.
값이 동기화되지 않은 것처럼 보일 때 이 빠른 체크리스트를 사용하세요:
- 테스트 디바이스에 설치된 네이티브 바이너리가 무엇인지 확인하세요.
- 네이티브 베이스라인으로 Capgo가 받는 버전 값을 찾으세요.
- 디바이스의 채널에 할당된 번들 버전을 확인하세요.
- 설치된 번들 버전을 위 두 값과 별도로 기록하세요.
네이티브 베이스라인을 다음 값에서 추측하지 마세요: package.json 빌드 프로세스가 해당 값을 의도적으로 네이티브 버전이나 Capgo 설정으로 복사하는 경우를 제외하고는요. JavaScript 프로젝트 버전과 스토어에 설치된 앱 버전은 달라질 수 있습니다. 올바른 소스는 앱이 실제로 Capgo에 전송하는 값입니다.
베이스라인과 현재 번들을 명확히 식별할 수 있게 되면, 다음 단계는 각 값을 소스 파일로 추적하는 것입니다. 플랫폼 간 차이가 주로 여기서 드러납니다.
3단계: 네이티브 앱 버전의 출처 확인
신뢰할 수 있는 version_build, Capacitor 앱이 보고하는 네이티브 버전을 확인하세요. Capgo의 버전 문서에는 iOS와 Android의 서로 다른 소스 키가 설명되어 있으며, 결과로 생성된 네이티브 값을 OTA 비교 기준으로 사용합니다.
iOS에서
체크 항목 CFBundleShortVersionString 앱의 Info.plist. 대부분의 Xcode 프로젝트에서 이 키는 다음과 같이 설정됩니다. $(MARKETING_VERSION), 따라서 실제로 수정하는 값은 타겟의 Marketing Version입니다. 템플릿이나 빌드가 덮어쓸 수 있는 파일에서만 확인하지 말고, 빌드된 앱에서도 값을 확인하세요.
팀이 Xcode 프로젝트를 업데이트했지만 앱에 전달되는 값은 변경하지 않은 경우, 로컬 프로젝트 뷰는 정상으로 보일 수 있지만 설치된 바이너리는 다른 값을 보고할 수 있습니다. 생성된 네이티브 앱의 버전을 릴리스 프로세스에서 기대하는 값과 비교하세요.
Android에서
체크 항목 defaultConfig.versionName Android 앱의 Gradle 설정에 정의됩니다. 이 네이티브 version name은 Capgo의 OTA 비교에 사용됩니다. Android build code이나 관련 없는 JavaScript 패키지 버전과 혼동하지 마세요. 이 체크에서 중요한 것은 네이티브 앱이 어떤 version name을 보내는지입니다.
공통 버전 정책은 두 플랫폼이 일관되게 유지되는 데 도움이 되지만, 이미 하나의 소스를 공유한다고 가정하지 마세요. iOS와 Android는 파일, 빌드 단계, 출시 시점이 각각 다를 수 있습니다. 특히 한 플랫폼의 스토어 출시 일정이 다르면, 출시 체크에서 최종 값을 비교하세요.
일부 앱은 네이티브 버전을 명시적으로 설정합니다: capacitor.config.ts updater 설정의 version 값을 통해서입니다. 이 Capgo Semver 테스터 설정 또는 네이티브 앱 메타데이터에서 올 수 있는 값으로 이 네이티브 베이스라인을 설명합니다. 앱이 네이티브 메타데이터를 오버라이드한다면, 스토어 버전이 소스라고 여기지 않도록 그 선택을 문서화하세요.
각 플랫폼마다 소스 파일, 확정된 값, 해당 값이 포함된 빌드를 기록해 두세요. 이렇게 하면 테스터 기기에 설치된 앱보다 레포지토리에 이미 더 최신 버전이 있을 수 있는 출시 후에 불일치를 더 쉽게 추적할 수 있습니다.
빌드가 실제로 읽는 소스만 변경하세요. 오래된 파일을 수정하면 패키징된 네이티브 버전은 그대로 둔 채 code 리뷰만 완료된 것처럼 보이게 할 수 있습니다.
4단계: Capgo가 수신하는 번들 버전 설정 및 검증
Bundle 버전은 설치된 네이티브 바이너리가 아닌 JavaScript 업데이트를 설명합니다. Capgo은(는) 다음에서 해당 버전을 가져올 수 있습니다. version 의 package.json 필드. 명시적인 bundle 버전을 제공하지 않는 경우, CLI의 --bundle 옵션을 통해 업로드 시 전송되는 버전을 설정할 수 있습니다.
하나의 경로를 선택하고 릴리스 프로세스에서 명확히 하세요. 만약 package.json 이 소스라면 업로드 전에 해당 필드를 증가시키세요. CI가 CLI를 통해 bundle 버전을 전달하는 경우, 해당 작업이 릴리스 로그에 해결된 버전을 출력하도록 하세요. 두 경로를 조용히 혼합하면 채널이 특정 값을 받은 이유를 파악하기 어려워집니다.
익숙한 형식의 세맨틱 버저닝 사용 major.minor.patch 예를 들어 1.2.3. Capgo 채널 전략은 해당 버전의 각 부분을 사용해 타겟 번들이 네이티브 베이스라인과 일치하는지 판단합니다. 프리릴리스 접미사(예: )는 채널별 빌드를 구분하는 데 도움이 되지만, 릴리스 도구 전반에서 버전이 파싱 가능하고 일관되도록 유지하세요. -beta.1 발행 전 증분 단위를 신중하게 결정하세요:
같은 릴리스 라인 내에서 호환되는 웹 수정사항에는 패치 변경을 사용하세요.
- 같은 릴리스 라인 내에서 호환되는 웹 수정사항에는 패치 변경을 사용하세요.
- 새로운 호환 기능 라인에 속하는 변경 사항이라면 minor 버전을 사용하세요.
- 호환성 경계가 바뀌어 이전 native code이 번들을 지원하지 않을 수 있다면 major 버전을 사용하세요.
이 라벨들은 팀 컨벤션일 뿐, OTA로 네이티브 기능을 추가하는 수단이 아닙니다. 버전 번호만으로는 번들이 네이티브 앱에서 안전한지 증명할 수 없습니다. 실제 호환성 결정은 바이너리에 포함된 code와 의존성에 맞춰 관리해야 합니다.
upload 전에 패키지 버전이나 CLI 값을 upload 후 번들에 표시되는 버전과 비교하세요. 번들이 배포될 채널도 확인해야 합니다. 이름이 올바른 번들이라도 의도하지 않은 채널에 upload하면 잘못된 테스트 결과가 나올 수 있습니다.
잘못되었거나 일관성 없는 문자열은 추측하지 말고 바로 확인해야 합니다. 검증된 릴리스 값을 유지하고, 소스를 수정한 뒤, 배포 전에 해석된 버전을 테스트하세요.
이 Capgo CLI 명령어 레퍼런스 bundle 버전이 릴리스 명령어의 입력값 중 하나이므로, 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 라인이 변경된 대상이 차단될 수 있습니다. 모든 최신 버전처럼 보이는 bundle이 허용된다고 가정하기보다 설정된 전략을 확인하세요.
릴리스할 정확한 조합을 테스트하세요:
- 타겟팅하는 사용자를 대표하는 네이티브 빌드를 설치하세요.
- Capgo에 전송된 네이티브 베이스라인을 확인하세요.
- 테스트 장치를 의도된 채널에 할당하세요.
- 채널 대상 및 해당 버전 전략을 확인하세요.
- 업데이트를 요청하고 장치의 결과를 확인하세요.
사용자 기반에 사용 중인 스토어 버전이 하나 이상이면 다른 네이티브 베이스라인에서도 동일한 확인을 수행하세요. 새 빌드에서는 작동하는 bundle이 오래된 바이너리에서는 차단될 수 있으며, 이는 의도된 안전 규칙일 수 있습니다.
더 넓은 릴리스의 경우 테스트 채널이나 제한된 롤아웃으로 시작하세요. 대상 범위를 확장하기 전에 예상치 못한 자격 결과를 주시하세요. Capgo의 채널 모델은 팀이 릴리스 채널을 통해 bundle을 전달할 수 있게 합니다. 릴리스 노트에서 각 채널의 대상과 의도된 네이티브 라인을 명확히 유지하세요.
테스트 장치가 업데이트되지 않으면 다시 업로드하기 전에 채널 할당 및 버전 값을 확인하세요. 동일한 bundle을 반복적으로 게시해도 베이스라인 불일치를 해결할 수 없습니다.
6단계: 버전 불일치 진단 및 릴리스 재현성 확보
값이 예상과 다르면 순서대로 추적하세요. 먼저 디바이스의 네이티브 앱 버전을 확인합니다. 다음으로 설정 오버라이드가 베이스라인을 변경하는지 확인합니다. 마지막으로 Capgo가 받은 번들 버전과 채널 타겟을 비교합니다. 이 순서는 잘못된 소스 값과 의도대로 작동하는 채널 규칙을 구분해 줍니다.
흔한 원인은 버전을 올리는 것 package.json 인데 네이티브 버전은 그대로 두는 경우, 다른 릴리스 브랜치에서 한 플랫폼만 빌드하는 경우, 다른 채널에 할당된 디바이스를 테스트하는 경우가 있습니다. 혼란의 또 다른 원인은 모든 숫자를 '빌드 버전'이라 부르는 것입니다. 어떤 값이 네이티브인지, 업로드된 번들이며, 현재 설치된 것이 무엇인지 기록해 두세요.
CI/CD에서는 버전 입력을 명시적으로 처리하세요. 파이프라인이 제어된 소스에서 의도된 릴리스 버전을 읽게 한 뒤, 업로드 명령에 전달하거나 업로드 단계 전에 패키지 필드를 업데이트하세요. 해결된 네이티브 베이스라인과 번들 타겟을 작업 출력에 기록합니다. 빌드 서버에서 볼 수 없는 개발자의 로컬 상태에 의존하지 마세요.
필수 버전이 없거나 팀이 허용하지 않는 형식인 경우 실패하는 릴리스 게이트를 사용하세요. 프로모션 전에 올바른 채널로 테스트 업로드를 실행합니다. Capgo는 CLI 기반 배포 플로우를 지원하므로, 팀은 번들 업로드를 기존 CI/CD 작업에 넣고 가시적인 명령 로그를 유지할 수 있습니다.
이 값들을 Android WebView 엔진 버전과 혼동하지 마세요. 저희는 @capgo/capacitor-webview-version-checker 플러그인은 기기의 WebView 엔진이 구형인지 확인하고 네이티브 업데이트 프롬프트를 표시할 수 있습니다. 이는 version_build 및 version_name이므로 네이티브 베이스라인과 채널의 대상 번들 확인을 대체하지 않습니다.
레거시 스킴에서 마이그레이션할 때는 기존 값의 이름을 한 번에 모두 바꾸지 마세요. 먼저 기존 native version을 native baseline에 매핑하세요. 그다음 업로드된 web release를 bundle version에 매핑하세요. 사용자를 해당 채널로 유도하기 전에 대표적인 기존 앱 빌드로 채널 전략을 테스트하세요.
소스 커밋, native version, 업로드된 bundle version, channel, 테스트 결과를 포함한 간단한 릴리스 기록을 남기세요. 릴리스를 일시 중지하거나 롤백해야 할 때 이 기록이 있으면 팀이 어떤 bundle이 어디로 갔는지 파악할 수 있습니다. 또한 다음 배포를 누군가가 어떤 파일을 변경했는지 기억하는 데 의존하지 않고 반복 가능하게 만듭니다.
자주 묻는 질문
Capgo에서 version_build와 version_name의 차이점은 무엇인가요?
version_build 는 네이티브 앱의 기준이 되며, version_name 현재 다운로드된 bundle version입니다. Capgo은 채널의 대상 bundle이 조건에 맞는지 확인할 때 native baseline을 사용합니다. 어떤 native app이 설치되어 있고 어떤 web bundle을 가지고 있는지 구분할 수 있도록 로그와 릴리스 노트에서 두 값을 별도로 유지하세요.
version_name이 OTA 업데이트 허용 여부를 결정하나요?
아니요, Capgo의 channel version 전략은 대상 bundle을 다음 값과 비교합니다: version_build즉, native baseline입니다. version_name 현재 다운로드된 bundle을 식별합니다. 기기가 업데이트를 받지 못한다면 현재 bundle 값을 변경하기 전에 해당 기기의 baseline, channel target, 설정된 전략을 확인하세요.
Capgo는 네이티브 버전을 어디에서 가져오나요?
iOS에서 Capgo이 읽는 값은 CFBundleShortVersionString, Xcode가 보통 자동으로 채워 넣는 값입니다 MARKETING_VERSION. Android에서는 네이티브 버전이 다음에서 가져옵니다 defaultConfig.versionName. Capacitor 설정에서 명시적인 업데이터 버전을 지정하면 앱이 전송하는 값이 달라질 수 있으므로, 빌드된 앱에서 확인하세요.
Capgo는 번들 버전을 어디에서 가져오나요?
Capgo은 다음을 사용할 수 있습니다 version 의 package.json 필드를 사용할 수 있습니다. 명시적인 번들 버전을 전달하지 않는 경우, CLI의 --bundle 옵션으로 버전을 제공할 수도 있습니다. 릴리스 워크플로우에서 하나의 명확한 출처를 선택한 후, 업로드 후 Capgo가 받은 버전을 확인하세요.
마치며
사용 version_build 네이티브 베이스라인에 version_name 설치된 번들에 해당합니다. 다음 롤아웃 전에 테스트 디바이스에서 두 값을 확인하고 채널 대상과 베이스라인을 비교하세요. 이 한 번의 확인으로 더 넓은 사용자층에 도달하기 전에 버전 불일치를 잡아낼 수 있습니다.
