Debug del processo di build, installazione ed esecuzione del gioco

Introduzione

Di seguito è riportata una guida per il debug della procedura di compilazione e di build per i giochi Unity che utilizzano l'SDK Firebase per Unity. Descrive come esaminare e risolvere molti dei problemi più comuni che potresti riscontrare durante la configurazione e la compilazione del tuo gioco per una nuova piattaforma o dopo un aggiornamento. Sono disposti in ordine di quando questi errori possono verificarsi nel processo. Consultali nell'ordine e procedi man mano che risolvi ogni problema.

Oltre a questo documento, consulta le domande frequenti su Firebase per Unity per ulteriori informazioni.

Problemi di compilazione della modalità di riproduzione

La prima classe di problemi di compilazione può verificarsi durante il test nell'editor prima di provare ad avviare una compilazione mobile. Questa sezione riguarda tutti gli errori Firebase che si verificano prima e durante la modalità di riproduzione.

Quando Unity si avvia o rileva modifiche a dipendenze, codice o altri asset, tenta di ricostruire il progetto. Se il progetto non riesce a compilarsi in quel momento, l'editor registrerà gli errori di compilazione nella console e, se provi ad accedere alla modalità di riproduzione, nella scheda Scena di Unity verrà visualizzato un popup di errore con il messaggio All compiler errors have to be fixed before you can enter playmode!.

Tipi, classi, metodi e membri mancanti

Molti problemi di Firebase si verificano a causa dell'impossibilità dell'editor e del compilatore di trovare i tipi, le classi, i metodi e i membri necessari. I sintomi più comuni sono varianti dei seguenti:

The type or namespace name ‘<CLASS OR NAMESPACE NAME>' could not be found. Are you missing a using directive or an assembly reference?

The type or namespace name <TYPE OR NAMESPACE NAME> does not exist in the namespace ‘Firebase<.OPTIONAL NESTED NAMESPACE NAME PATH>' (are you missing an assembly reference?)

‘<CLASS NAME>' does not contain a definition for ‘<MEMBER VARIABLE OR METHOD NAME>'

Passaggi per la risoluzione:
  1. Se utilizzi classi o metodi Firebase nel codice, assicurati di renderli disponibili inserendo le direttive using corrette per i prodotti Firebase specifici necessari.

    1. Esempi tratti da MechaHamster: Level Up With Firebase Edition:
      1. using Firebase.RemoteConfig;
      2. using Firebase.Crashlytics;
  2. Verifica di aver importato i pacchetti Firebase appropriati:

    1. Per importare i pacchetti appropriati:
      1. Aggiungi l'SDK Firebase Unity come .unitypackage oppure
      2. Esamina ed esegui una delle alternative descritte in Opzioni di installazione di Unity aggiuntive.
    2. Assicurati che ogni prodotto Firebase nel tuo progetto e in EDM4U:
      • Sono nella stessa versione
      • Sono stati installati come .unitypackage esclusivamente OPPURE esclusivamente tramite Unity Package Manager.
  3. Se hai importato l'SDK Firebase Unity prima della versione "10.0.0" come .unitypackage, l'archivio ZIP dell'SDK Firebase Unity contiene pacchetti per il supporto di .NET 3.x e .NET 4.x. Assicurati di aver incluso nel progetto solo il livello .NET Framework compatibile:

    1. La compatibilità tra le versioni di Unity Editor e i livelli del Framework .NET è descritta in Aggiungere Firebase al progetto Unity.
    2. Se hai importato accidentalmente i pacchetti Firebase al livello .NET Framework errato o devi passare dall'utilizzo di .unitypackage a una delle opzioni di installazione di Unity aggiuntive, il modo più semplice è rimuovere tutti i pacchetti Firebase utilizzando i metodi descritti in questa sezione sulla migrazione e poi importare di nuovo tutti i pacchetti Firebase.
  4. Verifica che l'editor stia ricostruendo il progetto e che i tuoi tentativi di riproduzione riflettano lo stato più recente del progetto:

    1. Per impostazione predefinita, l'editor di Unity è impostato per eseguire la ricostruzione ogni volta che vengono rilevate modifiche alle risorse o alla configurazione.
    2. È possibile che questa funzionalità sia stata disattivata e che Unity Editor sia impostato su aggiornamento/ricompilamento manuale. In questo caso, esamina il problema e prova a eseguire un aggiornamento manuale.

Errori di runtime della modalità di riproduzione

Se il gioco si avvia, ma si verificano problemi con Firebase durante l'esecuzione, prova a procedere nel seguente modo:

Assicurati di approvare i bundle Firebase in "Sicurezza e privacy" su macOS

Se, all'avvio del gioco nell'editor su Mac OS, viene visualizzata la finestra di dialogo "FirebaseCppApp-<version>.bundle Impossibile aprire perché non è possibile verificare lo sviluppatore", devi approvare lo specifico file del bundle nel menu Sicurezza e privacy di Mac.

A questo scopo, fai clic sull'icona Apple > Preferenze di Sistema > Sicurezza e Privacy.

Nel menu Sicurezza, circa a metà pagina, è presente una sezione che indica che l'utilizzo di ""FirebaseCppApp-<version>.bundle" è stato bloccato perché non proviene da uno sviluppatore identificato.

Fai clic sul pulsante Consenti comunque.

c35166e224cce720.png

Torna a Unity e premi di nuovo Riproduci.

Verrà visualizzato un avviso simile al primo:

5ad9ddb0d3a52892.png

Premi Apri e il programma potrà procedere. Non ti verrà più chiesto di questo determinato file.

Assicurati che il progetto contenga e utilizzi file di configurazione validi

  1. Assicurati che le impostazioni di build siano configurate per il target previsto (iOS o Android) in File > Impostazioni build. Per una discussione più completa, leggi la documentazione relativa alle impostazioni di compilazione di Unity.
  2. Scarica il file di configurazione per la tua app (google-services.json per Android o GoogleService-Info.plist per iOS) e il target di compilazione dalla console Firebase in Impostazioni progetto > Le tue app: Se hai già questi file, eliminali nel progetto e sostituiscili con la versione più recente, assicurandoti che la loro ortografia sia esattamente come mostrato sopra senza "(1)" o altri numeri aggiunti ai nomi dei file.
  3. Se la console contiene un messaggio relativo ai file in Assets/StreamingAssets/, assicurati che non siano presenti messaggi della console che indicano che Unity non è stato in grado di modificare i file
  4. Assicurati che Assets/StreamingAssets/google-services-desktop.json venga generato e corrisponda al file di configurazione scaricato.
    • Se non viene generato automaticamente e StreamingAssets/ non esiste, crea manualmente la directory nella directory Assets.
    • Controlla se Unity ha generato google-services-desktop.json.

Assicurati che tutti i prodotti Firebase e EDM4U siano stati installati esclusivamente tramite .unitypackage o Unity Package Manager

  1. Controlla sia la cartella Assets/ sia Unity Package Manager per assicurarti che gli SDK Firebase ed EDM4U siano stati installati esclusivamente tramite uno o l'altro metodo.
  2. Alcuni plug-in sviluppati da Google, come Google Play, e plug-in di terze parti potrebbero dipendere da EDM4U. Questi plug-in possono includere EDM4U nei propri pacchetti .unitypackage o Unity Package Manager (UPM). Assicurati che nel progetto sia presente una sola copia di EDM4U. Se i pacchetti UPM dipendono da EDM4U, è meglio conservare solo le versioni UPM di EDM4U, che puoi trovare nella pagina dell'archivio delle API di Google per Unity.

Assicurati che tutti i prodotti Firebase nel tuo progetto siano nella stessa versione.

  1. Se gli SDK Firebase sono stati installati tramite .unitypackage, controlla se tutte le librerie FirebaseCppApp in Assets/Firebase/Plugins/x86_64/ sono nella stessa versione.
  2. Se gli SDK Firebase sono stati installati tramite Unity Package Manager (UPM), apri Windows > Package Manager, cerca "Firebase" e assicurati che tutti i pacchetti Firebase siano della stessa versione.
  3. Se il tuo progetto contiene versioni diverse degli SDK Firebase, ti consigliamo di rimuoverli completamente prima di installarli di nuovo, questa volta con le stesse versioni. Il modo più pulito è rimuovere tutti i pacchetti Firebase tramite i metodi descritti in questa sezione sulla migrazione.

Errori di risoluzione e di build del dispositivo di destinazione

Se il gioco funziona nell'editor (configurato per il target di compilazione appropriato di tua scelta), verifica che External Dependency Manager for Unity (EDM4U) sia configurato e funzioni correttamente.

Il repository GitHub di EDM4U contiene una guida passo passo per questa parte della procedura che devi esaminare e seguire prima di procedere.

Problemi relativi a "Single Dex" e minificazione (obbligatorio se utilizzi Cloud Firestore)

Durante la compilazione di un'app per Android, potresti riscontrare un errore di compilazione relativo alla presenza di un singolo file dex. Il messaggio di errore è simile al seguente (se il tuo progetto è configurato per l'utilizzo del sistema di compilazione Gradle):

Cannot fit requested classes in a single dex file.

I file .dex vengono utilizzati per contenere un insieme di definizioni di classi e i relativi dati aggiuntivi associati per le applicazioni Android. Un singolo file dex è limitato a fare riferimento a 65.536 metodi. Le build non andranno a buon fine se il numero totale di metodi di tutte le librerie Android del progetto supera questo limite.

I due passaggi che seguono possono essere applicati in sequenza; attiva la funzionalità multidex solo se la minimizzazione non risolve il problema.

Attiva la minimizzazione

Unity ha introdotto la minimizzazione nel 2017.2 per eliminare il codice inutilizzato, il che può ridurre il numero totale di metodi di riferimento in un singolo file dex. * L'opzione è disponibile in Impostazioni player > Android > Impostazioni di pubblicazione > Minimizza. * Le opzioni possono variare in base alle versioni di Unity, quindi consulta la documentazione ufficiale di Unity.

Attivare Multidex

Se, dopo aver abilitato la minimizzazione, il numero di metodi di riferimento supera comunque il limite, un'altra opzione è attivare multidex. Esistono diversi modi per raggiungere questo obiettivo in Unity:

  • Se l'opzione Modello Gradle personalizzato in Impostazioni player è attivata, modifica mainTemplate.gradle.
  • Se utilizzi Android Studio per compilare il progetto esportato, modifica il file build.gradle a livello di modulo.

Per ulteriori dettagli, consulta la guida dell'utente di multidex.

Informazioni e correzione degli errori di runtime del dispositivo di destinazione

Se il gioco funziona nell'editor e può essere compilato e installato sul dispositivo di destinazione, ma si verificano errori di runtime, controlla e esamina i log generati sul dispositivo.

Questa sezione spiega come analizzare i log per individuare possibili errori e uno di questi errori che si verifica soltanto in fase di runtime sul dispositivo o nel simulatore.

Android

Simulatore

  • Controlla i log visualizzati nella console dell'emulatore o visualizza la finestra Logcat.

Dispositivo

Acquisisci familiarità con adb e adb logcat e su come utilizzarli.

  • Sebbene tu possa utilizzare i vari strumenti dell'ambiente a riga di comando per filtrare l'output, ti consigliamo di consultare le opzioni di logcat.
  • Un modo semplice per avviare una sessione ADB da zero è:

    adb logcat -c && adb logcat <OPTIONS>

    dove OPTIONS sono i flag a cui passi la riga di comando per filtrare l'output.

Utilizzare Logcat tramite Android Studio

Quando utilizzi Logcat tramite Android Studio, sono disponibili strumenti di ricerca aggiuntivi che semplificano la generazione di ricerche produttive.

iOS

Ispezione dei log

Se utilizzi un dispositivo fisico, collegalo al computer. Controlla lldb in Xcode.

Problemi con Swift

Se visualizzi log degli errori che menzionano la rapidità, consulta la sezione Gestore di dipendenze esterno per Unity in merito.

Passaggi successivi

Se il tuo gioco presenta ancora problemi di compilazione, compilazione o esecuzione relativi a Firebase, consulta la pagina dei problemi relativi all'SDK Firebase per Unity e valuta la possibilità di segnalarne uno nuovo. Inoltre, consulta la pagina di assistenza di Firebase per scoprire altre opzioni.