Mendukung arsitektur 64-bit

Aplikasi yang dipublikasikan di Google Play harus mendukung arsitektur 64-bit. Menambahkan aplikasi versi 64-bit akan meningkatkan performa dan menyiapkan aplikasi untuk perangkat dengan hardware yang hanya mendukung arsitektur 64-bit.

Langkah-langkah berikut memastikan bahwa aplikasi 32-bit Anda mendukung perangkat 64-bit.

Menilai aplikasi Anda

Jika aplikasi Anda hanya menggunakan kode yang ditulis dalam bahasa pemrograman Java atau di Kotlin, termasuk semua library atau SDK, berarti aplikasi tersebut mendukung perangkat 64-bit. Nilai aplikasi Anda jika aplikasi menggunakan kode native atau Anda tidak yakin kode apa yang digunakan.

Pemeriksaan status cepat

Buka Konsol Play, lalu lihat rilis yang sudah ada untuk melihat apakah rilis tersebut telah mematuhi persyaratan.

Jika terdapat masalah terkait persyaratan 64-bit, Konsol Play juga akan menampilkan peringatan untuk rilis draf Anda. Gambar berikut adalah contohnya.

Jika peringatan muncul, lihat langkah-langkah berikut untuk membuat aplikasi Anda kompatibel dengan perangkat 64-bit.

Apakah aplikasi Anda menggunakan kode native?

Aplikasi Anda menggunakan kode native jika:

• Menggunakan kode C/C++ (native) pada aplikasi.
• Terhubung dengan library native pihak ketiga.
• Dibuat oleh pembuat aplikasi pihak ketiga yang menggunakan library native.

Apakah aplikasi Anda menyertakan library 64-bit?

Periksa struktur file APK Anda. Saat dibangun, APK dikemas dengan library native yang dibutuhkan oleh aplikasi. Library native disimpan di berbagai folder berdasarkan ABI. Dukungan pada setiap arsitektur 64-bit tidak diperlukan, tetapi Anda harus menyertakan arsitektur 64-bit yang sesuai untuk setiap arsitektur 32-bit native yang didukung.

Untuk arsitektur ARM, library 32-bit terletak di armeabi-v7a. Sementara itu, library 64-bit terletak di arm64-v8a.

Untuk arsitektur x86, cari x86 untuk 32-bit dan x86_64 untuk 64-bit.

Pastikan Anda memiliki library native di kedua folder ini. Ringkasnya:

Perlu diingat bahwa bergantung pada aplikasi Anda, mungkin akan ada set library yang sama persis di setiap folder, mungkin juga tidak. Tujuannya adalah untuk memastikan aplikasi Anda berjalan dengan benar di lingkungan khusus 64-bit.

Pada umumnya, APK atau bundle yang dibangun untuk arsitektur 32-bit dan 64-bit memiliki folder untuk kedua ABI, masing-masing dengan kumpulan library native terkait. Jika tidak ada dukungan untuk 64-bit, Anda mungkin akan melihat folder ABI 32-bit tetapi tidak melihat folder 64-bit.

Mencari library native menggunakan APK Analyzer

APK Analyzer adalah alat yang memungkinkan Anda mengevaluasi berbagai aspek APK yang telah dibangun. Gunakan alat ini untuk menemukan library native, dan memastikan adanya library 64-bit.

1. Buka Android Studio, lalu buka project apa saja.

2. Dari menu, pilih Build > Analyze APK…

   

3. Pilih APK yang ingin Anda evaluasi.

4. Lihat di dalam folder lib, yang menghosting file '.so' jika ada. Jika tidak ada, berarti aplikasi Anda mendukung perangkat 64-bit dan Anda tidak perlu melakukan tindakan lebih lanjut. Jika Anda melihat armeabi-v7a atau x86, berarti Anda memiliki library 32-bit.

5. Periksa untuk memastikan ada file '.so' yang mirip di folder arm64-v8a atau x86_64.

   

6. Jika library arm64-v8a atau x86_64 tidak ada, perbarui proses build Anda untuk mulai membangun dan mengemas artefak tersebut dalam APK.

7. Jika kedua library sudah dikemas, Anda dapat langsung membuka menguji aplikasi pada hardware 64-bit.

Mencari library native dengan mengekstrak APK

File APK memiliki struktur seperti file ZIP. Dengan command line atau alat ekstraksi lainnya, ekstrak file APK tersebut. Bergantung pada alat ekstraksi, Anda mungkin harus mengganti nama file menjadi .zip.

Temukan file yang diekstrak, dengan mengikuti panduan di atas untuk menentukan apakah aplikasi Anda mendukung perangkat 64-bit. Anda dapat menjalankan contoh perintah berikut dari command line:

:: 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

Perhatikan bahwa dalam contoh ini, terdapat library armeabi-v7a dan arm64-v8a, yang berarti aplikasi Anda mendukung arsitektur 64-bit.

Membangun aplikasi dengan library 64-bit

Petunjuk berikut menguraikan cara membangun library 64-bit. Perhatikan bahwa langkah-langkah ini hanya mencakup cara membangun kode dan library yang dapat Anda bangun dari sumber.

Membangun aplikasi dengan Android Studio atau Gradle

Sebagian besar project Android Studio menggunakan Gradle sebagai sistem build yang mendasarinya, sehingga bagian ini berlaku pada kedua kasus. Guna mengaktifkan build untuk kode native, tambahkan arm64-v8a dan/atau x86_64, tergantung pada arsitektur yang ingin Anda dukung, ke setelan ndk.abiFilters dalam file 'build.gradle' aplikasi:

// 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")
        }
// ...

Membangun aplikasi dengan CMake

Jika aplikasi Anda dibangun menggunakan CMake, Anda dapat membangun untuk ABI 64-bit dengan meneruskan arm64-v8a ke parameter '-DANDROID_ABI':

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

Membangun aplikasi dengan ndk-build

Jika aplikasi dibangun dengan ndk-build, Anda dapat membangun untuk ABI 64-bit dengan memodifikasi file 'Application.mk' menggunakan variabel APP_ABI:

APP_ABI := armeabi-v7a arm64-v8a x86 x86_64

Melakukan porting kode 32-bit ke 64-bit

Jika kode Anda sudah berjalan pada desktop atau iOS, Anda tidak perlu melakukan tindakan tambahan untuk Android. Jika ini pertama kalinya Anda membangun kode untuk sistem 64-bit, masalah utama yang harus diatasi adalah pointer yang tidak lagi sesuai dengan jenis integer 32-bit seperti int.

Perbarui kode yang menyimpan pointer dalam jenis seperti int, unsigned, atau uint32_t. Pada sistem Unix, long cocok dengan ukuran pointer, tetapi berbeda halnya pada Windows. Sebagai gantinya, gunakan jenis yang menampakkan intent uintptr_t atau intptr_t. Untuk menyimpan perbedaan antara dua pointer, gunakan jenis ptrdiff_t.

Anda harus selalu memilih jenis integer spesifik dengan lebar tetap yang ditentukan dalam <stdint.h>, bukan jenis integer dengan lebar non-tetap seperti int atau long, bahkan untuk non-pointer.

Gunakan flag compiler berikut untuk merekam kasus saat kode Anda salah mengonversi antara pointer dan integer:

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

Class Java dengan kolom int yang menampung pointer untuk objek C/C++ memiliki masalah yang sama. Telusuri jint di sumber JNI dan pastikan Anda beralih ke long pada sistem Java dan jlong pada sistem C++.

Deklarasi fungsi implisit jauh lebih berbahaya untuk kode 64-bit. C/C++ menganggap int sebagai jenis nilai yang ditampilkan dari fungsi yang dideklarasikan secara implisit (artinya fungsi yang deklarasinya belum dilihat oleh compiler). Jika jenis nilai yang ditampilkan sebenarnya untuk fungsi Anda berupa pointer, jenis nilai yang ditampilkan ini akan berfungsi dengan baik pada sistem 32-bit, dengan pointer akan sesuai dengan int. Namun, pada sistem 64-bit, compiler berada di separuh bagian atas pointer Anda. Contoh:

// 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`.

Flag compiler berikut mengubah peringatan deklarasi fungsi implisit menjadi error sehingga Anda dapat menemukan dan memperbaiki masalah ini dengan lebih mudah:

-Werror=implicit-function-declaration

Jika Anda memiliki assembler inline, tulis ulang atau gunakan implementasi C/C++ biasa.

Jika memiliki ukuran jenis hard code (misalnya 8 atau 16 byte), ganti dengan ekspresi sizeof(T) yang setara, seperti sizeof(void*).

Jika perlu mengompilasi kode yang berbeda secara kondisional untuk 32-bit dan 64-bit, Anda dapat menggunakan #if defined(__LP64__) untuk perbedaan 32/64 umum, atau __arm__, __aarch64__ (arm64), __i386__ (x86), dan __x86_64__ untuk arsitektur tertentu yang didukung oleh Android.

Sesuaikan string format untuk fungsi yang menyerupai printf atau scanf, karena penentu format tradisional tidak mengizinkan Anda menentukan jenis 64-bit dengan cara yang benar untuk perangkat 32-bit dan juga 64-bit. Makro PRI dan SCN dalam <inttypes.h> dapat mengatasi masalah ini, PRIxPTR dan SCNxPTR untuk menulis dan membaca pointer hex; serta PRId64 dan SCNd64 untuk menulis dan membaca nilai 64-bit secara portabel.

Saat melakukan peralihan, Anda harus menggunakan 1ULL untuk beralih ke konstanta 64-bit, bukannya menggunakan 1 yang hanya 32-bit.

Memigrasikan peningkatan ukuran dengan Android App Bundle

Penambahan dukungan arsitektur 64-bit ke aplikasi dapat menyebabkan ukuran APK bertambah besar. Kami sangat merekomendasikan penggunaan fitur Android App Bundle untuk meminimalkan dampak peningkatan ukuran pada kode native 32-bit dan 64-bit dalam APK yang sama.

Developer game

Tiga mesin yang paling sering digunakan mendukung 64-bit:

• Unreal sejak 2015
• Cocos2d sejak 2015
• Unity sejak 2018

Developer Unity

Mengupgrade ke versi yang mendukung

Unity menyediakan dukungan 64-bit pada versi 2018.2 dan 2017.4.16.

Jika menggunakan versi Unity yang tidak mendukung 64-bit, tentukan ke versi mana Anda ingin mengupgrade, dan ikuti panduan yang disediakan Unity untuk memigrasikan lingkungan Anda, guna memastikan bahwa aplikasi Anda diupgrade ke versi yang dapat membangun library 64-bit. Unity merekomendasikan Anda memiliki akses ke fitur dan update terbaru dengan mengupgrade ke versi LTS editor terbaru.

Berikut adalah diagram yang merangkum berbagai versi Unity dan tindakan yang harus Anda lakukan:

Mengubah setelan build untuk menghasilkan library 64-bit

Jika menggunakan versi Unity yang mendukung library Android 64-bit, Anda dapat membuat aplikasi versi 64-bit dengan menyesuaikan setelan build. Gunakan backend IL2CPP sebagai Scripting Backend Anda. Untuk menyiapkan project Unity guna membangun arsitektur 64-bit, lakukan hal berikut:

1. Buka Build Settings dan pastikan Anda membangun aplikasi untuk Android dengan memverifikasi bahwa simbol Unity berada di sebelah Android di bagian Platform. 1. Jika simbol Unity tidak berada di sebelah platform Android, pilih Android dan klik Switch Platform.

2. Klik Player settings.

   

3. Buka Player Settings Panel > Settings for Android > Other settings > Configuration

4. Setel Scripting Backend ke IL2CPP.

5. Pilih kotak centang Target Architecture > ARM64.

   

6. Bangun aplikasi seperti biasa.

Perhatikan bahwa membangun ARM64 mengharuskan semua aset Anda dibangun secara khusus untuk platform tersebut. Ikuti panduan Unity untuk mengurangi ukuran APK, dan pertimbangkan untuk memanfaatkan fitur Android App Bundle guna membantu mengurangi peningkatan ukuran.

Kepatuhan terhadap persyaratan arsitektur 64-bit dan Multi-APK

Jika menggunakan dukungan multi-APK dari Google Play untuk memublikasikan aplikasi, perhatikan bahwa kepatuhan terhadap persyaratan 64-bit akan dievaluasi pada tingkat rilis. Namun, persyaratan 64-bit ini tidak berlaku untuk APK atau app bundle yang tidak didistribusikan ke perangkat yang menjalankan Android 9 Pie atau yang lebih baru.

Jika salah satu APK Anda ditandai sebagai APK yang tidak mematuhi persyaratan, tetapi versinya lebih lama dan tidak mungkin dibuat untuk mematuhi persyaratan, salah satu strateginya adalah dengan menambahkan atribut maxSdkVersion="27" pada elemen uses-sdk dalam manifes APK tersebut. APK ini tidak dikirim ke perangkat yang menjalankan Android 9 Pie atau yang lebih baru, dan tidak lagi mengalami masalah kepatuhan.

Kepatuhan terhadap arsitektur 64-bit dan RenderScript

Jika aplikasi menggunakan RenderScript dan dibangun dengan alat Android versi lama, Anda mungkin akan mengalami masalah kepatuhan 64-bit untuk aplikasi tersebut. Dengan alat build versi sebelum 21.0.0, compiler dapat membuat bitcode ke file .bc eksternal. File .bc lama ini tidak lagi didukung untuk arsitektur 64-bit, jadi keberadaan file di dalam APK akan menyebabkan masalah kepatuhan.

Untuk mengatasi masalah ini, hapus semua file .bc dalam project Anda, upgrade lingkungan Anda ke versi build-tools-21.0.0 atau yang lebih baru, dan tetapkan renderscriptTargetApi di Android Studio ke versi 21+, agar compiler tidak menghasilkan file .bc. Lalu, bangun ulang aplikasi Anda, periksa apakah file .bc ada, dan upload ke Konsol Play.

Menguji aplikasi pada hardware 64-bit

Aplikasi versi 64-bit Anda harus menawarkan kualitas dan set fitur yang sama dengan versi 32-bit. Uji aplikasi Anda untuk memastikan bahwa pengguna perangkat 64-bit terbaru mendapatkan pengalaman terbaik pada aplikasi Anda.

Perangkat khusus 64-bit

Jika memungkinkan, sebaiknya uji aplikasi Anda di lingkungan khusus 64-bit yang ketat menggunakan salah satu opsi berikut:

• Google Pixel dengan image sistem khusus 64-bit
• Android Emulator

Google Pixel dengan image sistem khusus 64-bit

Untuk memfasilitasi pengembangan dan pengujian aplikasi, kami telah menyediakan image sistem khusus dengan lingkungan khusus 64-bit yang ketat untuk beberapa perangkat Pixel. Image khusus 64-bit ini awalnya disediakan bersamaan dengan image sistem factory standar untuk rilis pratinjau Android 13 dan 14, tetapi Anda dapat terus menggunakannya saat Anda menguji aplikasi untuk kompatibilitas 64-bit.

Mendapatkan image khusus 64-bit

Seperti pada image sistem factory, Anda dapat melakukan flash image khusus 64-bit ke perangkat menggunakan Android Flash Tool atau dengan mem-flash perangkat secara manual, seperti yang dijelaskan di bagian berikut.

Mem-flash perangkat menggunakan Android Flash Tool

Dengan Android Flash Tool, Anda dapat dengan aman mem-flash image sistem ke perangkat Pixel yang didukung. Android Flash Tool dapat digunakan dengan browser Web apa pun yang mendukung WebUSB, seperti Chrome atau Edge 79+.

Android Flash Tool memberikan panduan langkah demi langkah untuk mem-flash perangkat. Anda tidak perlu menginstal alat, cukup buka kunci perangkat dan aktifkan Proses Debug USB dari opsi Developer. Untuk mengetahui petunjuk selengkapnya, lihat dokumentasi Android Flash Tool.

Hubungkan perangkat Anda melalui USB, lalu, bergantung pada jenis image sistem yang ingin Anda flash, buka Android Flash Tool menggunakan salah satu link berikut dan ikuti panduan di layar:

• Image sistem Android 14 (Beta 5.2) khusus 64-bit

  Pilih perangkat yang akan Anda flash:

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

• Image sistem Android 13 (QPR3 Beta 3.2) khusus 64-bit

  Pilih perangkat yang akan Anda flash:

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

Mem-flash perangkat secara manual

Anda juga dapat mendownload versi image sistem terbaru dan mem-flash secara manual ke perangkat. Lihat tabel berikut untuk mendownload image sistem perangkat pengujian Anda. Mem-flash perangkat secara manual akan sangat berguna jika Anda memerlukan kontrol yang akurat atas lingkungan pengujian atau jika Anda perlu menginstal ulang berkali-kali, seperti saat melakukan pengujian otomatis.

Setelah mencadangkan data perangkat dan mendownload image sistem yang cocok, Anda dapat mem-flash image tersebut ke perangkat Anda.

Anda dapat memilih untuk kembali ke build publik terbaru kapan saja.

Setelan pabrik khusus 64-bit untuk Android 14 (Beta 5.3)

Setelan ini memberikan lingkungan khusus 64-bit yang ketat untuk menguji kompatibilitas aplikasi 64-bit. Konfigurasi khusus 64-bit ini hanya untuk penggunaan developer.

Setelan pabrik khusus 64-bit untuk Android 13 (QPR3 Beta 3.2)

Setelan ini memberikan lingkungan khusus 64-bit yang ketat untuk menguji kompatibilitas aplikasi 64-bit. Konfigurasi khusus 64-bit ini hanya untuk penggunaan developer.

Kembali ke build publik

Anda dapat menggunakan Android Flash Tool untuk mem-flash setelan pabrik atau mendapatkan image sistem spesifikasi pabrik dari halaman Setelan Pabrik untuk Perangkat Nexus dan Pixel, lalu mem-flash image tersebut secara manual ke perangkat.

Android Emulator

Mulai Android 12 (level API 31), image sistem Android Emulator adalah khusus 64-bit. Buat Perangkat Virtual Android (AVD) menggunakan image sistem dengan Android 12 (API level 31) atau yang lebih baru untuk mendapatkan lingkungan khusus 64-bit yang ketat untuk pengujian aplikasi.

Opsi perangkat lainnya

Jika tidak memiliki salah satu perangkat tersebut atau tidak dapat menggunakan Android Emulator, opsi terbaik berikutnya adalah menggunakan perangkat yang mendukung 64-bit, seperti Google Pixel atau perangkat flagship terbaru lainnya dari produsen perangkat lain.

Menginstal dan menguji aplikasi

Cara termudah untuk menguji APK Anda adalah dengan menginstal aplikasi menggunakan Android Debug Bridge (adb). Pada kebanyakan kasus, Anda dapat menyediakan --abi sebagai parameter untuk menunjukkan library yang akan diinstal ke perangkat. Tindakan ini akan menginstal aplikasi dengan hanya library 64-bit di perangkat.

:: 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

Setelah Anda berhasil menginstal, uji aplikasi seperti biasanya untuk memastikan kualitasnya sama dengan versi 32-bit.

Memeriksa masalah kompatibilitas umum

Saat melakukan pengujian, periksa aplikasi Anda untuk menemukan masalah berikut yang memengaruhi aplikasi saat berjalan di perangkat 64-bit. Meskipun aplikasi tidak bergantung pada library yang terpengaruh secara langsung, library dan SDK pihak ketiga dalam dependensi aplikasi mungkin terpengaruh.

SoLoader

Jika Anda menggunakan SDK loader kode native SoLoader, update ke versi v0.10.4 atau yang lebih baru. Jika aplikasi Anda menggunakan SDK yang bergantung pada SoLoader, pastikan Anda juga mengupdate ke versi stabil terbaru dari SDK yang terpengaruh.

SoLoader v0.9.0 dan yang lebih rendah menganggap bahwa library sistem ada di /vendor/lib:/system/lib. Bug ini tidak dapat diamati di perangkat seperti Pixel 7 tempat jalur tersebut ada, tetapi asumsi ini menyebabkan error di perangkat yang hanya memiliki library sistem di /vendor/lib64:/system/lib64.

Untuk informasi selengkapnya tentang cara memperbaiki masalah ini dan masalah lain yang disebabkan oleh SoLoader, lihat jawaban yang sesuai di Pusat Bantuan Google.

OpenSSL

Jika Anda menggunakan library OpenSSL, update ke OpenSSL 1.1.1i atau yang lebih baru. Jika aplikasi Anda menggunakan SDK yang menyediakan komunikasi menggunakan HTTPS, atau SDK lain yang bergantung pada OpenSSL, pastikan Anda juga mengupdate ke versi terbaru SDK yang menggunakan versi OpenSSL yang lebih baru. Hubungi penyedia SDK jika salah satu opsi tersebut tidak ada.

ARMv8.3 PAC memungkinkan integritas alur kontrol yang dibantu hardware dengan mengautentikasi pointer saat runtime. Versi OpenSSL sebelumnya menggunakan kemampuan ini dengan tidak benar, sehingga menyebabkan error runtime di semua perangkat dengan prosesor yang berbasis ARMv8.3a dan yang lebih baru.

Untuk informasi selengkapnya tentang cara memperbaiki masalah ini dan masalah lain yang disebabkan oleh OpenSSL, lihat jawaban yang sesuai di Pusat Bantuan Google.

BTI

ARMv8.5 dan yang lebih tinggi menggunakan Branch Target Instructions (BTI) untuk membantu melindungi dari serangan JOP. SDK obfuscation versi lama yang bercabang ke dalam offset acak library yang dibangun dengan BTI dapat menyebabkan aplikasi error. Karena petunjuknya dienkode sebagai HINT, bug ini tidak dapat diamati pada perangkat yang tidak mendukung BTI.

Publikasi

Setelah merasa aplikasi Anda siap, publikasikan seperti biasa. Terus ikuti praktik terbaik untuk men-deploy aplikasi Anda. Sebaiknya manfaatkan jalur pengujian tertutup untuk meluncurkan ke sejumlah kecil pengguna agar dapat memastikan konsistensi kualitas aplikasi Anda.

Seperti saat meluncurkan update besar, pastikan Anda telah menjalankan pengujian secara menyeluruh pada perangkat yang mendukung 64-bit sebelum memublikasikan ke pengguna yang lebih luas.