Supporta dimensioni di pagina da 16 kB.

Requisito di compatibilità con le dimensioni di pagina di 16 kB di Google Play

A partire dal 1° novembre 2025, tutte le nuove app e gli aggiornamenti delle app esistenti inviati a Google Play e destinati ai dispositivi con Android 15 o versioni successive devono supportare le dimensioni di pagina di 16 kB sui dispositivi a 64 bit.

Scopri di più →

Storicamente, Android ha supportato solo dimensioni delle pagine di memoria di 4 KB, il che ha ottimizzato le prestazioni della memoria di sistema per la quantità media di memoria totale che i dispositivi Android hanno in genere avuto. A partire da Android 15, AOSP supporta i dispositivi configurati per utilizzare una dimensione pagina di 16 KB (dispositivi da 16 KB). Se la tua app utilizza librerie NDK, direttamente o indirettamente tramite un SDK, dovrai ricompilare l'app per farla funzionare su questi dispositivi da 16 KB.

Man mano che i produttori di dispositivi continuano a creare dispositivi con quantità maggiori di memoria fisica (RAM), molti di questi dispositivi adotteranno dimensioni delle pagine di 16 KB (e alla fine maggiori) per ottimizzare le prestazioni del dispositivo. L'aggiunta del supporto per i dispositivi con dimensioni di pagina di 16 kB consente alla tua app di essere eseguita su questi dispositivi e di sfruttare i miglioramenti delle prestazioni associati. Senza ricompilazione, le app non funzioneranno sui dispositivi da 16 KB nelle versioni future di Android.

Per aiutarti ad aggiungere il supporto per la tua app, abbiamo fornito indicazioni su come verificare se la tua app è interessata, su come ricompilare l'app (se applicabile) e su come testarla in un ambiente da 16 kB utilizzando emulatori (incluse le immagini di sistema Android 15 per Android Emulator).

Vantaggi e miglioramenti delle prestazioni

I dispositivi configurati con dimensioni di pagina di 16 KB in media utilizzano un po' più di memoria, ma ottengono anche vari miglioramenti delle prestazioni sia per il sistema sia per le app:

• Tempi di avvio delle app più ridotti quando il sistema è sotto pressione di memoria: in media il 3,16% meno, con miglioramenti più significativi (fino al 30%) per alcune app che abbiamo testato
• Assorbimento di corrente ridotto durante l'avvio dell'app: riduzione media del 4,56%
• Avvio più rapido della fotocamera: in media gli avvii a caldo più veloci del 4,48% e degli avvii a freddo del 6,60% più velocemente
• Tempo di avvio del sistema migliorato: miglioramento medio dell'8% (circa 950 millisecondi)

Questi miglioramenti si basano sui nostri test iniziali e i risultati sui dispositivi effettivi potrebbero essere diversi. Forniremo ulteriori analisi dei potenziali guadagni per le app man mano che continuiamo i test.

Verificare se la tua app è interessata

Se la tua app utilizza codice nativo, devi ricompilarla con il supporto per i dispositivi da 16 kB. Se non sai con certezza se la tua app utilizza codice nativo, puoi utilizzare APK Analyzer per identificare se è presente codice nativo e poi controllare l'allineamento dei segmenti ELF per le librerie condivise che trovi. Android Studio offre anche funzionalità che ti aiutano a rilevare automaticamente i problemi di allineamento.

Se la tua app utilizza solo codice scritto nel linguaggio di programmazione Java o in Kotlin, incluse tutte le librerie o gli SDK, allora la tua app supporta già dispositivi da 16 KB. Tuttavia, ti consigliamo di testare l'app in un ambiente da 16 KB per verificare che non si verifichino regressioni impreviste nel comportamento dell'app.

La tua app utilizza codice nativo?

La tua app utilizza codice nativo se si verifica una delle seguenti condizioni:

• La tua app utilizza codice C/C++ (nativo). Se la tua app utilizza il Android NDK, utilizza codice nativo.
• La tua app si collega a librerie o dipendenze native di terze parti (ad es. SDK) che le utilizzano.
• La tua app è creata da un generatore di app di terze parti che utilizza librerie native sul dispositivo.

Identificare le librerie native utilizzando lo Strumento di analisi APK

Strumento di analisi APK è uno strumento che ti consente di valutare vari aspetti di un APK creato. Per verificare se la tua app utilizza codice nativo (indipendentemente dal fatto che sia compatibile con le dimensioni di pagina di 16 kB):

1. Apri Android Studio, poi fai clic su File > Apri e scegli un progetto qualsiasi.

2. Nella barra dei menu, fai clic su Build > Analyze APK... (Analizza APK...)

   

3. Scegli l'APK che vuoi analizzare.

4. Cerca nella cartella lib, che contiene i file oggetto condivisi (.so), se presenti. Se sono presenti file oggetto condivisi, la tua app utilizza codice nativo. La colonna Allineamento mostra messaggi di avviso per tutti i file che presentano problemi di allineamento. Se non sono presenti file oggetto condivisi o non è presente una cartella lib, la tua app non utilizza codice nativo.

   

Rilevare i problemi di allineamento con i controlli automatici

Android Studio ti avvisa in modo proattivo se le librerie precompilate o gli APK non sono conformi alle dimensioni di pagina di 16 kB. Utilizza lo strumento APK Analyzer per esaminare le librerie da aggiornare o se sono necessarie modifiche al codice.

Lint in Android Studio evidenzia anche le librerie native che non sono allineate alle dimensioni di pagina di 16 kB.

Controllare l'allineamento dei segmenti ELF per le librerie condivise

Per tutte le librerie condivise, verifica che i segmenti ELF delle librerie condivise siano allineati correttamente utilizzando l'allineamento ELF a 16 kB. Se sviluppi su Linux o macOS, puoi utilizzare lo script check_elf_alignment.sh come descritto nella sezione seguente. Puoi anche utilizzare direttamente gli strumenti della riga di comando.

Utilizzare lo script check_elf_alignment.sh (Linux o macOS)

Segui questi passaggi per controllare l'allineamento dei segmenti ELF utilizzando lo script check_elf_alignment.sh:

1. Salva lo script check_elf_alignment.sh in un file.

2. Esegui lo script sul file APK della tua app:

   check_elf_alignment.sh APK_NAME.apk
   

   Lo script restituisce ALIGNED o UNALIGNED per tutte le arm64-v8a librerie condivise.

3. Se le librerie condivise arm64-v8a o x86_64 sono UNALIGNED, dovrai aggiornare la pacchettizzazione di queste librerie, quindi ricompilare l'app e ripetere il test seguendo i passaggi descritti in questa sezione.

Utilizzare direttamente gli strumenti della riga di comando

Segui questi passaggi per controllare l'allineamento dei segmenti ELF utilizzando direttamente gli strumenti della riga di comando:

1. Assicurati che Android SDK Build-Tools versione 35.0.0 o successive e l' Android NDK siano installati utilizzando lo SDK Manager in Android Studio o lo sdkmanager strumento a riga di comando.

2. Estrai il file APK della tua app:

   Linux o macOS

   unzip APK_NAME.apk -d /tmp/my_apk_out
   

   Windows (PowerShell)

   Expand-Archive -Path .\APK_NAME.apk -DestinationPath ~\tmp\my_apk_out
   

3. Nella directory temporanea in cui hai estratto il file APK, controlla i contenuti della directory lib per i file oggetto condivisi (.so). Questi sono gli stessi file oggetto condivisi che avresti visto durante l'identificazione delle librerie native utilizzando lo Strumento di analisi APK. Esegui il comando seguente su ogni file oggetto condiviso:

   Linux o macOS

   SDK_ROOT_LOCATION/Android/sdk/ndk/NDK_VERSION/toolchains/llvm/prebuilt/darwin-x86_64/bin/llvm-objdump -p SHARED_OBJECT_FILE.so | grep LOAD
   

   Windows (PowerShell)

   SDK_ROOT_LOCATION\Android\sdk\ndk\NDK_VERSION\toolchains\llvm\prebuilt\windows-x86_64\bin\llvm-objdump.exe -p SHARED_OBJECT_FILE.so | Select-String -Pattern "LOAD"
   

   Dove SDK_ROOT_LOCATION è il percorso della directory in cui hai installato SDK Android, SHARED_OBJECT_FILE è il nome del file oggetto condiviso che stai controllando e NDK_VERSION è la versione di Android NDK che hai installato (ad es. 28.0.12433566). L'output sarà simile al seguente per ogni file che controlli:

   LOAD off    0x0000000000000000 vaddr 0x0000000000000000 paddr 0x0000000000000000 align 2**14
   LOAD off    0x0000000000042a90 vaddr 0x0000000000043a90 paddr 0x0000000000043a90 align 2**14
   LOAD off    0x0000000000046230 vaddr 0x0000000000048230 paddr 0x0000000000048230 align 2**14
   

4. Controlla le righe di output per assicurarti che i segmenti di caricamento non abbiano valori inferiori a 2**14. Se i segmenti di caricamento sono 2**13, 2**12 o valori inferiori , dovrai aggiornare la pacchettizzazione di queste librerie, quindi ricompilare l'app e ripetere il test seguendo i passaggi descritti in questa sezione.

5. Poi, esegui lo strumento a riga di comando zipalign sul file APK della tua app:

   Linux o macOS

   SDK_ROOT_LOCATION/Android/sdk/build-tools/35.0.0/zipalign -v -c -P 16 4 APK_NAME.apk
   

   Windows (PowerShell)

   SDK_ROOT_LOCATION\Android\sdk\build-tools\35.0.0\zipalign.exe -v -c -P 16 4 APK_NAME.apk
   

   Dove SDK_ROOT_LOCATION è il percorso della directory in cui hai installato l'SDK Android e APK_NAME è il nome del file APK della tua app. L'ultima riga dell'output indicherà "Verification successful" (Verifica riuscita) se tutte le librerie condivise sono allineate correttamente.

   Se la verifica non è riuscita, alcune librerie condivise devono essere riallineate, quindi dovrai aggiornare la pacchettizzazione di queste librerie, poi ricompilare l'app e ripetere il test seguendo i passaggi descritti in questa sezione.

Creare l'app con il supporto per i dispositivi con dimensioni di pagina di 16 kB

Se la tua app utilizza codice nativo, completa i passaggi descritti nelle sezioni seguenti per assicurarti che supporti i dispositivi con dimensioni di pagina di 16 kB:

1. Aggiornare il packaging delle librerie condivise
2. Compilare l'app utilizzando l'allineamento ELF a 16 kB
3. Correggere il codice e risolvere i problemi di runtime
4. Controllare gli SDK per il supporto delle dimensioni di pagina di 16 kB

Aggiornare il packaging delle librerie condivise

Esegui l'upgrade ad AGP versione 8.5.1 o successive e utilizza librerie condivise non compresse.

Utilizzare bundletool per verificare l'allineamento ZIP

Per visualizzare l'allineamento del bundle, utilizza:

bundletool dump config --bundle=<my .aab>  | grep alignment

Se vedi PAGE_ALIGNMENT_16K, significa che il bundle richiede l'allineamento ZIP a 16 kB. Se vedi PAGE_ALIGNMENT_4K, significa che l'APK creato da questo AAB deve avere file .so allineati a 4 kB nel file ZIP.

AGP versione 8.5.1 o successive

I dispositivi con dimensioni di pagina di 16 kB richiedono che le app fornite con librerie condivise non compresse le allineino a un limite allineato a 16 kB. Per farlo, devi eseguire l'upgrade al plug-in Android per Gradle (AGP) versione 8.5.1 o successive. Per informazioni dettagliate sulla procedura di upgrade, consulta la sezione Android Assistente per l'upgrade del plug-in Gradle.

AGP versione 8.5 o precedenti

Se non puoi eseguire l'upgrade di AGP alla versione 8.5.1 o successive, l'alternativa è passare all'utilizzo di librerie condivise compresse. Aggiorna la configurazione di Gradle in modo che Gradle comprima le librerie condivise durante il packaging dell'app per evitare problemi di installazione dell'app con librerie condivise non allineate.

android {
  ...
  packagingOptions {
      jniLibs {
        useLegacyPackaging true
      }
  }
}

android {
  ...
  packagingOptions {
      jniLibs {
        useLegacyPackaging = true
      }
  }
}

AGP versione 8.0 o precedenti

Se utilizzi una versione di AGP uguale o precedente alla 8.0, devi anche disattivare l'opzione della libreria nativa non compressa per gli app bundle nel file gradle.properties:

android.bundle.enableUncompressedNativeLibs=false

Compilare l'app utilizzando l'allineamento ELF a 16 kB

Per l'esecuzione dell'app, i dispositivi con dimensioni di pagina di 16 kB richiedono che i segmenti ELF delle librerie condivise siano allineati correttamente utilizzando l'allineamento ELF a 16 kB.

Per gli sviluppatori di giochi, se il gioco viene eseguito sul motore grafico Unity, consulta la guida di Unity. Se il gioco viene eseguito sul motore grafico Unreal, consulta la guida di Unreal. Per i motori di gioco nativi, continua con questa guida.

Per compilare l'app utilizzando l'allineamento ELF a 16 kB, completa i passaggi in una delle sezioni seguenti a seconda della versione di Android NDK che stai utilizzando.

Android NDK r28 e versioni successive

NDK versione r28 e successive vengono compilate con allineamento a 16 kB per impostazione predefinita.

Android NDK r27

Per supportare la compilazione di librerie condivise allineate a 16 kB con Android NDK versione r27 e successive, devi aggiornare i flag ndk-build, build.gradle, build.gradle.kts o del linker come segue:

APP_SUPPORT_FLEXIBLE_PAGE_SIZES := true

android {
  ...
  defaultConfig {
    ...
    // This block is different from the one you use to link Gradle
    // to your CMake or ndk-build script.
    externalNativeBuild {
      // For ndk-build, instead use the ndkBuild block.
      cmake {
        // Passes optional arguments to CMake.
        arguments "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
      }
    }
  }
}

android {
  ...
  defaultConfig {
    ...
    // This block is different from the one you use to link Gradle
    // to your CMake or ndk-build script.
    externalNativeBuild {
      // For ndk-build, instead use the ndkBuild block.
      cmake {
        // Passes optional arguments to CMake.
        arguments += listOf("-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON")
      }
    }
  }
}

-Wl,-z,max-page-size=16384

Android NDK r26 e versioni precedenti

Aggiorna sempre NDK. Questa opzione deve essere utilizzata solo come ultima risorsa e non è garantito alcun supporto.

Per supportare la compilazione di librerie condivise allineate a 16 kB con Android NDK versione r26 o precedenti, devi aggiornare la configurazione ndk-build o cmake come segue:

LOCAL_LDFLAGS += "-Wl,-z,max-page-size=16384"

target_link_options(${CMAKE_PROJECT_NAME} PRIVATE "-Wl,-z,max-page-size=16384")

Android NDK r22 e versioni precedenti non sono compatibili

Aggiorna sempre NDK. Questa opzione deve essere utilizzata solo come ultima risorsa e non è garantito alcun supporto.

Oltre ai passaggi per NDK r26 e versioni precedenti, common-page-size=16384 può risolvere i bug nei vecchi GNU ld e LLVM lld linker. Questa opzione funziona solo se l'ELF ha anche una sezione .relro_padding. Dipende dalla versione del linker e dal programma specifico scritto. Non è disponibile alcun supporto per queste versioni di NDK e, se non funziona, aggiorna la versione di NDK prima di segnalare qualsiasi problema.

Correggere il codice e risolvere i problemi di runtime

Anche se la tua app è allineata a 16 kB, può riscontrare errori se in alcune parti del codice si presuppone che un dispositivo utilizzi una dimensione di pagina specifica. Per evitare questo problema, completa i seguenti passaggi:

1. Rimuovi tutte le dipendenze hardcoded che fanno riferimento alla PAGE_SIZE costante o alle istanze nella logica del codice che presuppongono che la dimensione della pagina di un dispositivo sia di 4 kB (4096).

   Utilizza invece getpagesize() o sysconf(_SC_PAGESIZE).

2. Cerca gli utilizzi di mmap() e di altre API che richiedono argomenti allineati alla pagina e sostituiscili con alternative, se necessario.

In alcuni casi, se la tua app utilizza PAGE_SIZE come valore pratico non vincolato alla dimensione della pagina sottostante, non si interromperà quando viene utilizzata in modalità a 16 kB. Tuttavia, se questo valore viene passato al kernel con mmap senza MAP_FIXED, il kernel utilizza comunque un'intera pagina, sprecando un po' di memoria. Per questi motivi, PAGE_SIZE non è definito quando la modalità a 16 kB è attivata su NDK r27 e versioni successive.

Se la tua app utilizza PAGE_SIZE in questo modo e non passa mai direttamente questo valore al kernel, crea una nuova variabile con un nuovo nome per indicare che viene utilizzata per altri scopi e non riflette una pagina di memoria reale.PAGE_SIZE

Controllare gli SDK per il supporto delle dimensioni di pagina di 16 kB

Molti SDK sono compatibili con le dimensioni di pagina di 16 kB, soprattutto se li crei tu o se utilizzi versioni precompilate recenti. Tuttavia, poiché alcune versioni precompilate o versioni di SDK non sono compatibili con le dimensioni di pagina di 16 kB, devi controllare il sito web di ogni fornitore di SDK per determinare la versione da utilizzare con le dimensioni di pagina di 16 kB.

Testare l'app in un ambiente da 16 kB

Dopo aver creato l'app con il supporto per i dispositivi con dimensioni di pagina di 16 kB, dovrai testarla in un ambiente da 16 kB per verificare se si verificano regressioni. A tale scopo, procedi nel seguente modo:

1. Configura Android SDK 15 o versioni successive.

2. Configura uno dei seguenti ambienti di test:

   • Configura l'emulatore Android con un'immagine di sistema Android 15 basata su 16 kB
     • Utilizza Cuttlefish con dimensioni di pagina di 16 kB su ARM64
     • Simula Cuttlefish con dimensioni di pagina di 16 kB su x86-64
   • Attiva la modalità a 16 kB su un dispositivo utilizzando le opzioni sviluppatore
   • Utilizza Samsung Remote Test Lab sui dispositivi che supportano le dimensioni di pagina di 16 kB

3. Avvia il dispositivo di test, poi esegui il comando seguente per verificare che utilizzi un ambiente da 16 kB:

   adb shell getconf PAGE_SIZE
   

   Il comando deve restituire un valore di 16384.

4. Esegui il seguente zipalign comando per verificare che l'app sia allineata a 16 kB, dove APK_NAME è il nome del file APK dell'app:

   zipalign -c -P 16 -v 4 APK_NAME.apk
   

5. Testa attentamente l'app, concentrandoti su tutte le aree che potrebbero essere interessate da modificando le istanze di codice che fanno riferimento a dimensioni di pagina specifiche.

Configurare l'emulatore Android con un'immagine di sistema basata su 16 kB

Per configurare un ambiente da 16 kB utilizzando l'emulatore Android, segui questi passaggi:

1. In Android Studio, fai clic su Strumenti > SDK Manager.

2. Nella scheda SDK Platforms (Piattaforme SDK), seleziona Show Package Details (Mostra dettagli pacchetto), poi espandi la sezione Android VanillaIceCream o versioni successive e seleziona una o entrambe le seguenti immagini di sistema dell'emulatore, a seconda dei dispositivi virtuali che vuoi creare:

   • API di Google sperimentali 16 kB Page Size ARM 64 v8a Immagine di sistema
   • API di Google sperimentale 16 kB Page Size Intel x86_64 Atom immagine di sistema

   

3. Fai clic su Applica > OK per scaricare le immagini di sistema selezionate.

4. Segui i passaggi per configurare un dispositivo virtuale per Android 15 e, quando ti viene chiesto di selezionare un'immagine di sistema, seleziona l'immagine di sistema da 16 kB che hai scaricato. Se non è consigliata automaticamente, puoi trovare l'immagine di sistema da 16 kB nella scheda Other Images (Altre immagini).

   

Avviare l'emulatore

Dopo aver completato la configurazione dell'emulatore Android e dei dispositivi virtuali, avvia l' emulatore dal menu del dispositivo di destinazione o dalla riga di comando.

Attivare la modalità a 16 kB su un dispositivo utilizzando le opzioni sviluppatore

Attiva l'opzione per sviluppatori Avvia con dimensione pagina 16 kB per avviare un dispositivo in modalità a 16 kB.

Nelle versioni QPR di Android 15, puoi utilizzare l'opzione sviluppatore disponibile su alcuni dispositivi per avviare il dispositivo in modalità 16 KB ed eseguire test sul dispositivo. Prima di utilizzare l'opzione sviluppatore, vai a Impostazioni > Sistema > Aggiornamenti software e applica gli aggiornamenti disponibili.

Questa opzione per sviluppatori è disponibile sui seguenti dispositivi:

• Pixel 8 e 8 Pro (con Android 15 QPR1 o versioni successive)

• Pixel 8a (con Android 15 QPR1 o versioni successive)

• Pixel 9, 9 Pro e 9 Pro XL (con Android 15 QPR2 o versioni successive)

• Pixel 9a (con Android 16 o versioni successive)

Modalità di compatibilità con le versioni precedenti a 16 kB

Avviso in modalità di compatibilità con le dimensioni di pagina

L'opzione di compatibilità con le versioni precedenti a 16 kB è disponibile quando un dispositivo è in esecuzione con un kernel da 16 kB. Il gestore di pacchetti esegue un'app in modalità di compatibilità con le versioni precedenti a 16 kB quando vengono soddisfatte le seguenti condizioni:

• Se l'app ha file ELF (con estensione .so) con un allineamento del segmento LOAD di 4 kB.
• Se l'APK compresso ha file ELF non compressi allineati a 4 kB.

Se il gestore di pacchetti ha attivato la modalità di compatibilità con le versioni precedenti a 16 kB per un'app, l'app mostra un avviso al primo avvio che indica che è in esecuzione in modalità di compatibilità con le versioni precedenti a 16 kB.

La modalità di compatibilità con le versioni precedenti a 16 kB consente ad alcune app di funzionare, ma per una maggiore affidabilità e stabilità, le app devono comunque essere allineate a 16 kB.

Nella pagina delle informazioni sull'app, in Avanzate, attiva o disattiva l'impostazione Esegui l'app in modalità di compatibilità con le dimensioni di pagina per attivare o disattivare la modalità di compatibilità con le versioni precedenti a 16 kB per un'app specifica. Questa impostazione è visibile solo quando il dispositivo è in esecuzione con dimensioni di pagina di 16 kB.

Impostazione della modalità di compatibilità con le dimensioni di pagina

Per forzare la compatibilità con le versioni precedenti a 16 kB per ogni app sul dispositivo:

adb shell setprop bionic.linker.16kb.app_compat.enabled true
adb shell setprop pm.16kb.app_compat.disabled false

Per disattivare la compatibilità con le versioni precedenti a 16 kB per ogni app sul dispositivo:

adb shell setprop bionic.linker.16kb.app_compat.enabled false
adb shell setprop pm.16kb.app_compat.disabled true

In Android 17, puoi anche disattivare la compatibilità con le versioni precedenti a 16 kB per ogni app e fare in modo che qualsiasi file binario incompatibile venga interrotto immediatamente:

    adb shell setprop bionic.linker.16kb.app_compat.enabled fatal
    adb shell setprop pm.16kb.app_compat.disabled true

Imposta la proprietà android:pageSizeCompat su attivata o disattivata per attivare o disattivare la modalità di compatibilità con le versioni precedenti per un'app specifica nel relativo file AndroidManifest.xml. Quando questa proprietà è impostata, l'app non mostra avvisi relativi alla modalità di compatibilità con le versioni precedenti all'avvio.

Requisito di compatibilità con Google Play

Poiché i produttori di dispositivi dotano i dispositivi di più RAM per ottimizzare le prestazioni, molti adotteranno dimensioni di pagina più grandi, come 16 kB. Per prepararsi al lancio di questi prossimi dispositivi, Google Play sta introducendo un nuovo requisito di compatibilità: a partire dal 1° novembre 2025, tutte le nuove app e gli aggiornamenti delle app esistenti inviati a Google Play e destinati ai dispositivi con Android 15 (livello API 35) e versioni successive devono supportare le dimensioni di pagina di 16 kB.

Per saperne di più su questo requisito di compatibilità, consulta questo post del blog.