Développement pour Android

Les appareils Android vous permettent d’y exécuter librement vos propres applications. Il est très facile de créer un build de votre jeu et de le copier sur un appareil Android. Ce manuel explique les étapes nécessaires à la création d’un bundle de votre jeu pour Android. Pendant le développement, il est souvent préférable d’exécuter votre jeu avec l’application de développement, car elle vous permet de recharger à chaud le contenu et le code directement sur votre appareil.

Processus de signature pour Android et Google Play

Android exige que tous les APK soient signés numériquement avec un certificat avant leur installation ou leur mise à jour sur un appareil. Si vous utilisez des Android App Bundles, vous devez uniquement signer votre bundle d’application avant de l’importer dans la Play Console, puis Play App Signing s’occupe du reste. Vous pouvez aussi signer manuellement votre application pour l’importer sur Google Play ou d’autres boutiques d’applications, ou pour la distribuer en dehors de toute boutique.

Lorsque vous créez un bundle d’application Android depuis l’éditeur Defold ou l’outil en ligne de commande, vous pouvez fournir un magasin de clés (keystore), contenant votre certificat et votre clé, ainsi que son mot de passe, qui serviront à signer votre application. Si vous ne le faites pas, Defold génère un magasin de clés de débogage et l’utilise pour signer le bundle d’application.

Création d’un magasin de clés

Vous pouvez créer un magasin de clés avec Android Studio ou depuis un terminal ou une invite de commandes :

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

Cette commande crée un fichier de magasin de clés nommé mykeystore.keystore, contenant une clé et un certificat. L’accès à la clé et au certificat est protégé par le mot de passe 5Up3r_53cR3t. La clé et le certificat sont valables pendant 25 ans (9125 jours). La clé et le certificat générés sont identifiés par l’alias myAlias.

Création d’un bundle d’application Android

L’éditeur vous permet de créer facilement un bundle d’application autonome pour votre jeu. Avant de créer le bundle, vous pouvez préciser les icônes à utiliser pour l’application, définir le code de version, etc. dans le fichier de paramètres du projet game.project.

Pour créer un bundle, sélectionnez Project ▸ Bundle... ▸ Android Application... dans le menu.

Si vous souhaitez que l’éditeur crée automatiquement des certificats de débogage aléatoires, laissez les champs Keystore et Keystore password vides :

Si vous souhaitez signer votre bundle avec un magasin de clés particulier, renseignez les champs Keystore et Keystore password. Le fichier Keystore doit avoir l’extension .keystore, tandis que le mot de passe doit être enregistré dans un fichier texte portant l’extension .txt. Vous pouvez aussi renseigner le champ Key password si la clé du magasin de clés utilise un mot de passe différent de celui du magasin lui-même :

Defold permet de créer des fichiers APK et AAB. Sélectionnez APK ou AAB dans la liste déroulante Bundle Format.

Cliquez sur Create Bundle lorsque vous avez configuré les paramètres du bundle d’application. Vous devrez ensuite préciser à quel emplacement de votre ordinateur le bundle sera créé.

Variantes de build

Lorsque vous créez un bundle de jeu, vous devez choisir le type de moteur que vous souhaitez utiliser. Vous disposez de trois options de base :

• Debug
• Release
• Headless

Ces différentes versions sont également appelées Build variants

Debug

Ce type d’exécutable est généralement utilisé pendant le développement d’un jeu, car il intègre plusieurs fonctionnalités de débogage utiles :

• Profileur - Sert à recueillir des compteurs de performances et d’utilisation. Découvrez comment utiliser le profileur dans le manuel de profilage.
• Journalisation - Le moteur consigne les informations système, les avertissements et les erreurs lorsque la journalisation est activée. Le moteur affiche également les journaux issus de la fonction Lua print() et des extensions natives qui utilisent dmLogInfo(), dmLogError(), etc. Découvrez comment lire ces journaux dans le manuel des journaux du jeu et du système.
• Rechargement à chaud - Le rechargement à chaud est une fonctionnalité puissante qui permet à un développeur de recharger une ressource pendant l’exécution du jeu. Découvrez comment l’utiliser dans le manuel du rechargement à chaud.
• Services du moteur - Il est possible de se connecter à une version Debug d’un jeu et d’interagir avec elle via différents ports TCP ouverts et services. Ces services comprennent le rechargement à chaud, l’accès à distance aux journaux et le profileur mentionnés ci-dessus, mais aussi d’autres services permettant d’interagir à distance avec le moteur. Pour en savoir plus sur les services du moteur, consultez la documentation pour les développeurs.

Release

Les fonctionnalités de débogage sont désactivées dans cette variante. Vous devriez choisir cette option lorsque le jeu est prêt à être publié dans un magasin d’applications ou partagé avec les joueurs d’une autre manière. Il est déconseillé de publier un jeu avec les fonctionnalités de débogage activées pour plusieurs raisons :

• Les fonctionnalités de débogage occupent un peu de place dans le binaire, et une bonne pratique consiste à garder le binaire d’un jeu publié aussi petit que possible.
• Les fonctionnalités de débogage consomment également un peu de temps processeur. Cela peut nuire aux performances du jeu si l’utilisateur dispose de matériel peu puissant. Sur les téléphones mobiles, l’utilisation accrue du processeur contribue aussi à l’échauffement et à la décharge de la batterie.
• Les fonctionnalités de débogage peuvent exposer des informations sur le jeu qui ne sont pas destinées aux joueurs, pour des raisons de sécurité, de triche ou de fraude.

Headless

Cet exécutable fonctionne sans interface graphique ni son. Cela signifie que vous pouvez exécuter les tests unitaires ou de bon fonctionnement du jeu sur un serveur d’intégration continue (CI), ou même l’utiliser comme serveur de jeu dans le cloud.

Installation d’un bundle d’application Android

Installation d’un APK

Vous pouvez copier un fichier .apk sur votre appareil avec l’outil adb, ou sur Google Play via la console développeur Google Play.

L’outil en ligne de commande adb est un programme polyvalent et facile à utiliser qui permet d’interagir avec les appareils Android. Vous pouvez télécharger et installer adb avec les Android SDK Platform-Tools, pour Mac, Linux ou Windows.

Téléchargez les Android SDK Platform-Tools à l’adresse suivante : https://developer.android.com/studio/releases/platform-tools. Vous trouverez l’outil adb dans /platform-tools/. Vous pouvez également installer des paquets propres à chaque plateforme à l’aide de leurs gestionnaires de paquets respectifs.

Sur Ubuntu Linux :

$ sudo apt-get install android-tools-adb

Sur Fedora 18/19 :

$ sudo yum install android-tools

Sur macOS (Homebrew)

$ brew cask install android-platform-tools

Vous pouvez vérifier que adb fonctionne en connectant votre appareil Android à votre ordinateur par USB et en exécutant la commande suivante :

$ adb devices
List of devices attached
31002535c90ef000    device

Si votre appareil n’apparaît pas, vérifiez que vous avez activé USB debugging sur l’appareil Android. Ouvrez les Settings de l’appareil et recherchez Developer options (ou Development).

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

Installation d’un APK avec l’éditeur

Vous pouvez installer et lancer un fichier .apk à l’aide des cases à cocher « Install on connected device » et « Launch installed app » de l’éditeur, dans la boîte de dialogue Bundle :

Pour que cette fonctionnalité fonctionne, ADB doit être installé et USB debugging doit être activé sur l’appareil connecté. Si l’éditeur ne parvient pas à détecter l’emplacement d’installation de l’outil en ligne de commande ADB, vous devez le préciser dans les Preferences.

Installation d’un AAB

Vous pouvez importer un fichier .aab sur Google Play via la console développeur Google Play. Vous pouvez aussi générer un fichier .apk à partir d’un fichier .aab pour l’installer localement avec Android bundletool.

Autorisations

Le moteur Defold nécessite plusieurs autorisations pour que toutes ses fonctionnalités puissent fonctionner. Les autorisations sont définies dans le fichier AndroidManifest.xml, indiqué dans le fichier de paramètres du projet game.project. Vous trouverez plus d’informations sur les autorisations Android dans la documentation officielle. Les autorisations suivantes sont demandées dans le manifeste par défaut :

android.permission.INTERNET et android.permission.ACCESS_NETWORK_STATE (niveau de protection : normal)

Permettent aux applications d’ouvrir des sockets réseau et d’accéder aux informations sur les réseaux. Ces autorisations sont nécessaires pour accéder à Internet. (Documentation officielle Android) et (Documentation officielle Android).

android.permission.WAKE_LOCK (niveau de protection : normal)

Permet d’utiliser les WakeLocks de PowerManager pour empêcher la mise en veille du processeur ou la réduction de la luminosité de l’écran. Cette autorisation est nécessaire pour empêcher temporairement l’appareil de se mettre en veille pendant la réception d’une notification push. (Documentation officielle Android)

Utilisation d’AndroidX

AndroidX est une amélioration majeure de la bibliothèque Android Support Library d’origine, qui n’est plus maintenue. Les paquets AndroidX remplacent entièrement la Support Library en offrant les mêmes fonctionnalités et de nouvelles bibliothèques. La plupart des extensions Android de l’Asset Portal prennent en charge AndroidX. Si vous ne souhaitez pas utiliser AndroidX, vous pouvez le désactiver explicitement au profit de l’ancienne Android Support Library en cochant Use Android Support Lib dans le manifeste de l’application.

Questions fréquentes

Q : Est-il possible de masquer les barres de navigation et d’état sur Android ?

R : Oui, activez le paramètre immersive_mode dans la section Android de votre fichier game.project. Cela permet à votre application d’occuper tout l’écran et de capturer tous les événements tactiles à l’écran.

Q : Pourquoi le message « Failure [INSTALL_PARSE_FAILED_INCONSISTENT_CERTIFICATES] » s’affiche-t-il lorsque j’installe un jeu Defold sur un appareil ?

R : Android détecte que vous essayez d’installer l’application avec un nouveau certificat. Lors de la création de bundles de builds de débogage, chaque build est signé avec un certificat temporaire. Désinstallez l’ancienne application avant d’installer la nouvelle 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 : Pourquoi est-ce que j’obtiens des erreurs concernant des propriétés en conflit dans AndroidManifest.xml lorsque je crée un build avec certaines extensions ?

R : Cela peut se produire lorsque deux extensions ou plus fournissent un fragment de manifeste Android contenant la même balise de propriété, mais avec des valeurs différentes. Cela s’est notamment produit avec Firebase et AdMob. L’erreur de build ressemble à ceci :

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. 

Vous trouverez plus d’informations sur ce problème et sa solution de contournement dans le ticket Defold #9453 et le ticket Google #327696048.