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ù →

Historically, Android has only supported 4 KB memory page sizes, which has optimized system memory performance for the average amount of total memory that Android devices have typically had. Beginning with Android 15, AOSP supports devices that are configured to use a page size of 16 KB (16 KB devices). If your app uses any NDK libraries, either directly or indirectly through an SDK, then you will need to rebuild your app for it to work on these 16 KB devices.

As device manufacturers continue to build devices with larger amounts of physical memory (RAM), many of these devices will adopt 16 KB (and eventually greater) page sizes to optimize the device's performance. Adding support for 16 KB page size devices enables your app to run on these devices and helps your app benefit from the associated performance improvements. Without recompiling, apps won't work on 16 KB devices in future Android releases.

To help you add support for your app, we've provided guidance on how to check if your app is impacted, how to rebuild your app (if applicable), and how to test your app in a 16 KB environment using emulators (including Android 15 system images for the Android Emulator).

Vantaggi e miglioramenti delle prestazioni

Devices configured with 16 KB page sizes use slightly more memory on average, but also gain various performance improvements for both the system and apps:

• Lower app launch times while the system is under memory pressure: 3.16% lower on average, with more significant improvements (up to 30%) for some apps that we tested
• Reduced power draw during app launch: 4.56% reduction on average
• Faster camera launch: 4.48% faster hot starts on average, and 6.60% faster cold starts on average
• Improved system boot time: improved by 8% (approximately 950 milliseconds) on average

These improvements are based on our initial testing, and results on actual devices will likely differ. We'll provide additional analysis of potential gains for apps as we continue our testing.

Verificare se la tua app è interessata

If your app uses any native code, then you should rebuild your app with support for 16 KB devices. If you are unsure if your app uses native code, you can use the APK Analyzer to identify whether any native code is present and then check the alignment of ELF segments for any shared libraries that you find. Android Studio also provides features that help you to automatically detect alignment issues.

If your app only uses code written in the Java programming language or in Kotlin, including all libraries or SDKs, then your app already supports 16 KB devices. Nevertheless, we recommend that you test your app in a 16 KB environment to verify that there are no unexpected regressions in app behavior.

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.