Sviluppo per Android

I dispositivi Android consentono di eseguire liberamente le proprie applicazioni. È molto semplice creare una build del gioco e copiarla su un dispositivo Android. Questo manuale illustra i passaggi necessari per creare un bundle del gioco per Android. Durante lo sviluppo, spesso è preferibile eseguire il gioco tramite l’applicazione di sviluppo, poiché consente di ricaricare a caldo contenuti e codice direttamente sul dispositivo.

Processo di firma per Android e Google Play

Android richiede che tutti gli APK siano firmati digitalmente con un certificato prima di essere installati su un dispositivo o aggiornati. Se utilizzi gli Android App Bundle, devi firmare solo il bundle dell’applicazione prima di caricarlo nella Play Console; Play App Signing si occupa del resto. Puoi comunque firmare manualmente l’applicazione per caricarla su Google Play, su altri store di applicazioni o per distribuirla al di fuori di qualsiasi store.

Quando crei un bundle di un’applicazione Android dall’editor Defold o dallo strumento a riga di comando, puoi fornire un keystore (contenente il certificato e la chiave) e la relativa password, che verranno utilizzati per firmare l’applicazione. Se non li fornisci, Defold genera un keystore di debug e lo utilizza per firmare il bundle dell’applicazione.

Creazione di un keystore

Puoi creare un keystore utilizzando Android Studio oppure da un terminale/prompt dei comandi:

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

Questo comando crea un file keystore chiamato mykeystore.keystore, contenente una chiave e un certificato. L’accesso alla chiave e al certificato sarà protetto dalla password 5Up3r_53cR3t. La chiave e il certificato saranno validi per 25 anni (9125 giorni). La chiave e il certificato generati saranno identificati dall’alias myAlias.

Creazione di un bundle di un’applicazione Android

L’editor consente di creare facilmente un bundle autonomo del gioco. Prima di creare il bundle, puoi specificare le icone da utilizzare per l’applicazione, impostare il codice di versione e altri parametri nel file delle impostazioni del progetto game.project.

Per creare il bundle, seleziona Project ▸ Bundle... ▸ Android Application... dal menu.

Se vuoi che l’editor crei automaticamente certificati di debug casuali, lascia vuoti i campi Keystore e Keystore password:

Se vuoi firmare il bundle con un keystore specifico, indica Keystore e Keystore password. Il file Keystore deve avere l’estensione .keystore, mentre la password deve essere salvata in un file di testo con estensione .txt. Puoi anche specificare una Key password se la chiave nel keystore utilizza una password diversa da quella del keystore stesso:

Defold supporta la creazione di file APK e AAB. Seleziona APK o AAB dal menu a discesa Bundle Format.

Premi Create Bundle dopo aver configurato le impostazioni del bundle dell’applicazione. Ti verrà quindi chiesto di specificare dove creare il bundle sul computer.

Varianti di build

Quando crei il bundle di un gioco, devi scegliere quale tipo di motore usare. Hai tre opzioni di base:

• Debug
• Release
• Headless

Queste diverse versioni sono anche indicate come Build variants

Debug

Questo tipo di eseguibile viene generalmente usato durante lo sviluppo di un gioco perché include diverse funzionalità utili per il debug:

• Profilatore - Serve a raccogliere contatori delle prestazioni e dell’utilizzo. Scopri come usare il profilatore nel manuale sulla profilazione.
• Registrazione dei log - Quando la registrazione dei log è abilitata, il motore registra informazioni sul sistema, avvisi ed errori. Il motore produce anche i log generati dalla funzione Lua print() e dalle estensioni native che usano dmLogInfo(), dmLogError() e così via. Scopri come leggere questi log nel manuale sui log del gioco e del sistema.
• Hot reload - L’hot reload è una potente funzionalità che permette a uno sviluppatore di ricaricare le risorse mentre il gioco è in esecuzione. Scopri come usarla nel manuale sull’hot reload.
• Servizi del motore - Puoi connetterti a una versione di debug di un gioco e interagire con essa attraverso diverse porte TCP aperte e vari servizi. Questi servizi comprendono la funzionalità di hot reload, l’accesso remoto ai log e il profilatore menzionati sopra, oltre ad altri servizi per interagire a distanza con il motore. Scopri di più sui servizi del motore nella documentazione per gli sviluppatori.

Release

In questa variante le funzionalità di debug sono disabilitate. Scegli questa opzione quando il gioco è pronto per essere pubblicato in uno store di applicazioni o distribuito ai giocatori in altri modi. È sconsigliato pubblicare un gioco con le funzionalità di debug abilitate per diversi motivi:

• Le funzionalità di debug occupano un po’ di spazio nel file binario e è buona pratica cercare di mantenere il più possibile ridotte le dimensioni del file binario di un gioco pubblicato.
• Le funzionalità di debug richiedono anche un po’ di tempo della CPU. Questo può influire sulle prestazioni del gioco se un utente dispone di hardware di fascia bassa. Sui telefoni cellulari, il maggiore utilizzo della CPU contribuisce anche al riscaldamento e al consumo della batteria.
• Le funzionalità di debug possono rivelare informazioni sul gioco che non dovrebbero essere accessibili ai giocatori, per ragioni legate alla sicurezza o alla prevenzione di trucchi e frodi.

Headless

Questo eseguibile funziona senza grafica né audio. Ciò significa che puoi eseguire i test unitari e gli smoke test del gioco su un server di integrazione continua (CI), o persino usarlo come server di gioco nel cloud.

Installazione di un bundle di un’applicazione Android

Installazione di un APK

Un file .apk può essere copiato sul dispositivo con lo strumento adb, oppure caricato su Google Play tramite la console per sviluppatori di Google Play.

Lo strumento a riga di comando adb è un programma versatile e facile da usare che permette di interagire con i dispositivi Android. Puoi scaricare e installare adb come parte di Android SDK Platform-Tools, per Mac, Linux o Windows.

Scarica Android SDK Platform-Tools da: https://developer.android.com/studio/releases/platform-tools. Trovi lo strumento adb in /platform-tools/. In alternativa, puoi installare i pacchetti specifici per la tua piattaforma tramite i rispettivi gestori di pacchetti.

Su Ubuntu Linux:

$ sudo apt-get install android-tools-adb

Su Fedora 18/19:

$ sudo yum install android-tools

Su macOS (Homebrew)

$ brew cask install android-platform-tools

Puoi verificare che adb funzioni collegando il dispositivo Android al computer tramite USB ed eseguendo il seguente comando:

$ adb devices
List of devices attached
31002535c90ef000    device

Se il dispositivo non compare, verifica di aver abilitato USB debugging sul dispositivo Android. Apri Settings sul dispositivo e cerca Developer options (o Development).

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

Installazione di un APK dall’editor

Puoi installare e avviare un file .apk utilizzando le caselle di controllo “Install on connected device” e “Launch installed app” dell’editor nella finestra di dialogo Bundle:

Per utilizzare questa funzionalità, devi avere ADB installato e USB debugging abilitato sul dispositivo collegato. Se l’editor non riesce a rilevare il percorso di installazione dello strumento a riga di comando ADB, devi specificarlo in Preferences.

Installazione di un AAB

Un file .aab può essere caricato su Google Play tramite la console per sviluppatori di Google Play. Puoi anche generare un file .apk da un file .aab per installarlo localmente utilizzando Android bundletool.

Autorizzazioni

Il motore Defold richiede diverse autorizzazioni affinché tutte le sue funzionalità possano operare. Le autorizzazioni sono definite in AndroidManifest.xml, specificato nel file delle impostazioni del progetto game.project. Puoi approfondire le autorizzazioni Android nella documentazione ufficiale. Il manifest predefinito richiede le seguenti autorizzazioni:

android.permission.INTERNET e android.permission.ACCESS_NETWORK_STATE (Livello di protezione: normal)

Consente alle applicazioni di aprire socket di rete e di accedere alle informazioni sulle reti. Queste autorizzazioni sono necessarie per l’accesso a Internet. (Documentazione ufficiale di Android) e (Documentazione ufficiale di Android).

android.permission.WAKE_LOCK (Livello di protezione: normal)

Consente di utilizzare i WakeLock di PowerManager per impedire la sospensione del processore o l’oscuramento dello schermo. Questa autorizzazione è necessaria per impedire temporaneamente al dispositivo di entrare in sospensione durante la ricezione di una notifica push. (Documentazione ufficiale di Android)

Utilizzo di AndroidX

AndroidX rappresenta un importante miglioramento rispetto alla libreria Android Support Library originale, che non è più mantenuta. I pacchetti AndroidX sostituiscono completamente la Support Library, offrendo le stesse funzionalità e nuove librerie. La maggior parte delle estensioni Android nell’Asset Portal supporta AndroidX. Se non vuoi utilizzare AndroidX, puoi disabilitarlo esplicitamente a favore della vecchia Android Support Library selezionando Use Android Support Lib nel manifest dell’applicazione.

FAQ

D: È possibile nascondere la barra di navigazione e la barra di stato su Android?

R: Sì, attiva l’impostazione immersive_mode nella sezione Android del file game.project. In questo modo l’app può occupare l’intero schermo e acquisire tutti gli eventi di tocco sullo schermo.

D: Perché compare “Failure [INSTALL_PARSE_FAILED_INCONSISTENT_CERTIFICATES]” quando installo un gioco Defold su un dispositivo?

R: Android rileva che stai tentando di installare l’app con un nuovo certificato. Quando crei bundle di build di debug, ogni build viene firmata con un certificato temporaneo. Disinstalla la vecchia app prima di installare la nuova versione:

$ 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

D: Perché si verificano errori relativi a proprietà in conflitto in AndroidManifest.xml quando creo una build con alcune estensioni?

R: Questo può accadere quando due o più estensioni forniscono un frammento di Android Manifest che contiene lo stesso tag di proprietà ma con valori diversi. È successo, ad esempio, con Firebase e AdMob. L’errore di build è simile al seguente:

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. 

Puoi trovare maggiori dettagli sul problema e sulla soluzione temporanea nella segnalazione Defold #9453 e nella segnalazione Google #327696048.