Android için geliştirme

Android cihazlarda kendi uygulamalarınızı serbestçe çalıştırabilirsiniz. Oyununuzun bir sürümünü derleyip bir Android cihaza kopyalamak çok kolaydır. Bu kılavuz, oyununuzu Android için paketleme adımlarını açıklar. Geliştirme sırasında oyununuzu geliştirme uygulaması üzerinden çalıştırmak genellikle tercih edilir; çünkü bu uygulama, içerik ve kodu doğrudan cihazınızda çalışma sırasında yeniden yüklemenize (hot reload) olanak tanır.

Android ve Google Play imzalama süreci

Android, tüm APK dosyalarının bir cihaza kurulmadan veya güncellenmeden önce bir sertifikayla dijital olarak imzalanmasını gerektirir. Android App Bundle (AAB) biçimini kullanıyorsanız Play Console’a yüklemeden önce yalnızca uygulama paketinizi imzalamanız gerekir; geri kalanını Play App Signing halleder. Bununla birlikte, uygulamanızı Google Play’e veya diğer uygulama mağazalarına yüklemek ve herhangi bir mağazanın dışında dağıtmak için elle de imzalayabilirsiniz.

Defold düzenleyicisinden veya komut satırı aracından bir Android uygulaması dağıtım paketi (bundle) oluştururken uygulamanızın imzalanmasında kullanılacak bir anahtar deposu (keystore; sertifikanızı ve anahtarınızı içerir) ve anahtar deposu parolası sağlayabilirsiniz. Bunları sağlamazsanız Defold bir hata ayıklama anahtar deposu oluşturur ve uygulamanın dağıtım paketini imzalarken bunu kullanır.

Anahtar deposu oluşturma

Bir anahtar deposunu Android Studio kullanarak veya bir terminalden/komut isteminden oluşturabilirsiniz:

keytool -genkey -v -noprompt -dname "CN=John Smith, OU=Area 51, O=US Air Force, L=Unknown, ST=Nevada, C=US" -keystore mykeystore.keystore -storepass 5Up3r_53cR3t -alias myAlias -keyalg RSA -validity 9125

Bu işlem, bir anahtar ve sertifika içeren mykeystore.keystore adlı bir anahtar deposu dosyası oluşturur. Anahtara ve sertifikaya erişim 5Up3r_53cR3t parolasıyla korunur. Anahtar ve sertifika 25 yıl (9125 gün) boyunca geçerli olur. Oluşturulan anahtar ve sertifika myAlias takma adıyla tanımlanır.

Android uygulaması dağıtım paketi oluşturma

Düzenleyici, oyununuz için kolayca bağımsız bir uygulama dağıtım paketi oluşturmanızı sağlar. Paketlemeden önce game.project proje ayarları dosyasında uygulama için kullanılacak simgeleri belirtebilir, sürüm kodunu ayarlayabilir ve benzeri işlemleri yapabilirsiniz.

Paketlemek için menüden Project ▸ Bundle... ▸ Android Application... seçeneğini seçin.

Düzenleyicinin otomatik olarak rastgele hata ayıklama sertifikaları oluşturmasını istiyorsanız Keystore ve Keystore password alanlarını boş bırakın:

Dağıtım paketinizi belirli bir anahtar deposuyla imzalamak istiyorsanız Keystore ve Keystore password alanlarını belirtin. Keystore dosyasının .keystore uzantısına sahip olması, parolanın ise .txt uzantılı bir metin dosyasında saklanması beklenir. Anahtar deposundaki anahtar, anahtar deposunun kendisinden farklı bir parola kullanıyorsa Key password belirtmeniz de mümkündür:

Defold hem APK hem de AAB dosyalarının oluşturulmasını destekler. Bundle Format açılır listesinden APK veya AAB seçin.

Uygulama dağıtım paketi ayarlarını yapılandırdıktan sonra Create Bundle düğmesine basın. Ardından, dağıtım paketinin bilgisayarınızda nerede oluşturulacağını belirtmeniz istenir.

Derleme çeşitleri

Bir oyunun dağıtım paketini oluştururken kullanmak istediğiniz motor türünü seçmeniz gerekir. Üç temel seçeneğiniz vardır:

• Debug
• Release
• Headless

Bu farklı sürümler derleme çeşitleri (Build variants) olarak da adlandırılır.

Debug

Bu tür yürütülebilir dosyalar, birkaç yararlı hata ayıklama özelliği içerdiği için genellikle oyun geliştirme sırasında kullanılır:

• Profil çıkarıcı (profiler) - Performans ve kullanım sayaçlarını toplamak için kullanılır. Profil çıkarıcının nasıl kullanılacağını Profil çıkarma kılavuzundan öğrenin.
• Günlüğe kaydetme (logging) - Günlüğe kaydetme etkinleştirildiğinde motor, sistem bilgilerini, uyarıları ve hataları günlüğe kaydeder. Motor ayrıca Lua’nın print() işlevinden ve dmLogInfo(), dmLogError() gibi işlevlerle günlüğe kaydeden yerel kod eklentilerinden (native extension) gelen günlükleri de çıktıya yazar. Bu günlükleri nasıl okuyacağınızı Oyun ve sistem günlükleri kılavuzundan öğrenin.
• Çalışma sırasında yeniden yükleme (hot reload) - Çalışma sırasında yeniden yükleme, geliştiricinin oyun çalışırken bir kaynağı (resource) yeniden yüklemesini sağlayan güçlü bir özelliktir. Bunu nasıl kullanacağınızı Çalışma sırasında yeniden yükleme kılavuzundan öğrenin.
• Motor hizmetleri (engine services) - Çeşitli açık TCP bağlantı noktaları ve hizmetler aracılığıyla bir oyunun hata ayıklama sürümüne bağlanmak ve bu sürümle etkileşim kurmak mümkündür. Bu hizmetler, yukarıda sözü edilen çalışma sırasında yeniden yükleme özelliğini, uzaktan günlük erişimini ve profil çıkarıcıyı, ayrıca motorla uzaktan etkileşim kurmaya yönelik başka hizmetleri de içerir. Motor hizmetleri hakkında daha fazla bilgi için geliştirici belgelerine bakın.

Release

Bu çeşitte hata ayıklama özellikleri devre dışıdır. Oyun, uygulama mağazasında yayımlanmaya veya başka yollarla oyuncularla paylaşılmaya hazır olduğunda bu seçeneğin seçilmesi önerilir. Bir oyunu hata ayıklama özellikleri etkin durumdayken yayımlamak çeşitli nedenlerle önerilmez:

• Hata ayıklama özellikleri ikili dosyada az da olsa yer kaplar ve yayımlanan bir oyunun ikili dosya boyutunu olabildiğince küçük tutmaya çalışmak iyi bir uygulamadır.
• Hata ayıklama özellikleri az da olsa CPU süresi de kullanır. Kullanıcının donanımı düşük özelliklere sahipse bu durum oyunun performansını etkileyebilir. Cep telefonlarında artan CPU kullanımı, ısınmaya ve pilin tükenmesine de katkıda bulunur.
• Hata ayıklama özellikleri, güvenlik, hile veya dolandırıcılık açısından oyuncuların görmesi amaçlanmayan oyun bilgilerini açığa çıkarabilir.

Headless

Bu yürütülebilir dosya herhangi bir grafik veya ses olmadan çalışır. Bu, oyunun birim/duman testlerini (unit/smoke tests) bir sürekli tümleştirme (CI) sunucusunda çalıştırabileceğiniz, hatta bu dosyayı bulutta bir oyun sunucusu olarak kullanabileceğiniz anlamına gelir.

Android uygulaması dağıtım paketini kurma

APK kurma

Bir .apk dosyası adb aracıyla cihazınıza veya Google Play geliştirici konsolu üzerinden Google Play’e kopyalanabilir.

adb komut satırı aracı, Android cihazlarıyla etkileşim kurmak için kullanılan, kullanımı kolay ve çok yönlü bir programdır. adb aracını Mac, Linux veya Windows için Android SDK Platform-Tools paketinin bir parçası olarak indirip kurabilirsiniz.

Android SDK Platform-Tools paketini şu adresten indirin: https://developer.android.com/studio/releases/platform-tools. adb aracını /platform-tools/ dizininde bulabilirsiniz. Alternatif olarak, platforma özgü paketler ilgili paket yöneticileri aracılığıyla kurulabilir.

Ubuntu Linux üzerinde:

$ sudo apt-get install android-tools-adb

Fedora 18/19 üzerinde:

$ sudo yum install android-tools

macOS üzerinde (Homebrew)

$ brew cask install android-platform-tools

Android cihazınızı USB aracılığıyla bilgisayarınıza bağlayıp aşağıdaki komutu çalıştırarak adb aracının çalıştığını doğrulayabilirsiniz:

$ adb devices
List of devices attached
31002535c90ef000    device

Cihazınız görünmüyorsa Android cihazında USB debugging seçeneğini etkinleştirdiğinizi doğrulayın. Cihazın Settings bölümünü açın ve Developer options (veya Development) seçeneğini bulun.

$ adb install Defold\ examples.apk
4826 KB/s (18774344 bytes in 3.798s)
  pkg: /data/local/tmp/my_app.apk
Success

Düzenleyiciyi kullanarak APK kurma

Düzenleyicinin Bundle iletişim kutusundaki “Install on connected device” ve “Launch installed app” onay kutularını kullanarak bir .apk dosyasını kurup başlatabilirsiniz:

Bu özelliğin çalışması için ADB kurulu olmalı ve bağlı cihazda USB debugging etkinleştirilmelidir. Düzenleyici ADB komut satırı aracının kurulum konumunu algılayamazsa bunu Preferences içinde belirtmeniz gerekir.

AAB kurma

Bir .aab dosyası Google Play geliştirici konsolu üzerinden Google Play’e yüklenebilir. Android bundletool kullanarak bir .aab dosyasından yerel olarak kurmak üzere bir .apk dosyası oluşturmak da mümkündür.

R8 ile Java kodunu küçültme

R8, küçültme, optimizasyon ve karartma (obfuscation) yoluyla Java kodunun boyutunu azaltır.

R8’i etkinleştirme

game.project dosyasındaki Android ▸ R8 Keep Rules alanında /builtins/manifests/android/dmengine.keep dosyasını seçin. Bu, Defold’un varsayılan kurallarını doğrudan kullanır:

[android]
r8_keep_rules = /builtins/manifests/android/dmengine.keep

Java kodu içeren her eklentinin, çalışma sırasında ihtiyaç duyduğu sınıflar için bir .keep dosyası sağladığından emin olun. Eklenti kuralları, proje derlenirken seçili proje kurallarıyla birleştirilir. R8’i etkinleştirdikten sonra yayıma yönelik bir derlemeyi cihazda test edin.

R8 Keep Rules alanı boş bırakıldığında küçültme işlemi yapılmadan D8 kullanılır. R8 etkinleştirildiğinde, yerel kod eklentileri (native extension) olmayan bir projede bile yerel kod eklentisi derleme hizmeti kullanılır.

Bir eklentiye kurallar ekleme

Bir eklentinin koruma kuralları, eklentinin manifests/android dizininde, build.gradle dosyasının yanında bulunur. Bir dosyanın nasıl ekleneceğini ve eklentinin Java sınıflarının nasıl korunacağını öğrenmek için Android eklentileri için R8 koruma kuralları bölümüne bakın.

Karartma eşlemesini saklama

Derleme bir mapping.txt dosyası oluşturduğunda R8’in bu dosyasını saklamak için Android dağıtım paketi iletişim kutusunda Generate debug symbols seçeneğini etkinleştirin veya Bob’a --with-symbols seçeneğini geçirin. Örneğin, proje dizininden:

java -jar bob.jar --platform arm64-android --variant release \
  --archive --with-symbols --bundle-output build/android \
  resolve build bundle

Eşleme, oluşturulan APK veya AAB dosyasının yanına <binary-name>.apk.symbols/mapping.txt olarak kaydedilir. Örneğin, proje başlığı My Game olduğunda yukarıdaki komut build/android/MyGame/MyGame.apk.symbols/mapping.txt dosyasını oluşturur.

Eşleme dosyasını, oluşturulduğu sürümle birlikte saklayın. Bu dosya, yığın izlerini (stack trace) yorumlamak için karartılmış Java adlarını özgün adlarla eşler; farklı bir derlemeye ait eşleme yanlış sonuçlar verebilir.

İzinler

Defold motoru, tüm motor özelliklerinin çalışabilmesi için çeşitli izinler gerektirir. İzinler, game.project proje ayarları dosyasında belirtilen AndroidManifest.xml dosyasında tanımlanır. Android izinleri hakkında daha fazla bilgiyi resmî belgelerden edinebilirsiniz. Varsayılan bildirimde aşağıdaki izinler istenir:

android.permission.INTERNET ve android.permission.ACCESS_NETWORK_STATE (Koruma düzeyi: normal)

Uygulamaların ağ soketleri açmasına ve ağlar hakkındaki bilgilere erişmesine izin verir. Bu izinler internet erişimi için gereklidir. (Android resmî belgeleri) ve (Android resmî belgeleri).

android.permission.WAKE_LOCK (Koruma düzeyi: normal)

İşlemcinin uyumasını veya ekranın kararmasını önlemek için PowerManager WakeLocks kullanılmasına izin verir. Bu izin, bir anlık bildirim alınırken cihazın uyumasını geçici olarak önlemek için gereklidir. (Android resmî belgeleri)

AndroidX kullanma

AndroidX, artık bakımı yapılmayan özgün Android Support Library’ye kıyasla büyük bir iyileştirmedir. AndroidX paketleri, aynı özellikleri ve yeni kütüphaneleri sağlayarak Support Library’nin yerini tamamen alır. Asset Portal üzerindeki Android eklentilerinin çoğu AndroidX’i destekler. AndroidX kullanmak istemiyorsanız uygulama bildiriminde Use Android Support Lib seçeneğini işaretleyerek AndroidX’i açıkça devre dışı bırakıp eski Android Support Library’yi kullanabilirsiniz.

Sık sorulan sorular

Q: Android’de gezinme ve durum çubuklarını gizlemek mümkün mü?

A: Evet, game.project dosyasının Android bölümündeki immersive_mode ayarını etkinleştirin. Bu, uygulamanızın ekranın tamamını kaplamasını ve ekrandaki tüm dokunma olaylarını yakalamasını sağlar.

Q: Cihaza bir Defold oyunu kurarken neden “Failure [INSTALL_PARSE_FAILED_INCONSISTENT_CERTIFICATES]” hatasını alıyorum?

A: Android, uygulamayı yeni bir sertifikayla kurmaya çalıştığınızı algılar. Hata ayıklama derlemeleri (debug build) paketlenirken her derleme geçici bir sertifikayla imzalanır. Yeni sürümü kurmadan önce eski uygulamayı kaldırın:

$ adb uninstall com.defold.examples
Success
$ adb install Defold\ examples.apk
4826 KB/s (18774344 bytes in 3.798s)
      pkg: /data/local/tmp/Defold examples.apk
Success

Q: Belirli eklentilerle projeyi derlerken neden AndroidManifest.xml dosyasındaki çakışan özelliklerle ilgili hatalar alıyorum?

A: Bu durum, iki veya daha fazla eklentinin (extension) aynı property etiketini farklı değerlerle içeren bir Android bildirim parçası (Android Manifest stub) sağlaması durumunda ortaya çıkabilir. Örneğin Firebase ve AdMob ile bu sorun yaşanmıştır. Derleme hatası şuna benzer:

SEVERE: /tmp/job4531953598647135356/upload/AndroidManifest.xml:32:13-58
Error: Attribute property#android.adservices.AD_SERVICES_CONFIG@resource
value=(@xml/ga_ad_services_config) from AndroidManifest.xml:32:13-58 is also
present at AndroidManifest.xml:92:13-59 value=(@xml/gma_ad_services_config).
Suggestion: add 'tools:replace="android:resource"' to <property> element at
AndroidManifest.xml to override. 

Sorun ve geçici çözümü hakkında daha fazla bilgi için Defold hata bildirimi #9453 ve Google hata bildirimi #327696048 sayfalarını okuyabilirsiniz.