이제 Play Console에서 Capacitor Android 앱에 대해 다음 사유로 경고를 표시합니다: 앱 최적화 수준이 기준치 미만입니다, 종종 Obfuscation 문제가 지속됩니다 3%. Google은 최소한 25% obfuscation, optimization, shrinking을 요구합니다. 적용은 2027년 2월부터시작되며, 이를 준수하지 않으면 노출도와 배포 옵션이 제한될 수 있습니다.
Android vitals의 경고 메시지는 다음과 같습니다:
이는 네이티브 Android DEX 문제입니다. Vue, React 또는 Angular bundle과는 무관합니다. Capgo Live Update 또한 이 점수에 영향을 주지 않습니다. Android Gradle release build에서 문제를 해결한 후, 새로운 App Bundle을 upload해야 합니다.
Google의 측정 기준
Google Play가 검사하는 항목은 DEX 입니다. Android App Bundle 내의 컴파일된 Java 및 Kotlin 코드로, Capacitor, 플러그인, AndroidX를 포함합니다. 2027년 2월부터는 DEX가 10 MB 를 초과하는 앱은 다음 세 가지 항목 모두에서 25% 를 충족해야 합니다:
| 지표 | 의미 | 낮은 점수를 받는 일반적인 Capacitor 원인 |
|---|---|---|
| Obfuscation | 클래스, 필드, 메서드 이름을 짧은 이름으로 변경 | minifyEnabled 여전히 false |
| 최적화 | R8은 바이트코드를 인라인하고 병합하고 재작성합니다 | 기본값 proguard-android.txt 포함 -dontoptimize |
| 축소 | 사용하지 않는 클래스와 메서드 제거 | Resource/code shrinking이 한 번도 켜지지 않음 |
Play가 읽는 시점은 r8.json Android Gradle Plugin 8.10 이상의 최신 패치로 빌드할 때입니다. 그렇지 않으면 mapping.txt, 그다음 DEX 휴리스틱을 사용합니다. minification을 끈 채로 배포된 Capacitor 앱은 매핑 파일이 거의 없으므로, Play는 읽을 수 있는 이름을 보고 몇 퍼센트의 난독화(보통 이미 난독화된 라이브러리 AAR에서 남은 것)로 보고합니다. 이는 3% vitals 점수와 일치합니다.
공식 정책: Play Console 기술 품질 요구사항. 구현 세부 사항: DEX code 최적화 및 R8로 앱 최적화 활성화.
Capacitor 앱이 이 검사를 통과하지 못하는 이유
Capacitor Android 템플릿은 여전히 release 빌드를 함께 제공합니다 없이 R8:
buildTypes {
release {
minifyEnabled false
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
}
}다음 파일의 기본값입니다: android-template/app/build.gradle. 디버그 빌드는 이대로 유지해야 합니다. Play에 게시한다면 릴리스 빌드는 이러면 안 됩니다.
JavaScript는 이미 Vite나 webpack으로 minify되어 있습니다. Play는 이걸 계산하지 않습니다. Play가 계산하는 건 네이티브 DEX 이름, 사용되지 않는 네이티브 code, R8 최적화뿐입니다.
1단계 — 릴리스용 R8 켜기
열기 android/app/build.gradle (Groovy가 Capacitor 기본값입니다) 그리고 다음을 변경하세요 릴리스 블록:
buildTypes {
release {
minifyEnabled true
shrinkResources true
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
}
}모듈에서 Kotlin DSL을 사용한다면 (build.gradle.kts):
buildTypes {
getByName("release") {
isMinifyEnabled = true
isShrinkResources = true
proguardFiles(
getDefaultProguardFile("proguard-android-optimize.txt"),
"proguard-rules.pro"
)
}
}세 가지 핵심 사항:
minifyEnabled true실제로 R8(shrink + obfuscate + optimize)을 실행하는 주체입니다.shrinkResources true사용하지 않는 Android 리소스를 제거합니다. minification이 필요합니다.- 이 R8 설정에는 다음을 사용하세요
proguard-android-optimize.txt.proguard-android.txt배포됩니다-dontoptimize, R8 최적화를 막고 AGP 9에서 실패합니다. Play는 모든 shrinker를 허용하므로, Capacitor 앱은 optimize 기본값으로 R8을 사용해야 합니다. 참고: Capacitor Plugin AGP 9 빌드 오류 해결 방법 플러그인이 아직 이전 파일을 참조하는 경우.
설정하지 마세요 minifyEnabled true 켜짐 debug. Release-only는 로컬 실행을 빠르게 하고 stack trace를 읽기 쉽게 유지합니다.
2단계 — R8 full mode를 비활성화하지 마세요
열기 android/gradle.properties 이 줄이 있으면 삭제하세요:
android.enableR8.fullMode=falseAGP 8+는 이미 full mode를 활성화합니다. 해당 플래그를 그대로 두면 최적화가 제한됩니다.
또한 검색하세요: android/app/proguard-rules.pro (및 기타 추가 -include 파일) 용:
-dontobfuscate
-dontoptimize
-dontshrink
-keep class ** { *; }이 규칙들을 그대로 두면 설정을 변경한 후에도 Play 점수가 낮게 유지됩니다. minifyEnabled문서화된 일시적 사유가 없다면 삭제하세요.
3단계 — 앱 전체가 아닌 Capacitor 플러그인만 유지하기
R8은 리플렉션 메타데이터를 사용합니다. Capacitor 플러그인은 어노테이션을 통해 탐색되므로 keep 규칙이 필요합니다. 일반적으로 사용자가 직접 추가할 필요는 없습니다. Capacitor 3.2.3 버전부터, @capacitor/android 배포됩니다 consumer ProGuard 규칙이 다음 항목을 유지합니다:
@CapacitorPlugin클래스:@PluginMethod, 권한 및 액티비티 콜백- 확장하는 클래스
com.getcapacitor.Plugin - 레거시
@NativePlugin및 Cordova 플러그인 클래스
해당 consumer rules가 적용되도록 현재 Capacitor 6/7/8 라인을 유지하세요.
다음에 추가 규칙을 추가하세요: android/app/proguard-rules.pro 오직 릴리스 빌드에서 재현되는 크래시에는 범위를 좁게 잡는 게 낫습니다:
# Good: one misbehaving plugin package
-keep class com.mycompany.myplugin.** { *; }
# Bad: this will tank obfuscation and shrinking
-keep class com.getcapacitor.** { *; }
-keep class ** { *; }특정 keep rule 후에도 서드파티 플러그인이 계속 크래시하면, 플러그인을 업데이트한 뒤 다음에서 유지보수되는 대안을 고려하세요: 그리고 Capgo 플러그인 디렉토리, 또는 문의하세요 Capgo 컨설팅 패치하기 위해서입니다.
공식 Capacitor 노트: ProGuard 사용하기.
4단계 — 실제 릴리스 번들 빌드
디버그 APK는 여전히 난독화율이 ~0%로 표시됩니다. Play는 업로드한 것만 평가합니다.
프로젝트 루트에서:
npm run build
npx cap sync android
cd android
./gradlew bundleReleaseWithout a release 이 태스크들은 여전히 성공하지만 서명되지 않은 .aab파일이 생성됩니다. Play 업로드 전 Android Studio에서 서명하세요.
기기에 release APK를 설치하세요 (./gradlew assembleRelease, 그다음 아래에 있는 APK app/build/outputs/apk/release/). .aab 는 Play 업로드 포맷이며, 사이드로드하는 것이 아닙니다. 네이티브 플러그인(camera, push, file, billing, auth)을 테스트해 보세요. R8 버그는 npx cap run android 디버그 세션에서는 나타나지 않습니다.
위의 Gradle 명령을 실행한 후 (현재 android/ 상태라면), R8이 실제로 실행됐는지 확인하세요:
app/build/outputs/mapping/release/mapping.txtapp/build/outputs/mapping/release/configuration.txt- AGP 8.10 이상의 최신 패치에서는,
r8.jsonApp Bundle 내부의
해당 release 폴더가 기본 Capacitor variant입니다. product flavors를 사용하는 경우, 매핑은 variant 이름 아래에 있습니다 ("mapping/freeRelease/"). APK는 아래에 있습니다 apk/<flavor>/release/ (예를 들어 apk/free/release/).
만약 mapping.txt 누락되었거나, 잘못된 variant 폴더를 참조했거나, CI 빌드 과정에서 debug, 또는 R8이 다음 옵션과 함께 실행되었습니다: -dontobfuscate. 다시 확인하세요. minifyEnabled true 켜짐 release 또한 keep rules가 난독화를 해제하지 않는지도 확인해야 합니다.
5단계 — 크래시 리포트 가독성 유지하기
매핑 파일이 없으면 난독화된 stack trace는 무용지물입니다. 각 mapping.txt Play 버전별로 다음을 보관하세요:
- Play Console: 테스트 및 출시 → 앱 번들 탐색기 → 다운로드 → 에셋, 그런 다음 upload 하세요.
mapping.txt이미 연결되어 있지 않은 경우. - Firebase Crashlytics / Sentry: CI 과정에서 동일한 mapping 파일을 upload 하세요.
Android Studio / AGP는 종종 mapping을 다음 항목에 포함합니다: .aab. 첫 번째 최적화 upload 후에도 Assets 탭을 확인하세요.
6단계 — Play에 upload 및 재확인
새로운 .aab 를 내부 테스트 트랙에 upload 하세요 (점수 갱신을 위해 production까지 갈 필요는 없습니다). 다음 경로를 여세요:
- 테스트 및 출시 → App bundle explorer 해당 버전에 대한
- DEX 크기 및 obfuscation / optimization / shrinking 백분율
- 모니터링 및 개선 → Android vitals 새 버전이 출시된 후 Play가 분석을 시작합니다
필요합니다 각 지표에서 25% 이상 난독화뿐만 아니라 세 가지 지표 모두를 충족해야 합니다. R8을 활성화하면 proguard-android-optimize.txt Capacitor 앱의 경우 보통 한 자릿수였던 난독화율이 세 지표 모두 25%를 훨씬 상회하게 됩니다.
Play 스토어는 강제합니다 DEX 크기가 10MB(게임은 50MB)를 초과하는 앱에 대해 25% 하한선을 적용합니다. 이 기준 미만이라도 최적화할 가치는 충분합니다. DEX 크기가 줄어들면 메모리 사용량이 감소하고 시작 속도가 빨라집니다.
아직 25% 미만이라면
R8이 켜져 있음에도 Play 스토어(또는 로컬 분석기) 점수가 낮게 나올 수 있습니다. 대개 너무 광범위한 keep rules가 원인입니다.
- 열기 R8 설정 분석기 Android Gradle Plugin 버전이 9.3 이상인 경우 —
assembleRelease그다음 작성합니다configanalyzer.html옆에mapping.txt. AGP 9.2 이하에서는 해당 HTML 파일을 건너뛰고 다음을 사용하세요mapping.txt, APK Analyzer, 그리고 Play의 App bundle explorer를 대신 사용하세요. - keep 규칙을 앱을 얼마나 고정하는지에 따라 정렬하세요. 수정할 수 없는 라이브러리 consumer 규칙은 정상입니다. 앱 레벨
-keep class com.foo.** { *; }은 아닙니다. - 다음을 엽니다:
.aabAndroid Studio APK Analyzer에서 용량이 큰.dex파일을 선택하고, deobfuscated 이름을 토글하세요 (다음이 필요합니다:mapping.txt). 용량이 여전히 크고 읽기 쉬운 패키지는 통째로 keep 대상에서 제외해야 할 패키지입니다. - 여전히 참조를 유지하고 있는 플러그인 업데이트하기
proguard-android.txt. 이 파일은 AGP 9에서 최적화를 방해하며, 이전 플러그인에서는 위험 신호입니다.
단순히 DEX 크기를 줄여서 낮은 점수를 minifyEnabled false 해결하려 하지 마세요. Play 스토어는 크기 축소, 최적화, 및 난독화를 원합니다.
이것이 대체할 수 없는 것:
- JavaScript minification은 에서
vite.config.ts이 지표에 영향을 주지 않습니다. - Capgo Live Update 사용하기 HTML/JS/CSS를 배포할 뿐 DEX를 다시 빌드하지 않습니다. 스토어 바이너리에 R8이 적용된 후에도 JS 수정 사항은 Live Update로 배포할 수 있습니다. 다만 난독화 체크 자체를 위해서는 Native Play upload가 한 번 필요합니다.
- 16 KB 페이지 크기 는 별도의 Play native 요구 사항입니다. 자세히 보기: Android 16 KB 페이지 크기.
이미 다음을 사용하여 Android를 빌드 중이라면, Capgo 빌드, 다음을 android/app/build.gradle in the repo. The next cloud build picks up R8. You do not need a different Play pipeline, only a release binary produced with minification on. Same idea if you keep GitHub Actions Android 빌드: 워크플로우에서 assemble을 릴리스실행해야 하며, debug가 아니어야 합니다.
자주 묻는 질문
R8을 활성화하면 Capacitor 플러그인이 깨질까요?
플러그인이 reflection을 사용하면서 consumer keep rules를 포함하지 않는다면 그럴 수 있습니다. 핵심 Capacitor는 이미 플러그인 클래스를 유지하도록 설정되어 있습니다. 릴리스 빌드를 테스트하고, 다음을 추가하세요. 범위를 좁히세요 크래시가 발생하는 패키지에만 규칙을 적용하세요. 만약 플러그인이 관리되지 않는다면, Capgo 컨설팅 직접 fork하여 빌드가 유지되도록 할 수 있습니다.
이것이 npx cap run 검사를 통과했다는 증거가 될까요?
아니요. 해당 명령어는 R8이 꺼진 디버그 빌드를 사용합니다. 대신 bundleRelease / 서명된 Play 업로드 빌드를 사용하세요.
이미 설정을 minifyEnabled true 했는데도 여전히 3%가 발생합니다. 왜 그럴까요?
검색: -dontobfuscate, proguard-android.txt, android.enableR8.fullMode=false, 그리고 일괄적으로 -keep 규칙을 확인하세요. CI가 이전 아티팩트가 아닌, minified AAB를 업로드했는지 확인해야 합니다.
R8 대신 ProGuard를 사용해야 하나요?
아니요. R8은 Android Gradle Plugin의 shrinker입니다. ProGuard 스타일의 규칙 파일을 읽을 수 있습니다. Google Play 문서에서는 어떤 shrinker든 허용하지만, Capacitor 앱에는 R8 사용을 권장합니다.
체크리스트
-
release { minifyEnabled true; shrinkResources true } -
proguard-android-optimize.txt(아님proguard-android.txt) - 아니요
-dontobfuscate/-dontoptimize/ 앱 전체 적용-keep class ** - Capacitor 3.2.3+ 버전 이상이므로 플러그인 소비자 규칙이 적용됩니다
- Release build 결과물
mapping.txt - Release 설치본에서 테스트 완료된 Native plugins
- 신규
.aab업로드됨; App bundle explorer에서 매핑 확인 가능 - 난독화, 최적화, 코드 축소 모두 25% 미만
Play Console의 경고 내용은 이렇습니다: Capacitor에서 R8을 비활성화하여 Play의 DEX 점수가 낮아졌으니, Gradle 설정을 한 줄 수정하고 스토어에 다시 upload 하라는 것입니다.
Capacitor 앱에서 Google Play 난독화 25% 미만 문제 해결하기
사용 중이라면 Capacitor 앱에서 Google Play 난독화 25% 미만 문제 해결하기 Android 스토어 출시 계획을 세우고, 다음을 연결하세요: Capgo Native Build App Bundle 출시용, Capgo CI/CD 설정하기 upload 파이프라인용, CI/CD 통합 구현 세부 사항용, GitHub actions를 이용한 자동 Capacitor Android build 자체 호스팅 파이프라인용 및, Capgo 컨설팅 R8 활성화 후 플러그인이 작동하지 않는 경우.
