Android-Entwicklung

Auf Android-Geräten kannst du deine eigenen Apps frei ausführen. Es ist sehr einfach, eine Version deines Spiels zu erstellen und auf ein Android-Gerät zu kopieren. Dieses Handbuch erklärt die Schritte zur Bundle-Erstellung deines Spiels für Android. Während der Entwicklung wird häufig die Ausführung deines Spiels über die Entwicklungs-App (development app) bevorzugt, da du damit Inhalte und Code per Hot Reload direkt auf deinem Gerät aktualisieren kannst.

Signieren für Android und Google Play

Android verlangt, dass alle APKs mit einem Zertifikat digital signiert werden, bevor sie auf einem Gerät installiert oder aktualisiert werden. Wenn du Android App Bundles verwendest, musst du nur dein App Bundle signieren, bevor du es in die Play Console hochlädst. Play App Signing übernimmt den Rest. Du kannst deine App aber auch manuell signieren, um sie bei Google Play oder anderen App-Stores hochzuladen oder außerhalb eines Stores zu verteilen.

Wenn du ein Android-Anwendungs-Bundle mit dem Defold-Editor oder dem Befehlszeilenwerkzeug erstellst, kannst du einen Schlüsselspeicher (keystore) mit deinem Zertifikat und Schlüssel sowie das Passwort des Schlüsselspeichers angeben. Diese werden zum Signieren deiner Anwendung verwendet. Wenn du diese Angaben weglässt, erzeugt Defold einen Debug-Schlüsselspeicher und verwendet ihn zum Signieren des Anwendungs-Bundles.

Einen Schlüsselspeicher erstellen

Du kannst einen Schlüsselspeicher mit Android Studio oder über ein Terminal bzw. die Eingabeaufforderung erstellen:

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

Dadurch wird eine Schlüsselspeicherdatei namens mykeystore.keystore erstellt, die einen Schlüssel und ein Zertifikat enthält. Der Zugriff auf Schlüssel und Zertifikat wird durch das Passwort 5Up3r_53cR3t geschützt. Schlüssel und Zertifikat sind 25 Jahre (9125 Tage) gültig. Der erzeugte Schlüssel und das Zertifikat werden durch den Alias myAlias identifiziert.

Ein Android-Anwendungs-Bundle erstellen

Mit dem Editor kannst du einfach ein eigenständiges Anwendungs-Bundle für dein Spiel erstellen. Vor der Bundle-Erstellung kannst du in der Projekteinstellungsdatei game.project festlegen, welche Symbole für die App verwendet werden sollen, den Versionscode einstellen usw.

Wähle zum Erstellen eines Bundles im Menü Project ▸ Bundle... ▸ Android Application....

Wenn der Editor automatisch zufällige Debug-Zertifikate erstellen soll, lasse die Felder Keystore und Keystore password leer:

Wenn du dein Bundle mit einem bestimmten Schlüsselspeicher signieren möchtest, gib Keystore und Keystore password an. Für Keystore wird die Dateierweiterung .keystore erwartet, während das Passwort in einer Textdatei mit der Erweiterung .txt gespeichert sein muss. Du kannst außerdem ein Key password angeben, wenn der Schlüssel im Schlüsselspeicher ein anderes Passwort als der Schlüsselspeicher selbst verwendet:

Defold unterstützt die Erstellung von APK- und AAB-Dateien. Wähle APK oder AAB aus der Auswahlliste Bundle Format.

Klicke auf Create Bundle, sobald du die Einstellungen für das Anwendungs-Bundle konfiguriert hast. Anschließend wirst du aufgefordert, den Speicherort auf deinem Computer anzugeben, an dem das Bundle erstellt werden soll.

Build-Varianten

Wenn du ein Bundle für ein Spiel erstellst, musst du auswählen, welche Art von Engine du verwenden möchtest. Du hast drei grundlegende Optionen:

• Debug
• Release
• Headless

Diese verschiedenen Versionen werden auch als Build-Varianten (Build variants) bezeichnet.

Debug

Diese Art von ausführbarer Datei wird üblicherweise während der Entwicklung eines Spiels verwendet, da sie mehrere nützliche Debugging-Funktionen enthält:

• Profiler - Dient zum Erfassen von Leistungs- und Nutzungszählern. Wie du den Profiler verwendest, erfährst du im Profiling-Handbuch.
• Protokollierung - Die Engine protokolliert Systeminformationen, Warnungen und Fehler, wenn die Protokollierung aktiviert ist. Die Engine gibt außerdem Protokollmeldungen der Lua-Funktion print() sowie von nativen Erweiterungen (native extensions) aus, die mit dmLogInfo(), dmLogError() und ähnlichen Funktionen protokollieren. Wie du diese Protokolle liest, erfährst du im Handbuch zu Spiel- und Systemprotokollen.
• Hot Reload - Hot Reload ist eine leistungsfähige Funktion, mit der du während der Entwicklung Ressourcen (resources) neu laden kannst, während das Spiel läuft. Wie du diese Funktion verwendest, erfährst du im Hot-Reload-Handbuch.
• Engine-Dienste - Du kannst über verschiedene offene TCP-Ports und Dienste eine Verbindung zu einer Debug-Version eines Spiels herstellen und mit ihr interagieren. Zu diesen Diensten gehören die Hot-Reload-Funktion, der Fernzugriff auf Protokolle und der oben erwähnte Profiler, aber auch weitere Dienste zur Ferninteraktion mit der Engine. Mehr über die Engine-Dienste erfährst du in der Entwicklerdokumentation.

Release

Bei dieser Variante sind die Debugging-Funktionen deaktiviert. Du solltest diese Option wählen, wenn das Spiel zur Veröffentlichung im App Store oder zur Weitergabe an Spieler auf anderem Wege bereit ist. Aus mehreren Gründen wird davon abgeraten, ein Spiel mit aktivierten Debugging-Funktionen zu veröffentlichen:

• Die Debugging-Funktionen beanspruchen etwas Platz in der Binärdatei, und es ist bewährte Praxis, die Binärdatei eines veröffentlichten Spiels so klein wie möglich zu halten.
• Die Debugging-Funktionen beanspruchen auch etwas CPU-Zeit. Das kann die Leistung des Spiels beeinträchtigen, wenn ein Nutzer leistungsschwache Hardware verwendet. Auf Mobiltelefonen trägt die erhöhte CPU-Auslastung außerdem zur Erwärmung und zum Akkuverbrauch bei.
• Die Debugging-Funktionen können Informationen über das Spiel offenlegen, die nicht für die Augen der Spieler bestimmt sind, sei es im Hinblick auf Sicherheit, Schummeln oder Betrug.

Headless

Diese ausführbare Datei läuft ohne Grafik und Ton. Das bedeutet, dass du die Unit- und Smoke-Tests des Spiels auf einem CI-Server ausführen oder das Spiel sogar als Spielserver in der Cloud betreiben kannst.

Ein Android-Anwendungs-Bundle installieren

Eine APK installieren

Eine .apk-Datei kann mit dem Werkzeug adb auf dein Gerät oder über die Google Play-Entwicklerkonsole zu Google Play kopiert werden.

Das Kommandozeilenwerkzeug adb ist ein einfach zu bedienendes und vielseitiges Programm, mit dem du mit Android-Geräten interagieren kannst. Du kannst adb als Teil der Android SDK Platform-Tools für Mac, Linux oder Windows herunterladen und installieren.

Lade die Android SDK Platform-Tools hier herunter: https://developer.android.com/studio/releases/platform-tools. Das Werkzeug adb findest du unter /platform-tools/. Alternativ kannst du plattformspezifische Pakete über die jeweiligen Paketmanager installieren.

Unter Ubuntu Linux:

$ sudo apt-get install android-tools-adb

Unter Fedora 18/19:

$ sudo yum install android-tools

Unter macOS (Homebrew)

$ brew cask install android-platform-tools

Du kannst überprüfen, ob adb funktioniert, indem du dein Android-Gerät per USB mit deinem Computer verbindest und den folgenden Befehl ausführst:

$ adb devices
List of devices attached
31002535c90ef000    device

Wenn dein Gerät nicht angezeigt wird, prüfe, ob du USB debugging auf dem Android-Gerät aktiviert hast. Öffne auf dem Gerät Settings und suche nach Developer options (oder Development).

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

Eine APK mit dem Editor installieren

Du kannst eine .apk-Datei mit den Kontrollkästchen „Install on connected device“ und „Launch installed app“ im Bundle-Dialogfeld des Editors installieren und starten:

Für diese Funktion muss ADB installiert und USB debugging auf dem verbundenen Gerät aktiviert sein. Wenn der Editor den Installationsort des ADB-Befehlszeilenwerkzeugs nicht erkennen kann, musst du ihn in Preferences angeben.

Eine AAB installieren

Eine .aab-Datei kann über die Google Play-Entwicklerkonsole zu Google Play hochgeladen werden. Mit dem Android bundletool kannst du außerdem aus einer .aab-Datei eine .apk-Datei erzeugen, um sie lokal zu installieren.

Java-Code mit R8 verkleinern

R8 reduziert die Größe von Java-Code durch Verkleinerung, Optimierung und Verschleierung.

R8 aktivieren

Wähle /builtins/manifests/android/dmengine.keep unter Android ▸ R8 Keep Rules in game.project aus. Dadurch werden die Standardregeln von Defold direkt verwendet:

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

Stelle sicher, dass jede Erweiterung mit Java-Code eine .keep-Datei für die Klassen bereitstellt, die sie zur Laufzeit benötigt. Die Regeln der Erweiterungen werden beim Build mit den ausgewählten Projektregeln kombiniert. Teste nach dem Aktivieren von R8 einen Release-Build auf einem Gerät.

Wenn du R8 Keep Rules leer lässt, wird D8 ohne Verkleinerung verwendet. Beim Aktivieren von R8 wird der Build-Dienst für native Erweiterungen verwendet, auch für ein Projekt ohne native Erweiterungen.

Regeln zu einer Erweiterung hinzufügen

Die Keep-Regeln einer Erweiterung gehören in ihr Verzeichnis manifests/android, neben build.gradle. Unter R8-Keep-Regeln für Android-Erweiterungen erfährst du, wie du eine Datei hinzufügst und die Java-Klassen der Erweiterung erhältst.

Die Zuordnung verschleierter Namen aufbewahren

Aktiviere Generate debug symbols im Android-Bundle-Dialogfeld oder übergib --with-symbols an Bob, um die Datei mapping.txt von R8 aufzubewahren, wenn der Build eine erzeugt. Beispielsweise aus dem Projektverzeichnis:

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

Die Zuordnung wird als <binary-name>.apk.symbols/mapping.txt neben der erzeugten APK oder AAB gespeichert. Bei dem Projekttitel My Game erzeugt der obige Befehl beispielsweise build/android/MyGame/MyGame.apk.symbols/mapping.txt.

Bewahre die Zuordnungsdatei zusammen mit genau der Release-Version auf, aus der sie stammt. Sie ordnet verschleierten Java-Namen wieder ihre ursprünglichen Namen zu, um Stacktraces auswerten zu können. Eine Zuordnung aus einem anderen Build kann falsche Ergebnisse liefern.

Berechtigungen

Die Defold-Engine benötigt verschiedene Berechtigungen, damit alle Engine-Funktionen arbeiten können. Die Berechtigungen werden in der Datei AndroidManifest.xml definiert, die in der Projekteinstellungsdatei game.project angegeben ist. Weitere Informationen zu Android-Berechtigungen findest du in der offiziellen Dokumentation. Im Standardmanifest werden die folgenden Berechtigungen angefordert:

android.permission.INTERNET und android.permission.ACCESS_NETWORK_STATE (Schutzstufe: normal)

Erlaubt Anwendungen, Netzwerk-Sockets zu öffnen und auf Informationen über Netzwerke zuzugreifen. Diese Berechtigungen werden für den Internetzugriff benötigt. (Offizielle Android-Dokumentation) und (Offizielle Android-Dokumentation).

android.permission.WAKE_LOCK (Schutzstufe: normal)

Erlaubt die Verwendung von PowerManager-WakeLocks, um zu verhindern, dass der Prozessor in den Ruhezustand wechselt oder der Bildschirm gedimmt wird. Diese Berechtigung wird benötigt, um das Gerät beim Empfang einer Push-Benachrichtigung vorübergehend am Wechsel in den Ruhezustand zu hindern. (Offizielle Android-Dokumentation)

AndroidX verwenden

AndroidX ist eine wesentliche Verbesserung gegenüber der ursprünglichen Android Support Library, die nicht mehr gepflegt wird. AndroidX-Pakete ersetzen die Support Library vollständig, indem sie denselben Funktionsumfang und neue Bibliotheken bereitstellen. Die meisten Android-Erweiterungen im Asset Portal unterstützen AndroidX. Wenn du AndroidX nicht verwenden möchtest, kannst du es ausdrücklich zugunsten der alten Android Support Library deaktivieren, indem du Use Android Support Lib im Anwendungsmanifest aktivierst.

FAQ

Q: Kann ich die Navigations- und Statusleiste unter Android ausblenden?

A: Ja, aktiviere die Einstellung immersive_mode im Abschnitt Android deiner Datei game.project. Dadurch kann deine App den gesamten Bildschirm nutzen und alle Ereignisse für Berührungseingaben auf dem Bildschirm erfassen.

Q: Warum erhalte ich „Failure [INSTALL_PARSE_FAILED_INCONSISTENT_CERTIFICATES]“, wenn ich ein Defold-Spiel auf einem Gerät installiere?

A: Android erkennt, dass du versuchst, die App mit einem neuen Zertifikat zu installieren. Wenn du Bundles für Debug-Builds erstellst, wird jeder Build mit einem temporären Zertifikat signiert. Deinstalliere die alte App, bevor du die neue Version installierst:

$ 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: Warum erhalte ich beim Erstellen eines Builds mit bestimmten Erweiterungen Fehlermeldungen zu widersprüchlichen Eigenschaften in AndroidManifest.xml?

A: Das kann passieren, wenn zwei oder mehr Erweiterungen jeweils einen Stub eines Android-Manifests bereitstellen, der dasselbe property-Tag mit unterschiedlichen Werten enthält. Das ist beispielsweise bei Firebase und AdMob aufgetreten. Der Build-Fehler sieht etwa so aus:

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. 

Mehr über das Problem und die Übergangslösung erfährst du im gemeldeten Defold-Issue #9453 und im Google-Issue #327696048.