Read this manual in English

Android development

Urządzenia z systemem Android pozwalają na swobodne otwieranie Twoich własnych aplikacji i gier. Jest bardzo łatwo zbudować wersję gry i skopiować ją na takie urządzenie. Instrukcja ta opisuje kroki procesu pakowania aplikacji na system Android. Podczas tworzenia oprogramowania z Defoldem, otwieranie i testowanie Twojej gry poprzez specjalną aplikacją zwaną development app jest często preferowane, ponieważ umożliwia szybkie przeładowanie zawartości nawet podczas działania programu i programowanie urządzenia bezprzewodowo.

Proces podpisywania Android i Google Play

Android wyamaga, aby aplikacje, które chcesz zainstalować na urządzeniu były cyfrowo podpisane. W przeciwieństwie do iOS, gdzie wszystkie certyfikaty są przyznawane przez Apple, Android umożliwia własnoręczne podpisanie aplikacji, więc można swobodnie tworzyć certyfikaty i klucze wymagane do podpisywania.

Proces tworzenia certyfikatów i kluczy może wyglądać na skomplikowany, ale podczas tworzenia oprogramowania Defold go automatyzuje. Kiedy tworzysz aplikację i pakujesz ją do paczki (ang. Android application bundle) możesz podać specyficzny certyfikat i klucz. Jeśli tego nie zrobisz, Defold wygeneruje je za Ciebie i podpisze aplikację automatycznie.

Ważne, aby zaapamiętać, że przy releasowaniu aplikacji na Google Play, będziesz musiał stworzyć certyfikat i klucz, którymi właśnie podpiszesz tę aplikację. Powodem tego jest to, że podczas publikowania zaktualizowanej wersji aplikacji użyć musisz tego samego podpisu jak dotychczasowa wersja. Jeśli podpiszesz aplikację innym kluczem, Google Play odrzuci aktualizację i będziesz musiał opublikować aplikację jako osobna, nowa aplikacja.

Możesz przeczytać więcej na ten temat na stronie Google Play developer console.

Tworzenie certyfikatów i kluczy

Musisz stworzyć certyfikaty w formacie .pem, a klucze w formacie .pk8. Możesz je wygenerować korzystając z narzędzia openssl:

$ openssl genrsa -out key.pem 2048
$ openssl req -new -key key.pem -out request.pem
$ openssl x509 -req -days 9999 -in request.pem -signkey key.pem -out certificate.pem
$ openssl pkcs8 -topk8 -outform DER -in key.pem -inform PEM -out key.pk8 -nocrypt

Uzyskasz dzięki temu pliki certificate.pem i key.pk8, które użyjesz do podpisania aplikacji.

Tworzenie paczki - Android application bundle

Edytor Defold umożliwia łatwe stworzenie paczki z aplikacją. Przed pakowaniem określasz, których ikon należy używać, wersję produktu itd. w pliku game.project. Więcej tutaj: plik konfiguracyjny projektu.

Aby stworzyć paczkę kliknij Project ▸ Bundle... ▸ Android Application... w menu.

Jeśli chcesz, aby Defold automatycznie stworzył certyfikat, zostaw pola Certificate i Private key puste:

Jeśli chcesz podpisać paczkę własnym certyfikatem i kluczem, wskaż odpowiednie pliki .pem i .pk8:

Defold wspiera tworzenie zarówno paczek APK i AAB. Wybierz APK lub AAB z rozwijanej listy “Bundle Format”.

Kliknij Create Bundle po skonfigurowaniu wszystkich ustawień. Będziesz poproszony o wskazanie lokalizacji na Twoim urządzeniu do zapisania zbudowanej paczki.

Build variants

When you bundle a game, you need to choose what type of engine you wish to use. You have three basic options:

• Debug
• Release
• Headless

These different versions are also referred to as Build variants

Debug

This type of executable is typically used during development of a game as it has several useful debugging features included:

• Profiler - Used for gathering performance and usage counters. Learn how to use the profiler in the Profiling manual.
• Logging - The engine will log system information, warnings and errors when logging is enabled. The engine will also output logs from the Lua print() function and from native extensions logging using dmLogInfo(), dmLogError() and so on. Learn how to read these logs in the Game and System Logs manual.
• Hot reload - Hot-reload is a powerful feature which lets a developer reload resource while the game is running. Learn how to use this in the Hot-Reload manual.
• Engine services - It is possible to connect to and interact with a debug version of a game through a number of different open TCP ports and services. The services include the hot-reload feature, remote log access and the profiler mentioned above, but also other services to remotely interact with the engine. Learn more about the engine services in the developer documentation.

Release

This variant has the debugging features disabled. This options should be chosen when the game is ready to be released to the app store or in other ways shared with players. It is not recommended to release a game with the debugging features enabled for a number of reasons:

• The debugging features take up a little bit of size in the binary, and it is a best practice to try to keep the binary size of a released game as small as possible.
• The debugging features takes a little bit of CPU time as well. This can impact the performance of the game if a user has a low-end hardware. On mobile phones the increased CPU usage will also contribute to heating and battery drain.
• The debugging features may expose information about the game that is not intended for the eyes of the players, either from a security, cheating or fraud perspective.

Headless

This executable runs without any graphics and sound. It means that you can run the game unit/smoke tests on a CI server, or even have it as a game server in the cloud.

Instalowanie paczek na Androidzie

Instalowanie APK

Plik .apk może być skopiowany na Twoje urządzenie z systemem Android przy użyciu narzędzia adb (zobacz poniżej) lub załadowane do Google Play poprzez Google Play developer console.

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

Instalowanie AAB

Plik .aab może być załadowany do Google Play poprzez Google Play developer console. Jest również możliwe wygenerowanie pliku .apk z pliku .aab, aby zainstalować je lokalnie dzięki Android bundletool.

Pozwolenia

Silnik Defold wymaga niektórych pozwoleń, aby wszystkie jego elementy mogły działać. Pozwolenia są zdefiniowane w pliku AndroidManifest.xml, wybranym w pliku game.project: plik konfiguracyjny projektu. Możesz dowiedzieć się więcej na temat pozwoleń w systemie Android w oficjalnej dokumenetacji. Następujące pozwolenia są wymagane przy użyciu domyślnego pliku manifest:

android.permission.INTERNET i android.permission.ACCESS_NETWORK_STATE (Protection level: normal)

Pozwala aplikacji na otwieranie połączeń internetowych i uzyskiwaniu informacji na temat sieci. Potrzebne są przy dostępie do Internetu. (Android official docs) i (Android official docs).

android.permission.WRITE_EXTERNAL_STORAGE (Protection level: dangerous)

Pozwala aplikacji na zapisywanie do pamięci zewnętrznej. Od poziomu 19 API to pozwolenie nie jest wymagane do zapisu i odczytu plików w lokalizacji przeznaczonej dla Twojej aplikacji (otrzymanej przez Context.getExternalFilesDir(String) i Context.getExternalCacheDir()). To pozwolenie jest wymagane, gdy chcesz zapisywać do lub odczytywać dane z plików z dysku (używając metod z io.* lub sys.save/load) poza lokalizacją wskazaną przez sys.get_save_file() i mając android:minSdkVersion ustawione na mniejsze niż 19 w pliku manifest. (Android official docs).

android.permission.WAKE_LOCK (Protection level: normal)

Pozwala na użwanie PowerManagera, aby powstrzymać procesor przed przyciemnianiem ekranu lub wygaszaniem. Potrzebne jest do tego, by tymczasowo powstrzymać urządzenie przed uśpieniem podczas otrzymywania powiadomień. (Android official docs)

Narzędzie adb - Android Debug Bridge

Narzędzie adb jest łatwym i wszechstronnym programem do interakcji z urządzeniami z systemem Android. Możesz ściągnąć je i zainstalować jako część Android SDK Platform-Tools, dla systemów Mac, Linux czy Windows.

Ściągnij Android SDK Platform-Tools z: https://developer.android.com/studio/releases/platform-tools. Znajdziesz narzędzie adb w /platform-tools/. Alternatywnie, paczki dla konkretnych platform mogą zostać zainstalowane przez odpowiednie managery paczek.

Na Ubuntu Linux:

$ sudo apt-get install android-tools-adb

Na Fedora 18/19:

$ sudo yum install android-tools

Na macOS (Homebrew)

$ brew cask install android-platform-tools

Możesz sprawdzić czy adb działa łącząc Twoje urządzenie z systemem Android do Twojego komputera przez USB i użyć komendy:

$ adb devices
List of devices attached
31002535c90ef000    device

Jeśli Twoje urządzenie się nie pojawi, upewnij się najpierw czy zezwolono na USB debugging na urządzeniu mobilnym. Otwórz ustawienia Settings i wyszukaj Developer options (lub Development).

Debugowanie paczki z aplikacją

Paczka zbudowana w trybie Debug silnika (czyli z opcją “Debug” zaznaczoną podczas budowania paczki) będzie wysyłać wszystkie swoje logi do systemu Android. Uzyskaj dostęp do tych logów przez narzędzie adb używając komendylogcat. Prawdopodobnie też będziesz chcieć przefiltrować wynik używając tagu (-s [tagname]):

$ adb logcat -s "defold"
--------- beginning of /dev/log/system
--------- beginning of /dev/log/main
I/defold  ( 6210): INFO:DLIB: SSDP started (ssdp://192.168.0.97:58089, http://0.0.0.0:38637)
I/defold  ( 6210): INFO:ENGINE: Defold Engine 1.2.50 (8d1b912)
I/defold  ( 6210): INFO:ENGINE: Loading data from:
I/defold  ( 6210): INFO:ENGINE: Initialised sound device 'default'
I/defold  ( 6210):
D/defold  ( 6210): DEBUG:SCRIPT: Hello there, log!
...

FAQ

Q: Is it possible to hide the navigation and status bars on Android?

A: Yes, set the immersive_mode setting in the Android section of your game.project file. This lets your app take over the whole screen and capture all touch events on the screen.

Q: Why am I’m getting “Failure [INSTALL_PARSE_FAILED_INCONSISTENT_CERTIFICATES]” when installing a Defold game on device?

A: Android detects that you try to install the app with a new certificate. When bundling debug builds, each build will be signed with a temporary certificate. Uninstall the old app before installing the new version:

$ 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: Why am I getting errors about conflicting properties in AndroidManifest.xml when building with certain extensions?

A: This can happen when two or more extensions provide an Android Manifest stub containing the same property tag but with different values. This has for instance happened with Firebase and AdMob. The build error looks similar to this:

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. 

You can read more about the issue and the workaround in reported Defold issue #9453 and Google issue #327696048.