Supporta architetture a 64 bit

Le app pubblicate su Google Play devono supportare le architetture a 64 bit. L'aggiunta di una versione a 64 bit della tua app consente di migliorare le prestazioni e di prepararsi per i dispositivi con hardware solo a 64 bit.

I passaggi che seguono ti assicurano che la tua app a 32 bit supporti i dispositivi a 64 bit.

Valutare l'app

Se la tua app utilizza solo codice scritto nel linguaggio di programmazione Java o in Kotlin, incluse tutte le librerie o gli SDK, supporta i dispositivi a 64 bit. Se la tua app utilizza codice nativo o non sai con certezza, valutala.

Controllo rapido dello stato

Vai a Play Console e controlla le release esistenti per verificare se sono conformi.

Play Console mostra anche gli avvisi che si applicano alle release in bozza se si verificano problemi relativi al requisito dei 64 bit. L'immagine seguente è un esempio.

Se viene visualizzato un avviso, segui i passaggi riportati di seguito per rendere la tua app compatibile con i dispositivi a 64 bit.

La tua app utilizza codice nativo?

La tua app utilizza codice nativo se:

• Utilizza codice C/C++ (nativo) nella tua app.
• Link con eventuali librerie native di terze parti.
• È stata creata da un generatore di app di terze parti che utilizza librerie native.

La tua app include librerie a 64 bit?

Controlla la struttura del file APK. Al momento della compilazione, l'APK viene pacchettizzato con le eventuali librerie native necessarie all'app. Le librerie native vengono memorizzate in varie cartelle in base all'ABI. Non è necessario supportare ogni architettura a 64 bit, ma per ogni architettura a 32 bit nativa supportata devi includere l'architettura a 64 bit corrispondente.

Per l'architettura ARM, le librerie a 32 bit si trovano in armeabi-v7a. L'equivalente a 64 bit è arm64-v8a.

Per l'architettura x86, cerca x86 per 32 bit e x86_64 per 64 bit.

Assicurati di avere librerie native in entrambe le cartelle. Ricapitoliamo:

Tieni presente che, a seconda dell'app, in ogni cartella potrebbe essere presente o meno lo stesso insieme di librerie. L'obiettivo è assicurarti che l'app funzioni correttamente in un ambiente solo a 64 bit.

In un caso normale, un APK o un bundle creato sia per le architetture a 32 bit sia per quelle a 64 bit ha cartelle per entrambi gli ABI, ciascuno con un insieme corrispondente di librerie native. Se non è supportato il 64 bit, potresti vedere una cartella ABI a 32 bit, ma non una a 64 bit.

Cercare le librerie native utilizzando APK Analyzer

APK Analyzer è uno strumento che ti consente di valutare vari aspetti di un APK compilato. Utilizzalo per trovare eventuali librerie native e assicurarti che siano presenti librerie a 64 bit.

1. Apri Android Studio e apri un progetto.

2. Dal menu, seleziona Build > Analizza APK…

   

3. Scegli l'APK che vuoi valutare.

4. Cerca nella cartella lib, che ospita eventuali file ".so". Se non ce ne sono, la tua app supporta i dispositivi a 64 bit e non è richiesta alcuna azione aggiuntiva. Se vedi armeabi-v7a o x86, significa che hai librerie a 32 bit.

5. Controlla se hai file ".so" simili nella cartella arm64-v8a o x86_64.

   

6. Se non hai librerie arm64-v8a o x86_64, aggiorna il processo di compilazione per iniziare a compilare e pacchettizzare questi elementi nell'APK.

7. Se vedi già che entrambe le librerie vengono pacchettizzate, puoi andare avanti e testare la tua app su hardware a 64 bit.

Cercare le librerie native scompattando gli APK

I file APK sono strutturati come file ZIP. Estrai il file APK con la riga di comando o con qualsiasi altro strumento di estrazione. A seconda dello strumento di estrazione, potrebbe essere necessario rinominare il file in .zip.

Sfoglia i file estratti seguendo le indicazioni riportate sopra per determinare se la tua app supporta i dispositivi a 64 bit. Puoi eseguire il seguente esempio di comando dalla riga di comando:

:: Command Line
> zipinfo -1 YOUR_APK_FILE.apk | grep \.so$
lib/armeabi-v7a/libmain.so
lib/armeabi-v7a/libmono.so
lib/armeabi-v7a/libunity.so
lib/arm64-v8a/libmain.so
lib/arm64-v8a/libmono.so
lib/arm64-v8a/libunity.so

In questo esempio, nota la presenza delle librerie armeabi-v7a e arm64-v8a, il che significa che l'app supporta le architetture a 64 bit.

Creare l'app con librerie a 64 bit

Le istruzioni riportate di seguito descrivono come compilare le librerie a 64 bit. Tieni presente che questi passaggi riguardano solo la compilazione del codice e delle librerie che puoi compilare da sorgente.

Esegui la compilazione con Android Studio o Gradle

La maggior parte dei progetti Android Studio utilizza Gradle come sistema di compilazione sottostante, pertanto questa sezione si applica a entrambi i casi. Per attivare le build per il codice nativo, aggiungi arm64-v8a e/o x86_64, a seconda delle architetture che vuoi supportare, all'impostazione ndk.abiFilters nel file 'build.gradle' della tua app:

// Your app's build.gradle
plugins {
  id 'com.android.app'
}

android {
   compileSdkVersion 27
   defaultConfig {
       appId "com.google.example.64bit"
       minSdkVersion 15
       targetSdkVersion 28
       versionCode 1
       versionName "1.0"
       ndk.abiFilters 'armeabi-v7a','arm64-v8a','x86','x86_64'
// ...

// Your app's build.gradle
plugins {
    id("com.android.app")
}

android {
    compileSdkVersion(27)
    defaultConfig {
        appId = "com.google.example.64bit"
        minSdkVersion(15)
        targetSdkVersion(28)
        versionCode = 1
        versionName = "1.0"
        ndk {
            abiFilters += listOf("armeabi-v7a","arm64-v8a","x86","x86_64")
        }
// ...

Creare con CMake

Se la tua app viene compilata utilizzando CMake, puoi eseguire la compilazione per le ABI a 64 bit passando arm64-v8a al parametro "-DANDROID_ABI":

:: Command Line
> cmake -DANDROID_ABI=arm64-v8a … or
> cmake -DANDROID_ABI=x86_64 …

Compilare con ndk-build

Se la tua app è compilata con ndk-build, puoi eseguire la compilazione per le ABI a 64 bit modificando il file 'Application.mk' utilizzando la variabile APP_ABI:

APP_ABI := armeabi-v7a arm64-v8a x86 x86_64

Eseguire il porting del codice a 32 bit a 64 bit

Se il codice viene già eseguito su computer o iOS, non dovresti dover fare altro per Android. Se è la prima volta che il codice viene compilato per un sistema a 64 bit, il problema principale che devi affrontare è che i puntatori non rientrano più nei tipi di interi a 32 bit come int.

Aggiorna il codice che memorizza i puntatori in tipi come int, unsigned o uint32_t. Sui sistemi Unix, long corrisponde alle dimensioni del cursore, ma non su Windows. Utilizza invece i tipi che rivelano l'intenzione uintptr_t o intptr_t. Per memorizzare la differenza tra due puntatori, utilizza il tipo ptrdiff_t.

Devi sempre preferire i tipi di numeri interi specifici a larghezza fissa definiti in <stdint.h> anziché i tipi a larghezza variabile come int o long, anche per i non puntatori.

Utilizza i seguenti flag del compilatore per rilevare i casi in cui il codice esegue conversioni errate tra puntatori e interi:

-Werror=pointer-to-int-cast
-Werror=int-to-pointer-cast
-Werror=shorten-64-to-32

Le classi Java con campi int che contengono puntatori a oggetti C/C++ presentano lo stesso problema. Cerca jint nel codice sorgente JNI e assicurati di passare a long lato Java e jlong lato C++.

Le dichiarazioni di funzioni implicite sono molto più pericolose per il codice a 64 bit. C/C++ assume che il tipo di ritorno di una funzione dichiarata implicitamente (ovvero una funzione per la quale il compilatore non ha visto una dichiarazione) sia int. Se il tipo di ritorno effettivo della funzione è un puntatore, funziona bene su un sistema a 32 bit in cui il puntatore si inserisce in un int. Tuttavia, su un sistema a 64 bit, il compilatore elimina la metà superiore del puntatore. Ad esempio:

// This function returns a pointer:
// extern char* foo();

// If you don't include a header that declares it,
// when the compiler sees this:
char* result = foo();

// Instead of compiling that to:
result = foo();

// It compiles to something equivalent to:
result = foo() & 0xffffffff;

// Which will then cause a SIGSEGV if you try to dereference `result`.

Il seguente flag del compilatore trasforma gli avvisi relativi alla dichiarazione di funzioni implicite in errori in modo da poter trovare e risolvere questo problema più facilmente:

-Werror=implicit-function-declaration

Se hai assembler in linea, riscrivilo o utilizza un'implementazione C/C++ semplice.

Se hai dimensioni di tipi hardcoded (ad esempio 8 o 16 byte), sostituiscile con l'espressione sizeof(T) equivalente, ad esempio sizeof(void*).

Se devi compilare in modo condizionale codice diverso per 32 bit e 64 bit, puoi utilizzare #if defined(__LP64__) per le differenze generiche 32/64 oppure __arm__, __aarch64__ (arm64), __i386__ (x86) e __x86_64__ per le architetture specifiche supportate da Android.

Modifica le stringhe di formato per le funzioni simili a printf o scanf, poiché i tradizionali specificatori di formato non ti consentono di specificare tipi a 64 bit in modo corretto sia per i dispositivi a 32 bit sia per quelli a 64 bit. Le macro PRI e SCN in <inttypes.h> risolvono questo problema, PRIxPTR e SCNxPTR per scrivere e leggere puntatori esadecimali; e PRId64 e SCNd64 per scrivere e leggere valori a 64 bit in modo portabile.

Quando esegui lo spostamento, potresti dover utilizzare 1ULL per ottenere una costante a 64 bit da spostare piuttosto che 1, che è di soli 32 bit.

Ridurre gli aumenti delle dimensioni con Android App Bundle

L'aggiunta del supporto dell'architettura a 64 bit alla tua app può causare un aumento delle dimensioni dell'APK. Ti consigliamo vivamente di sfruttare la funzionalità Android App Bundle per ridurre al minimo l'impatto sulle dimensioni derivante dall'inclusione del codice nativo a 32 e 64 bit nello stesso APK.

Sviluppatori di giochi

I tre motori più utilizzati supportano il 64 bit:

• Unreal dal 2015
• Cocos2d dal 2015
• Unity dal 2018

Sviluppatori Unity

Eseguire l'upgrade alle versioni idonee

Unity fornisce il supporto a 64 bit con le versioni 2018.2 e 2017.4.16.

Se utilizzi una versione di Unity che non supporta il 64 bit, determina la versione a cui vuoi eseguire l'upgrade e segui le guide fornite da Unity per eseguire la migrazione del tuo ambiente, assicurandoti che l'upgrade dell'app venga eseguito a una versione che può creare librerie a 64 bit. Unity consiglia di accedere alle funzionalità e agli aggiornamenti più recenti eseguendo l'upgrade alla versione LTS più recente dell'editor.

Ecco un grafico che illustra le varie versioni di Unity e cosa devi fare:

Modificare le impostazioni di compilazione per generare librerie a 64 bit

Se utilizzi una versione di Unity che supporta le librerie Android a 64 bit, puoi generare una versione a 64 bit della tua app modificando le impostazioni di compilazione. Utilizza il backend IL2CPP come backend di scripting. Per configurare il progetto Unity per la compilazione dell'architettura a 64 bit:

1. Vai a Impostazioni di compilazione e assicurati di eseguire la compilazione per Android verificando che il simbolo di Unity sia accanto ad Android in Piattaforma. 1. Se il simbolo di Unity non è accanto alla piattaforma Android, seleziona Android e fai clic su Cambia piattaforma.

2. Fai clic su Impostazioni del player.

   

3. Vai a Pannello delle impostazioni del player > Impostazioni per Android > Altre impostazioni > Configurazione

4. Imposta Scripting Backend su IL2CPP.

5. Seleziona la casella di controllo Architettura di destinazione > ARM64.

   

6. Esegui la compilazione come di consueto.

Tieni presente che la compilazione per ARM64 richiede che tutti gli asset vengano compilati specificamente per quella piattaforma. Segui le linee guida di Unity per ridurre le dimensioni dell'APK e valuta la possibilità di sfruttare la funzionalità Android App Bundle per contribuire ad attenuare questo aumento di dimensioni.

Conformità a più APK e a 64 bit

Se utilizzi il supporto di più APK di Google Play per pubblicare la tua app, tieni presente che la conformità al requisito dei 64 bit viene valutata a livello di release. Tuttavia, il requisito dei 64 bit non si applica agli APK o agli app bundle che non vengono distribuiti su dispositivi con Android 9 Pie o versioni successive.

Se uno dei tuoi APK è contrassegnato come non conforme, ma è una versione precedente e non è possibile renderlo conforme, una strategia è aggiungere un attributo maxSdkVersion="27" all'elemento uses-sdk nel manifest dell'APK. Questo APK non viene caricato sui dispositivi con Android 9 Pie o versioni successive e non blocca più la conformità.

Conformità a RenderScript e 64 bit

Se la tua app utilizza RenderScript ed è stata compilata con una versione precedente degli strumenti Android, potresti riscontrare problemi di conformità a 64 bit per l'app. Con gli strumenti di compilazione precedenti alla versione 21.0.0, il compilatore potrebbe generare il codice bit in un file .bc esterno. Questi file .bc precedenti non sono più supportati per le architetture a 64 bit, pertanto la presenza del file nell'APK causa il problema di conformità.

Per risolvere il problema, rimuovi tutti i file .bc nel progetto, esegui l'upgrade dell'ambiente alla versione build-tools-21.0.0 o successiva e imposta renderscriptTargetApi in Android Studio su una versione successiva alla 21 per indicare al compilatore di non emettere file .bc. Dopodiché, ricostruisci l'app, controlla la presenza di file .bc e caricala su Play Console.

Testa la tua app su hardware a 64 bit

La versione a 64 bit della tua app deve offrire la stessa qualità e lo stesso insieme di funzionalità della versione a 32 bit. Testa la tua app per assicurarti che gli utenti che utilizzano i dispositivi a 64 bit più recenti abbiano un'esperienza ottimale.

Dispositivi solo a 64 bit

Se possibile, ti consigliamo di testare l'app in un ambiente rigorosamente solo a 64 bit utilizzando una delle seguenti opzioni:

• Google Pixel con un'immagine di sistema solo a 64 bit
• Emulatore Android

Google Pixel con un'immagine di sistema solo a 64 bit

Per semplificare lo sviluppo e il test delle app, abbiamo fornito immagini di sistema speciali con un ambiente rigorosamente solo a 64 bit per alcuni dispositivi Pixel. Queste immagini solo a 64 bit erano originariamente fornite contemporaneamente alle immagini di sistema di fabbrica standard per le release di anteprima di Android 13 e 14, ma puoi continuare a utilizzarle mentre testi la compatibilità a 64 bit della tua app.

Ottenere un'immagine solo a 64 bit

Come per le immagini di sistema di fabbrica, puoi eseguire il flashing di un'immagine solo a 64 bit sul tuo dispositivo utilizzando Android Flash Tool o eseguendo il flashing manualmente sul tuo dispositivo, come descritto nelle sezioni seguenti.

Eseguire il flashing del dispositivo utilizzando Android Flash Tool

Android Flash Tool ti consente di eseguire il flashing di un'immagine di sistema in modo sicuro sul tuo dispositivo Pixel supportato. Android Flash Tool funziona con qualsiasi browser web che supporta WebUSB, ad esempio Chrome o Edge 79 e versioni successive.

Android Flash Tool ti guida passo passo nella procedura di flashing del dispositivo. Non è necessario installare strumenti, ma devi sbloccare il dispositivo e attivare il debug USB nelle Opzioni sviluppatore. Per istruzioni complete, consulta la documentazione di Android Flash Tool.

Collega il dispositivo tramite USB, quindi, a seconda del tipo di immagine di sistema che vuoi eseguire il flashing, vai ad Android Flash Tool utilizzando uno dei seguenti link e segui le istruzioni sullo schermo:

• Immagini di sistema solo a 64 bit di Android 14 (beta 5.2)

  Seleziona il dispositivo su cui stai tentando di eseguire il flashing:

  • Pixel 4a (5G)
  • Pixel 5
  • Pixel 6
  • Pixel 6 Pro

• Immagini di sistema solo a 64 bit di Android 13 (QPR3 Beta 3.2)

  Seleziona il dispositivo su cui stai tentando di eseguire il flashing:

  • Pixel 4a (5G)
  • Pixel 5
  • Pixel 6
  • Pixel 6 Pro

Eseguire il flashing del dispositivo manualmente

Puoi anche scaricare l'immagine di sistema più recente ed eseguirne il flashing manualmente sul dispositivo. Consulta la tabella seguente per scaricare l'immagine di sistema per il tuo dispositivo di test. Il flashing manuale di un dispositivo è utile se hai bisogno di un controllo preciso sull'ambiente di test o se devi reinstallare di frequente, ad esempio quando esegui test automatici.

Dopo aver eseguito il backup dei dati del dispositivo e scaricato l'immagine di sistema corrispondente, puoi eseguire il flashing dell'immagine sul dispositivo.

Puoi scegliere di tornare all'ultima build pubblica in qualsiasi momento.

Immagini del produttore solo a 64 bit per Android 14 (beta 5.3)

Queste immagini forniscono un ambiente rigoroso solo a 64 bit per testare la compatibilità delle app a 64 bit. Queste configurazioni solo a 64 bit sono destinate esclusivamente agli sviluppatori.

Immagini del produttore solo a 64 bit per Android 13 (QPR3 Beta 3.2)

Queste immagini forniscono un ambiente rigoroso solo a 64 bit per testare la compatibilità delle app a 64 bit. Queste configurazioni solo a 64 bit sono destinate esclusivamente agli sviluppatori.

Tornare a una build pubblica

Puoi utilizzare Android Flash Tool per aggiornare il firmware dell'immagine del produttore oppure ottenere un'immagine di sistema con le specifiche di fabbrica dalla pagina Immagini del produttore per dispositivi Nexus e Pixel e poi aggiornare manualmente il firmware del dispositivo.

Emulatore Android

A partire da Android 12 (livello API 31), le immagini di sistema di Android Emulator sono solo a 64 bit. Crea un dispositivo virtuale Android (AVD) utilizzando un'immagine di sistema con Android 12 (livello API 31) o versioni successive per ottenere un ambiente rigoroso solo a 64 bit per il test delle app.

Altre opzioni per il dispositivo

Se non hai uno di questi dispositivi o non puoi utilizzare l'emulatore Android, la migliore opzione alternativa è utilizzare un dispositivo compatibile con 64 bit, ad esempio un Google Pixel o altri dispositivi di punta recenti di altri produttori di dispositivi.

Installa e testa l'app

Il modo più semplice per testare l'APK è installare l'app utilizzando Android Debug Bridge (adb). Nella maggior parte dei casi, puoi fornire --abi come parametro per indicare le librerie da installare sul dispositivo. In questo modo, sul dispositivo viene installata solo l'app con le librerie a 64 bit.

:: Command Line
# A successful install:
> adb install --abi armeabi-v7a YOUR_APK_FILE.apk
Success

# If your APK does not have the 64-bit libraries:
> adb install --abi arm64-v8a YOUR_APK_FILE.apk
adb: failed to install YOUR_APK_FILE.apk: Failure [INSTALL_FAILED_NO_MATCHING_ABIS: Failed to extract native libraries, res=-113]

# If your device does not support 64-bit, an emulator, for example:
> adb install --abi arm64-v8a YOUR_APK_FILE.apk
ABI arm64-v8a not supported on this device

Una volta completata l'installazione, testa l'app come faresti normalmente per verificare che la qualità sia la stessa della versione a 32 bit.

Verificare la presenza di problemi di compatibilità noti

Durante il test, controlla la tua app per verificare la presenza dei seguenti problemi che interessano le app quando vengono eseguite su dispositivi a 64 bit. Anche se la tua app non dipende direttamente dalle librerie interessate, è possibile che lo facciano le librerie e gli SDK di terze parti nelle dipendenze dell'app.

SoLoader

Se utilizzi l'SDK loader del codice nativo SoLoader, esegui l'aggiornamento alla versione 0.10.4 o successive. Se la tua app utilizza SDK che dipendono da SoLoader, assicurati di eseguire l'aggiornamento anche alla versione stabile più recente degli SDK interessati.

SoLoader 0.9.0 e versioni precedenti presuppongono che le librerie di sistema siano presenti in /vendor/lib:/system/lib. Questo bug non è osservabile su dispositivi come Pixel 7, dove il percorso esiste, ma questa assunzione causa arresti anomali nei dispositivi che hanno solo librerie di sistema in /vendor/lib64:/system/lib64.

Per ulteriori informazioni su come risolvere questo e altri problemi causati da SoLoader, consulta la risposta corrispondente nel Centro assistenza Google.

OpenSSL

Se utilizzi la libreria OpenSSL, esegui l'aggiornamento a OpenSSL 1.1.1i o versioni successive. Se la tua app utilizza SDK che forniscono comunicazioni tramite HTTPS o altri SDK che dipendono da OpenSSL, assicurati di eseguire l'aggiornamento anche all'ultima versione dell'SDK che utilizza una versione di OpenSSL più recente. Contatta il provider di SDK se non è disponibile.

ARMv8.3 PAC consente l'integrità del flusso di controllo con supporto hardware autenticando i puntatori durante il runtime. Le versioni precedenti di OpenSSL utilizzano queste funzionalità in modo errato, causando arresti anomali in fase di runtime in tutti i dispositivi con processori basati su ARMv8.3a e versioni successive.

Per ulteriori informazioni su come risolvere questo e altri problemi causati da OpenSSL, consulta la risposta corrispondente nel Centro assistenza Google.

BTI

ARMv8.5 e versioni successive utilizzano le istruzioni di destinazione del ramo (BTI) per contribuire a proteggersi dagli attacchi JOP. Le versioni precedenti degli SDK di offuscamento che si ramificano in offset casuali delle librerie create con BTI possono causare l'arresto anomalo delle app. Poiché le istruzioni sono codificate come HINT, questo bug non è osservabile nei dispositivi che non supportano BTI.

Pubblica

Quando ritieni che la tua app sia pronta, pubblicala normalmente. Come sempre, continua a seguire le best practice per il deployment dell'app. Ti consigliamo di sfruttare i canali di test chiuso per implementare l'app per un numero limitato di utenti, in modo da garantire la qualità costante dell'app.

Come per l'implementazione di un aggiornamento importante, assicurati di aver eseguito test approfonditi su dispositivi compatibili con 64 bit prima di pubblicare per un pubblico più ampio.