Risolvi l'offuscamento di Google Play sotto il 25% nelle app Capacitor

Play Console ora segnala le app Android Capacitor per L'ottimizzazione dell'app è sotto la nostra soglia, spesso con Offuscamento è rimasta 3%. Google richiede almeno 25% obfuscation, optimization e shrinking. L'obbligo scatta a febbraio 2027, e non rispettarlo può ridurre la visibilità e le opzioni di pubblicazione.

L'avviso in Android vitals appare così:

Avviso Android vitals su Google Play Console: obfuscation al 3%, sotto la soglia di ottimizzazione dell'app del 25%, con data di correzione febbraio 2027

Si tratta di un problema nativo dei file DEX di Android. Non riguarda il tuo bundle Vue, React o Angular. Capgo Anche i live update non cambiano questo punteggio. Lo risolvi nella build release Android Gradle, poi carichi un nuovo App Bundle.

Cosa misura Google

Google Play analizza i file DEX nel tuo Android App Bundle: Java e Kotlin compilati, inclusi Capacitor, plugin e AndroidX. Da febbraio 2027, le app con oltre 10 MB di DEX dovranno soddisfare 25% tutti e tre i requisiti:

Metrica	Cosa significa	Causa tipica di un punteggio basso per Capacitor
Obfuscation	Nomi di classi, campi e metodi rinominati in nomi brevi	`minifyEnabled` è ancora `false`
Ottimizzazione	R8 esegue inline, merge e riscrive il bytecode	Predefinito `proguard-android.txt` include `-dontoptimize`
Shrinking	Rimozione di classi e metodi inutilizzati	Lo shrinking di Resource/code non è mai attivo

Play legge r8.json quando buildi con l'ultima patch di Android Gradle Plugin 8.10 o superiore. Altrimenti usa mapping.txt, poi le euristiche DEX. Un'app Capacitor distribuita con minificazione disattivata ha quasi nessun mapping file, quindi Play vede nomi leggibili e riporta una percentuale minima di obfuscation (spesso residua da librerie AAR già obfuscate). Questo influisce sul 3% punteggio dei vitals.

Policy ufficiale: Requisiti tecnici di qualità di Play Console. Dettaglio implementazione: Ottimizzazione DEX code e Abilitare l'ottimizzazione dell'app con R8.

Perché le app Capacitor falliscono questo controllo

Il template Android Capacitor include ancora release build senza R8:

buildTypes {
    release {
        minifyEnabled false
        proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
    }
}

È l'impostazione predefinita in android-template/app/build.gradle. Le build di debug devono restare così. Le build di release no, se pubblichi su Play.

Il tuo JavaScript è già minificato da Vite o webpack. Play non lo considera. Contano solo i nomi DEX nativi, code nativi inutilizzati e le ottimizzazioni R8.

Passaggio 1 — Attiva R8 per la release

Apri android/app/build.gradle (Groovy è il Capacitor default) e cambia il release blocco:

buildTypes {
    release {
        minifyEnabled true
        shrinkResources true
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
    }
}

Se il modulo usa Kotlin DSL (build.gradle.kts):

buildTypes {
    getByName("release") {
        isMinifyEnabled = true
        isShrinkResources = true
        proguardFiles(
            getDefaultProguardFile("proguard-android-optimize.txt"),
            "proguard-rules.pro"
        )
    }
}

Tre dettagli sono importanti:

minifyEnabled true è ciò che esegue effettivamente R8 (shrink + obfuscate + optimize).
shrinkResources true rimuove le risorse Android inutilizzate. Richiede la minificazione.
Per questa configurazione R8, usa proguard-android-optimize.txt. proguard-android.txt ships -dontoptimize, che blocca le ottimizzazioni di R8 e causa errori con AGP 9. Play permette qualsiasi shrinker; le app Capacitor dovrebbero usare R8 con i default di ottimizzazione. Controlla Correzione errore build AGP 9 del plugin Capacitor se un plugin fa ancora riferimento al vecchio file.

Non impostare minifyEnabled true su debug. L'opzione Release-only mantiene veloci le esecuzioni locali e gli stack trace leggibili.

Passaggio 2 — Non disabilitare la full mode di R8

Apri android/gradle.properties e rimuovi questa riga se presente:

android.enableR8.fullMode=false

AGP 8+ abilita già la full mode. Lasciare quel flag limita l'ottimizzazione.

Cerca anche android/app/proguard-rules.pro (e qualsiasi altro -include file) per:

-dontobfuscate
-dontoptimize
-dontshrink
-keep class ** { *; }

Queste regole manterranno bassi i punteggi Play anche dopo aver attivato minifyEnabled. Eliminale a meno che tu non abbia una ragione documentata e temporanea.

Passaggio 3 — Mantieni i plugin Capacitor, non l'intera app

R8 usa i metadati della reflection. I plugin Capacitor vengono rilevati tramite annotazioni, quindi necessitano di keep rules. Di solito non devi aggiungerle tu manualmente. Da Capacitor 3.2.3, @capacitor/android ships le regole ProGuard per i consumer che mantengono:

@CapacitorPlugin le classi, @PluginMethod, callback di permessi e Activity
Classi che estendono com.getcapacitor.Plugin
Legacy @NativePlugin e classi dei plugin Cordova

Resta su una linea Capacitor 6/7/8 aggiornata, così da applicare quelle regole consumer.

Aggiungi regole extra in android/app/proguard-rules.pro solo per un crash riproducibile in una release build. Meglio mirato che generico:

# Good: one misbehaving plugin package
-keep class com.mycompany.myplugin.** { *; }

# Bad: this will tank obfuscation and shrinking
-keep class com.getcapacitor.** { *; }
-keep class ** { *; }

Se un plugin di terze parti crasha ancora dopo una regola keep mirata, aggiorna il plugin, poi valuta un'alternativa mantenuta da directory dei plugin di Capgo, oppure chiedi Consulenza Capgo per patcharlo.

Note ufficiali di Capacitor: Usare ProGuard.

Step 4 — Crea un bundle di release reale

Gli APK di debug mostreranno comunque ~0% di offuscamento. Play valuta solo quello che carichi.

Dalla root del progetto:

npm run build
npx cap sync android
cd android
./gradlew bundleRelease

Senza un release signingConfig, questi task hanno comunque successo ma generano un file non firmato .aab. Firmalo in Android Studio prima dell'upload su Play.

Installa un APK di release su un dispositivo (./gradlew assembleRelease, poi l'APK in app/build/outputs/apk/release/). Un .aab è un formato per l'upload su Play, non per il sideload. Testa i plugin nativi (camera, push, file, billing, auth). I bug di R8 non emergono durante npx cap run android le sessioni di debug.

Dopo i comandi Gradle sopra (ti trovi in android/), conferma che R8 sia stato eseguito:

app/build/outputs/mapping/release/mapping.txt
app/build/outputs/mapping/release/configuration.txt
Nell'ultima patch di AGP 8.10 o superiore, r8.json all'interno dell'App Bundle

Quelle release le cartelle sono la variante Capacitor predefinita. Con i product flavors, la mappatura avviene sotto il nome della variante ("mapping/freeRelease/). L'APK si trova in apk/<flavor>/release/ (ad esempio apk/free/release/).

Se mapping.txt manca, sei nella cartella della variante sbagliata, CI assemblato debug, o R8 è stato eseguito con -dontobfuscate. Ricontrolla minifyEnabled true su release e che le keep rules non disabilitino l'obfuscation.

Passaggio 5 — Mantieni i crash report leggibili

Gli stack trace offuscati sono inutili senza il mapping file. Mantieni mapping.txt per ogni versione di Play:

Play Console: Test e rilascio → Esplora bundle app → Download → Asset, quindi esegui l'upload mapping.txt se non è già collegato.
Firebase Crashlytics / Sentry: carica lo stesso mapping tramite CI.

Android Studio / AGP spesso incorpora il mapping nel .aab. Verifica comunque la scheda Assets dopo il primo upload ottimizzato.

Passaggio 6 — Carica e ricontrolla Play

Carica il nuovo .aab in un canale di test interno (non serve la produzione per aggiornare il punteggio). Apri:

Test e rilascio → Esplora bundle app per quella versione
Dimensione DEX più percentuali di obfuscation / optimization / shrinking
Monitora e migliora → Android vitals dopo che Play ha analizzato la nuova versione

Ti serve il 25% su ciascuna delle tre metriche, non solo l'offuscamento. Abilitando R8 con proguard-android-optimize.txt solitamente porta un'app Capacitor da un offuscamento a una cifra a ben oltre il 25% su tutte e tre.

Solo Play impone il limite minimo del 25% quando il DEX supera i 10 MB per le app (50 MB per i giochi). Anche sotto quella soglia, vale comunque la pena sistemarlo: DEX più piccolo, meno memoria, avvio più rapido.

Se sei ancora sotto il 25%

R8 è attivo, ma Play (o l'analyzer locale) mostra ancora un punteggio basso. Spesso la causa sono regole di keep troppo ampie.

Apri Analizzatore della configurazione R8 se il tuo Android Gradle Plugin è 9.3 o successivo — assembleRelease e poi scrive configanalyzer.html accanto a mapping.txt. Su AGP 9.2 e versioni precedenti, salta quel file HTML e usa mapping.txt, APK Analyzer e l'App bundle explorer di Play.
Ordina le regole di keep in base alla quantità di app che bloccano. Le regole delle librerie che non puoi modificare sono normali. Livello app -keep class com.foo.** { *; } non lo è.
Apri la .aab in Android Studio APK Analyzer, seleziona il grande .dex files, e attiva i nomi deobfuscated (richiede mapping.txt). I package che rimangono enormi e leggibili sono quelli da non mantenere integralmente.
Aggiorna i plugin che fanno ancora riferimento a proguard-android.txt. Quel file blocca l'ottimizzazione su AGP 9 ed è un segnale critico nei plugin più vecchi.

Non cercare di "correggere" un punteggio basso riducendo i DEX con minifyEnabled false e sperando che le euristiche cambino. Play vuole riduzione, ottimizzazione, e offuscamento.

Cosa non sostituisce

La minificazione di JavaScript nella vite.config.ts non sposta questa metrica.
Live updates di Capgo distribuiscono HTML/JS/CSS. Non ricostruiscono i DEX. Una volta attivato R8 nel binario dello store, puoi ancora distribuire fix JS over the air. Il controllo di offuscamento in sé richiede un upload nativo su Play.
Dimensione pagina 16 KB è un requisito nativo separato di Play. Vedi Dimensione pagina Android a 16 KB.

Se hai già buildato Android con Build Capgo, cambia android/app/build.gradle nel repo. Il prossimo cloud build utilizzerà R8. Non serve una pipeline Play diversa, basta un binario di release con minificazione attiva. Lo stesso vale se usi GitHub Actions per build Android: il workflow deve assemblare release, non debug.

FAQ

Attivare R8 romperà i miei plugin Capacitor?

È possibile, se un plugin usa la reflection e non include regole consumer keep. Il core di Capacitor mantiene già le classi dei plugin. Testa una build di release. Aggiungi un restringere applica la regola solo al pacchetto che crasha. Se il plugin non è più mantenuto, Consulenza Capgo puoi fare il fork e continuare a buildarlo.

Emette `npx cap run` dimostrare di aver superato il controllo?

No. Quel comando usa una build di debug con R8 disattivato. Usa bundleRelease / un upload Play firmato.

Abbiamo già impostato `minifyEnabled true` e vediamo ancora il 3%. Perché?

Cerca -dontobfuscate, proguard-android.txt, android.enableR8.fullMode=false, e una regola -keep regole. Conferma che la CI abbia caricato l'AAB minificato e non un vecchio artifact.

Serve ProGuard invece di R8?

No. R8 è lo shrinker dell'Android Gradle Plugin. Legge i file di regole in stile ProGuard. La documentazione di Google Play permette qualsiasi shrinker; R8 è quello che le app Capacitor dovrebbero usare.

Checklist

release { minifyEnabled true; shrinkResources true }
proguard-android-optimize.txt (non proguard-android.txt)
No -dontobfuscate / -dontoptimize / a livello di app -keep class **
Capacitor 3.2.3+ per applicare le consumer rules del plugin
La release build produce mapping.txt
Plugin nativi testati su un'installazione release
Nuovo .aab caricato; mapping allegato nell'App bundle explorer
Obfuscation, optimization e shrinking: +25% ciascuno

Questo è il tipico avviso della Play Console: Capacitor ha disattivato R8, Play ha iniziato a calcolare i DEX, e basta una riga nel file Gradle e un nuovo upload per risolvere.

Riprendi da: Correggi l'offuscamento di Google Play sotto il 25% nelle app Capacitor

Se stai usando Risolvi l'offuscamento di Google Play sotto il 25% nelle app Capacitor per pianificare i release sul Play Store, collegalo a Capgo Native Build per gli App Bundle di rilascio, CI/CD con Capgo per la pipeline di upload, Integrazione CI/CD per i dettagli di implementazione, Build Android automatica di Capacitor con GitHub Actions per le pipeline self-hosted, e Consulenza Capgo if a plugin breaks after R8 is enabled.