Comprendere gli arresti anomali di un gioco Unity utilizzando le funzionalità avanzate di Crashlytics

1. Introduzione

In questo codelab imparerai a utilizzare le funzionalità avanzate di Crashlytics, che ti daranno una migliore visibilità sugli arresti anomali e sulle circostanze che potrebbero averli causati.

Aggiungerai nuove funzionalità a un gioco di esempio, MechaHamster: Level Up with Firebase Edition. Questo gioco di esempio è una nuova versione del classico gioco Firebase MechaHamster, in cui è stata rimossa la maggior parte delle funzionalità Firebase integrate, offrendoti la possibilità di implementare nuovi utilizzi di Firebase al loro posto.

Aggiungerai un menu di debug al gioco. Questo menu di debug chiama i metodi che creerai e ti consente di esercitare le diverse funzionalità di Crashlytics. Questi metodi ti mostreranno come annotare i report sugli arresti anomali automatici con chiavi personalizzate, log personalizzati, errori non fatali e altro ancora.

Dopo aver creato il gioco, utilizzerai il menu di debug ed esaminerai i risultati per comprendere la visualizzazione unica che forniscono sul funzionamento del gioco in produzione.

Obiettivi didattici

• I tipi di errori rilevati automaticamente da Crashlytics.
• Errori aggiuntivi che possono essere registrati intenzionalmente.
• Come aggiungere ulteriori informazioni a questi errori per renderli più facili da comprendere.

Che cosa ti serve

• Unity (versione minima consigliata 2019+) con uno o entrambi i seguenti elementi:
  • Supporto della build iOS
  • Supporto per la build Android
• (Solo per Android) L'interfaccia a riga di comando di Firebase (utilizzata per caricare i simboli per i report sugli arresti anomali)
  • Segui le istruzioni per installare l'interfaccia a riga di comando di Firebase.
    Se hai già installato l'interfaccia a riga di comando, assicurati di eseguire l'aggiornamento all'ultima versione.

2. Configurazione dell'ambiente di sviluppo

Le sezioni seguenti descrivono come scaricare il codice di Level Up with Firebase e aprirlo in Unity.

Tieni presente che questo gioco di esempio Level Up with Firebase viene utilizzato da diversi altri codelab Firebase + Unity, quindi potresti aver già completato le attività di questa sezione. In questo caso, puoi andare direttamente all'ultimo passaggio di questa pagina: "Aggiungi gli SDK Firebase per Unity".

Scarica il codice

Clona il repository GitHub di questo codelab dalla riga di comando:

git clone https://github.com/firebase/level-up-with-firebase.git

In alternativa, se non hai installato git, puoi scaricare il repository come file ZIP.

Apri Level Up with Firebase nell'editor Unity

1. Avvia Unity Hub e, nella scheda Progetti, fai clic sulla freccia del menu a discesa accanto ad Apri.
2. Fai clic su Aggiungi progetto dal disco.
3. Vai alla directory contenente il codice e fai clic su Ok.
4. Se richiesto, seleziona una versione dell'editor Unity da utilizzare e la piattaforma di destinazione (Android o iOS).
5. Fai clic sul nome del progetto, level-up-with-firebase, e il progetto si aprirà nell'editor Unity.
6. Se l'editor non lo apre automaticamente, apri MainGameScene in Assets > Hamster nella scheda Project di Unity Editor.
   

Per saperne di più sull'installazione e l'utilizzo di Unity, consulta Lavorare in Unity.

3. Aggiungi Firebase al tuo progetto Unity

Crea un progetto Firebase

1. Accedi alla console Firebase utilizzando il tuo Account Google.
2. Fai clic sul pulsante per creare un nuovo progetto, quindi inserisci un nome per il progetto (ad esempio Mechahamster Codelab).
   

   Questo nome del progetto viene utilizzato come nome visualizzato nelle interfacce Firebase e Firebase crea automaticamente un ID progetto univoco in base a questo nome. Tieni presente che ora puoi fare clic sull'icona Modifica per impostare l'ID progetto che preferisci, ma non potrai modificarlo dopo la creazione del progetto.

   Ricorda l'ID progetto perché ti servirà in seguito per identificare il tuo progetto Firebase nella CLI Firebase. Se dimentichi l'ID, puoi sempre trovarlo in un secondo momento nelle Impostazioni progetto.

3. Fai clic su Continua.
4. Se richiesto, leggi e accetta i termini di Firebase, quindi fai clic su Continua.
5. (Facoltativo) Attiva l'assistenza AI nella console Firebase (denominata "Gemini in Firebase").
6. Per questo codelab, hai bisogno di Google Analytics per utilizzare in modo ottimale i prodotti Firebase, quindi mantieni l'opzione attiva per Google Analytics. Segui le istruzioni sullo schermo per configurare Google Analytics.
7. Fai clic su Crea progetto, attendi il provisioning del progetto, poi fai clic su Continua.

Registrare l'app con Firebase

1. Sempre nella console Firebase, al centro della pagina di riepilogo del progetto, fai clic sull'icona Unity per avviare il flusso di lavoro di configurazione oppure, se hai già aggiunto un'app al progetto Firebase, fai clic su Aggiungi app per visualizzare le opzioni della piattaforma.
2. Seleziona per registrare le destinazioni di build Apple (iOS) e Android.
3. Inserisci gli ID specifici per la piattaforma del tuo progetto Unity. Per questo codelab, inserisci quanto segue:
   • Per Apple (iOS): inserisci com.google.firebase.level-up nel campo ID bundle iOS.
   • Per Android: inserisci com.google.firebase.level_up nel campo Nome pacchetto Android.

   Importante: l'ID pacchetto iOS e il nome del pacchetto Android riportati sopra sono diversi. L'identificatore iOS non è valido per Android e viceversa. Assicurati di utilizzare l'identificatore corretto.

4. (Facoltativo) Inserisci i nickname specifici per la piattaforma del tuo progetto Unity.
5. Fai clic su Registra app e poi vai alla sezione Scarica il file di configurazione.

Aggiungere i file di configurazione di Firebase

Dopo aver fatto clic su Registra app, ti verrà chiesto di scaricare due file di configurazione (uno per ogni target di build). Per connettersi a Firebase, il progetto Unity ha bisogno dei metadati di Firebase in questi file.

1. Scarica entrambi i file di configurazione disponibili:
   • Per Apple (iOS): scarica GoogleService-Info.plist.
   • Per Android: scarica google-services.json.
2. Apri la finestra Project (Progetto) del progetto Unity, quindi sposta entrambi i file di configurazione nella cartella Assets (Asset).

   Importante: anche se prevedi di creare solo app per iOS o Android, devi scaricare entrambi i file e aggiungerli al tuo progetto.

3. Nella console Firebase, nel flusso di lavoro di configurazione, fai clic su Avanti e procedi ad aggiungere gli SDK Firebase per Unity.

Nota:puoi sempre scaricare di nuovo questi file in un secondo momento aprendo le impostazioni generali del progetto, scorrendo verso il basso fino alla sezione Le tue app e facendo clic sul pulsante di download per il file di configurazione desiderato.

Aggiungi gli SDK Firebase per Unity

1. Fai clic su Scarica l'SDK Firebase Unity nella console Firebase.

   Nota:il download di questo SDK potrebbe richiedere un po' di tempo. Prendi un caffè o un tè e idratati.

2. Decomprimi l'SDK in un percorso semplice da raggiungere.
3. Nel tuo progetto Unity aperto, vai a Assets > Import Package > Custom Package (Risorse > Importa pacchetto > Pacchetto personalizzato).
4. Nella finestra di dialogo Importa pacchetto, vai alla directory che contiene l'SDK non compresso, seleziona FirebaseAnalytics.unitypackage e poi fai clic su Apri.
5. Nella finestra di dialogo Import Unity Package (Importa il pacchetto Unity) visualizzata, fai clic su Import (Importa).
6. Ripeti i passaggi precedenti per importare FirebaseCrashlytics.unitypackage.
7. Torna alla console Firebase e, nel flusso di lavoro di configurazione, fai clic su Avanti.

Per saperne di più sull'aggiunta degli SDK Firebase ai progetti Unity, consulta Opzioni di installazione di Unity aggiuntive.

4. Configurare Crashlytics nel progetto Unity

Per utilizzare Crashlytics nei progetti Unity, devi eseguire alcuni passaggi di configurazione aggiuntivi. Naturalmente, dovrai inizializzare l'SDK. Inoltre, dovrai caricare i simboli per poter visualizzare le stacktrace simbolizzate nella console Firebase e dovrai forzare un arresto anomalo di test per assicurarti che Firebase riceva gli eventi di arresto anomalo.

Inizializza l'SDK Crashlytics

1. In Assets/Hamster/Scripts/MainGame.cs, aggiungi le seguenti istruzioni using:

   using Firebase.Crashlytics;
   using Firebase.Extensions;
   

   Il primo modulo consente di utilizzare i metodi dell'SDK Crashlytics, mentre il secondo contiene alcune estensioni dell'API C# Tasks. Senza entrambe using le istruzioni, il seguente codice non funzionerà.
2. Ancora in MainGame.cs, aggiungi l'inizializzazione di Firebase al metodo Start() esistente chiamando InitializeFirebaseAndStartGame():

   void Start()
   {
     Screen.SetResolution(Screen.width / 2, Screen.height / 2, true);
     InitializeFirebaseAndStartGame();
   }
   

3. Ancora una volta, in MainGame.cs, trova InitializeFirebaseAndStartGame(), dichiara una variabile dell'app e poi sovrascrivi l'implementazione del metodo come segue:

   public Firebase.FirebaseApp app = null;
   
   // Begins the firebase initialization process and afterwards, opens the main menu.
   private void InitializeFirebaseAndStartGame()
   {
     Firebase.FirebaseApp.CheckAndFixDependenciesAsync()
     .ContinueWithOnMainThread(
       previousTask => 
       {
         var dependencyStatus = previousTask.Result;
         if (dependencyStatus == Firebase.DependencyStatus.Available) {
           // Create and hold a reference to your FirebaseApp,
           app = Firebase.FirebaseApp.DefaultInstance;
           // Set the recommended Crashlytics uncaught exception behavior.
           Crashlytics.ReportUncaughtExceptionsAsFatal = true;
           InitializeCommonDataAndStartGame();
         } else {
           UnityEngine.Debug.LogError(
             $"Could not resolve all Firebase dependencies: {dependencyStatus}\n" +
             "Firebase Unity SDK is not safe to use here");
         }
       });
   }
   

Il posizionamento della logica di inizializzazione qui impedisce l'interazione del giocatore prima dell'inizializzazione delle dipendenze di Firebase.

I vantaggi e gli effetti della segnalazione delle eccezioni non gestite come irreversibili sono descritti nelle domande frequenti di Crashlytics.

Crea il progetto e carica i simboli

Nota:completa i passaggi descritti in questa sezione per configurare Crashlytics. In futuro, completa questi passaggi ogni volta che crei una build di release o una build per cui vuoi visualizzare le analisi dello stack con simboli nella console Firebase (in questo codelab, dopo ogni passaggio).

I passaggi per creare e caricare i simboli sono diversi per le app per iOS e Android.

iOS+ (piattaforma Apple)

1. Nella finestra di dialogo Impostazioni build, esporta il progetto in un workspace Xcode.
2. Crea la tua app.
   Per le piattaforme Apple, il plug-in Firebase Unity Editor configura automaticamente il progetto Xcode per generare e caricare un file di simboli compatibile con Crashlytics sui server Firebase per ogni build. Queste informazioni sui simboli sono necessarie per visualizzare le analisi dello stack con simboli nella dashboard di Crashlytics.

Android

1. (solo durante la configurazione iniziale, non per ogni build) Configura la build:
   1. Crea una nuova cartella denominata Builds nella directory principale del progetto (ovvero come elemento di pari livello della directory Assets) e poi crea una sottocartella denominata Android.
   2. In File > Build Settings > Player Settings > Configuration, imposta Scripting Backend su IL2CPP.
      • In genere, IL2CPP fa sì che le build siano più piccole e abbiano un rendimento migliore.
      • IL2CPP è anche l'UNICA opzione disponibile su iOS e la sua selezione qui consente alle due piattaforme di essere più simili e semplifica il debug delle differenze tra le due (se scegli di creare entrambe).
2. Crea la tua app. In File > Impostazioni build, completa le seguenti operazioni:
   1. Assicurati che la casella di controllo Crea symbols.zip sia selezionata (o, se viene visualizzato un menu a discesa, seleziona Debug).
   2. Crea l'APK direttamente da Unity Editor nella sottocartella Builds/Android che hai appena creato.
3. Una volta completata la build, devi generare un file di simboli compatibile con Crashlytics e caricarlo sui server Firebase. Queste informazioni sui simboli sono necessarie per visualizzare le analisi dello stack con simboli per gli arresti anomali delle librerie native nella dashboard di Crashlytics.
   
   Genera e carica questo file di simboli eseguendo il seguente comando dell'interfaccia a riga di comando di Firebase:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

   • FIREBASE_APP_ID: l'ID app Firebase per Android (non il nome del pacchetto). Trova questo valore nel file google-services.json che hai scaricato in precedenza. È il valore mobilesdk_app_id.
     ID app Firebase per Android di esempio: 1:567383003300:android:17104a2ced0c9b9b
   • PATH/TO/SYMBOLS: il percorso del file di simboli compresso generato nella directory Builds/Android al termine della build (ad esempio: Builds/Android/myapp-1.0-v100.symbols.zip).

     Nota:questo nome file cambierà man mano che il progetto viene creato con numeri diversi impostati per Version e Bundle Version Code in File > Impostazioni di build > Impostazioni del giocatore > Identificazione.

Forzare un arresto anomalo di test per completare la configurazione

Per completare la configurazione di Crashlytics e visualizzare i dati iniziali nella dashboard di Crashlytics della console Firebase, devi forzare un arresto anomalo di test.

1. In MainGameScene, trova EmptyObject GameObject nell'Hierarchy dell'editor, aggiungi il seguente script e salva la scena. Questo script causerà un arresto anomalo del test pochi secondi dopo l'esecuzione dell'app.

   using System;
   using UnityEngine;
   
   public class CrashlyticsTester : MonoBehaviour {
       // Update is called once per frame
       void Update()
       {
           // Tests your Crashlytics implementation by
           // throwing an exception every 60 frames.
           // You should see reports in the Firebase console
           // a few minutes after running your app with this method.
           if(Time.frameCount >0 && (Time.frameCount%60) == 0)
           {
               throw new System.Exception("Test exception; please ignore");
           }
       }
   }
   

2. Crea la tua app e carica le informazioni sui simboli al termine della build.
   • iOS: il plug-in Firebase Unity Editor configura automaticamente il progetto Xcode per caricare il file dei simboli.
   • Android: esegui il comando crashlytics:symbols:upload dell'interfaccia a riga di comando di Firebase per caricare il file dei simboli.

   Nota:se è la prima volta che crei una build per un determinato target mobile, questo tempo di compilazione potrebbe richiedere diversi minuti. Le build successive saranno molto più veloci.

3. Esegui l'app. Una volta in esecuzione, osserva il log del dispositivo e attendi che l'eccezione venga attivata da CrashlyticsTester.
   • iOS: visualizza i log nel riquadro inferiore di Xcode.
   • Android: visualizza i log eseguendo il seguente comando nel terminale: adb logcat.
4. Visita la dashboard di Crashlytics per visualizzare l'eccezione. La vedrai nella tabella Problemi nella parte inferiore della dashboard. Più avanti nel codelab, scoprirai di più su come esplorare questi report.
5. Dopo aver confermato che l'evento è stato caricato su Crashlytics, seleziona l'EmptyObject GameObject a cui l'hai allegato, rimuovi solo il componente CrashlyticsTester e poi salva la scena per ripristinarla alle condizioni originali.

5. Attivare e comprendere il menu di debug

Finora hai aggiunto Crashlytics al tuo progetto Unity, hai completato la configurazione e hai verificato che l'SDK Crashlytics carichi gli eventi su Firebase. Ora creerai un menu nel tuo progetto Unity che mostrerà come utilizzare funzionalità più avanzate di Crashlytics nel tuo gioco. Il progetto Unity Level Up with Firebase ha già un menu di debug nascosto che renderai visibile e per cui scriverai la funzionalità.

Attivare il menu di debug

Il pulsante per accedere al menu di debug esiste nel tuo progetto Unity, ma al momento non è abilitato. Devi abilitare il pulsante per accedervi dal prefab MainMenu:

1. Nell'editor Unity, apri il prefab denominato MainMenu.
2. Nella gerarchia del prefab, individua il sotto-oggetto disattivato denominato DebugMenuButton e selezionalo.
3. Attiva DebugMenuButton selezionando la casella nell'angolo in alto a sinistra, a sinistra del campo di testo contenente DebugMenuButton.
4. Salva il prefab.
5. Esegui il gioco nell'editor o sul tuo dispositivo. Ora il menu dovrebbe essere accessibile.

Importante: poiché i metodi di arresto anomalo non sono attualmente implementati, toccando i rispettivi pulsanti verrà generato un System.NotImplementedException e non verrà eseguita alcuna altra operazione.

Visualizzare in anteprima e comprendere i corpi dei metodi per il menu di debug

Più avanti in questo codelab, scriverai i corpi dei metodi per alcuni metodi di debug di Crashlytics preconfigurati. Nel progetto Unity Level Up with Firebase, invece, i metodi sono definiti e chiamati da DebugMenu.cs.

Sebbene alcuni di questi metodi chiamino i metodi Crashlytics e generino errori, la capacità di Crashlytics di rilevare questi errori non dipende dalla chiamata preventiva di questi metodi. Al contrario, i report sugli arresti anomali generati dal rilevamento automatico degli errori verranno migliorati dalle informazioni aggiunte da questi metodi.

Apri DebugMenu.cs e trova i seguenti metodi:

Metodi per generare e annotare i problemi di Crashlytics:

• CrashNow
• LogNonfatalError
• LogStringsAndCrashNow
• SetAndOverwriteCustomKeyThenCrash
• SetLogsAndKeysBeforeANR

Metodi per registrare gli eventi Analytics per facilitare il debug:

• LogProgressEventWithStringLiterals
• LogIntScoreWithBuiltInEventAndParams

Nei passaggi successivi di questo codelab, implementerai questi metodi e imparerai come aiutano ad affrontare situazioni specifiche che possono verificarsi nello sviluppo di giochi.

6. Garantire la consegna dei report sugli arresti anomali durante lo sviluppo

Prima di iniziare a implementare questi metodi di debug e vedere come influiscono sui report sugli arresti anomali, assicurati di comprendere come vengono segnalati gli eventi a Crashlytics.

Per i progetti Unity, gli eventi di arresto anomalo e di eccezione nel gioco vengono scritti immediatamente su disco. Per le eccezioni non rilevate che non causano l'arresto anomalo del gioco (ad esempio, le eccezioni C# non rilevate nella logica di gioco), puoi fare in modo che l'SDK Crashlytics le segnali come eventi irreversibili impostando la proprietà Crashlytics.ReportUncaughtExceptionsAsFatal su true nel punto in cui inizializzi Crashlytics nel tuo progetto Unity. Questi eventi vengono segnalati a Crashlytics in tempo reale senza che l'utente finale debba riavviare il gioco. Tieni presente che gli arresti anomali nativi vengono sempre segnalati come eventi irreversibili e inviati quando un utente finale riavvia il gioco.

Nota:per segnalare le eccezioni non rilevate come eventi irreversibili, il tuo progetto Unity deve utilizzare Firebase Crashlytics Unity SDK 10.4.0 e versioni successive.

Inoltre, tieni presente le seguenti piccole, ma significative, differenze tra il modo in cui i diversi ambienti di runtime inviano le informazioni di Crashlytics a Firebase:

Simulatore iOS:

• Le informazioni di Crashlytics vengono segnalate solo se scolleghi Xcode dal simulatore. Se Xcode è collegato, rileva gli errori a monte, impedendo la distribuzione delle informazioni.

Dispositivi fisici mobili (Android e iOS):

• Specifico per Android: gli ANR vengono segnalati solo su Android 11 e versioni successive. Gli ANR e gli eventi non irreversibili vengono segnalati alla successiva esecuzione.

Unity Editor:

• Le informazioni di Crashlytics dell'editor in modalità di riproduzione o in modalità autonoma NON vengono registrate o caricate su Firebase. Inoltre, il flusso di lavoro di sviluppo di Firebase Desktop non supporta Crashlytics.

Prova a bloccare il gioco con il tocco di un pulsante in CrashNow()

Una volta configurato Crashlytics nel gioco, l'SDK Crashlytics registra automaticamente gli arresti anomali e le eccezioni non rilevate e li carica su Firebase per l'analisi. I report vengono visualizzati nella dashboard di Crashlytics nella console Firebase.

1. Per dimostrare che si tratta effettivamente di un'operazione automatica, apri DebugMenu.cs e poi sovrascrivi il metodo CrashNow() come segue:

   void CrashNow()
   {
       TestCrash();
   }
   

2. Crea la tua app.
3. (Solo Android) Carica i simboli eseguendo il seguente comando dell'interfaccia a riga di comando di Firebase:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

4. Tocca il pulsante Arresto anomalo ora e vai al passaggio successivo di questo codelab per scoprire come visualizzare e interpretare il report sugli arresti anomali.

7. Informazioni sui report sui problemi nella console Firebase

Per quanto riguarda la visualizzazione dei report sugli arresti anomali, devi sapere qualcosa in più su come ottenere il massimo da questi report. Ciascuno dei metodi che scrivi mostrerà come aggiungere diversi tipi di informazioni ai report di Crashlytics.

1. Tocca il pulsante Arresto anomalo ora, quindi riavvia l'app.
2. Vai alla dashboard di Crashlytics. Scorri verso il basso fino alla tabella Problemi nella parte inferiore della dashboard, dove Crashlytics raggruppa gli eventi che hanno tutti la stessa causa principale in "problemi".
3. Fai clic sul nuovo problema elencato nella tabella Problemi. In questo modo viene visualizzato il Riepilogo eventi di ogni singolo evento inviato a Firebase.
   
   Dovresti visualizzare una schermata simile alla seguente. Nota come il Riepilogo evento mostri in evidenza lo stack trace della chiamata che ha causato l'arresto anomalo.

Metadati aggiuntivi

Un'altra scheda utile è Metadati di Unity. Questa sezione fornisce informazioni sugli attributi del dispositivo su cui si è verificato l'evento, tra cui le caratteristiche fisiche, il modello/le specifiche della CPU e tutti i tipi di metriche della GPU.

Ecco un esempio in cui le informazioni in questa scheda potrebbero essere utili:
immagina che il tuo gioco utilizzi molto gli shader per ottenere un determinato aspetto, ma non tutti gli smartphone hanno GPU in grado di eseguire il rendering di questa funzionalità. Le informazioni nella scheda Metadati di Unity possono darti un'idea migliore dell'hardware per cui la tua app deve eseguire i test quando decidi quali funzionalità rendere disponibili automaticamente o disattivare completamente.

Anche se un bug o un arresto anomalo potrebbe non verificarsi mai sul tuo dispositivo, data l'enorme diversità dei dispositivi Android in circolazione, è utile comprendere meglio i particolari"punti caldi" dei dispositivi del tuo pubblico.

8. Generare, rilevare e registrare un'eccezione

Spesso, in qualità di sviluppatore, anche se il codice rileva e gestisce correttamente un'eccezione di runtime, è bene annotare che si è verificata e in quali circostanze. Crashlytics.LogException può essere utilizzato proprio a questo scopo: inviare un evento di eccezione a Firebase in modo da poter eseguire il debug del problema nella console Firebase.

1. In Assets/Hamster/Scripts/States/DebugMenu.cs, aggiungi quanto segue alle istruzioni using:

   // Import Firebase
   using Firebase.Crashlytics;
   

2. Sempre in DebugMenu.cs, sovrascrivi LogNonfatalError() come segue:

   void LogNonfatalError()
   {
       try
       {
           throw new System.Exception($"Test exception thrown in {nameof(LogNonfatalError)}");
       }
       catch(System.Exception exception)
       {
           Crashlytics.LogException(exception);
       }
   }
   

3. Crea la tua app.
4. (Solo Android) Carica i simboli eseguendo il seguente comando dell'interfaccia a riga di comando di Firebase:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

5. Tocca il pulsante Registra errore non fatale, quindi riavvia l'app.
6. Vai alla dashboard di Crashlytics e dovresti vedere qualcosa di simile a quello che hai visto nell'ultimo passaggio di questo codelab.
7. Questa volta, però, limita il filtro Tipo di evento a Non irreversibili in modo da visualizzare solo gli errori non irreversibili, come quello appena registrato.
   

9. Registra le stringhe in Crashlytics per comprendere meglio il flusso di esecuzione del programma

Hai mai provato a capire perché una riga di codice chiamata da più percorsi, centinaia se non migliaia di volte per sessione, può generare improvvisamente un'eccezione o un arresto anomalo? Anche se potrebbe essere utile esaminare il codice in un IDE e osservare i valori più da vicino, cosa succede se questo si verifica solo in una percentuale molto piccola di utenti? Ancora peggio, cosa faresti se non riuscissi a replicare l'arresto anomalo in nessun modo?

In situazioni come questa, avere un po' di contesto può fare la differenza. Con Crashlytics.Log, puoi scrivere il contesto di cui hai bisogno. Considera questi messaggi come suggerimenti per la tua versione futura su ciò che potrebbe accadere.

Sebbene i log possano essere utilizzati in svariati modi, in genere sono più utili per registrare situazioni in cui l'ordine e/o l'assenza di chiamate sono informazioni di vitale importanza.

1. In Assets/Hamster/Scripts/States/DebugMenu.cs, sovrascrivi LogStringsAndCrashNow() come segue:

   void LogStringsAndCrashNow()
   {
       Crashlytics.Log($"This is the first of two descriptive strings in {nameof(LogStringsAndCrashNow)}");
       const bool RUN_OPTIONAL_PATH = false;
       if(RUN_OPTIONAL_PATH)
       {
           Crashlytics.Log(" As it stands, this log should not appear in your records because it will never be called.");
       }
       else
       {
           Crashlytics.Log(" A log that will simply inform you which path of logic was taken. Akin to print debugging.");
       }
       Crashlytics.Log($"This is the second of two descriptive strings in {nameof(LogStringsAndCrashNow)}");
       TestCrash();
   }
   

2. Crea la tua app.
3. (Solo Android) Carica i simboli eseguendo il seguente comando dell'interfaccia a riga di comando di Firebase:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

4. Tocca il pulsante Stringhe di log e arresto anomalo ora, quindi riavvia l'app.
5. Torna alla dashboard di Crashlytics e fai clic sul problema più recente elencato nella tabella Problemi. Anche in questo caso, dovresti vedere qualcosa di simile ai problemi precedenti.
   
6. Tuttavia, se fai clic sulla scheda Log all'interno di un Riepilogo eventi, viene visualizzata una schermata come questa:
   

Nota:questi log sono utili non solo per il messaggio, ma anche per i timestamp, che ti aiutano a capire l'ordine in cui sono stati generati.

Importante:per evitare di rallentare l'app, Crashlytics limita i log a 64 KB ed elimina le voci di log meno recenti quando il log di una sessione supera questo limite.

10. Scrivere e sovrascrivere una chiave personalizzata

Supponiamo che tu voglia comprendere meglio un arresto anomalo corrispondente a variabili impostate su un numero ridotto di valori o configurazioni. Potrebbe essere utile poter filtrare in base alla combinazione di variabili e valori possibili che stai esaminando in un determinato momento.

Oltre a registrare stringhe arbitrarie, Crashlytics offre un'altra forma di debug quando è utile conoscere lo stato esatto del programma al momento dell'arresto anomalo: le chiavi personalizzate.

Si tratta di coppie chiave-valore che puoi impostare per una sessione. A differenza dei log, che si accumulano e sono puramente additivi, le chiavi possono essere sovrascritte per riflettere solo lo stato più recente di una variabile o di una condizione.

Oltre a essere un registro dell'ultimo stato registrato del programma, queste chiavi possono essere utilizzate come potenti filtri per i problemi di Crashlytics.

1. In Assets/Hamster/Scripts/States/DebugMenu.cs, sovrascrivi SetAndOverwriteCustomKeyThenCrash() come segue:

   void SetAndOverwriteCustomKeyThenCrash()
   {
       const string CURRENT_TIME_KEY = "Current Time";
       System.TimeSpan currentTime = System.DateTime.Now.TimeOfDay;
       Crashlytics.SetCustomKey(
           CURRENT_TIME_KEY,
           DayDivision.GetPartOfDay(currentTime).ToString() // Values must be strings
           );
   
       // Time Passes
       currentTime += DayDivision.DURATION_THAT_ENSURES_PHASE_CHANGE;
   
       Crashlytics.SetCustomKey(
           CURRENT_TIME_KEY,
           DayDivision.GetPartOfDay(currentTime).ToString()
           );
       TestCrash();
   }
   

2. Crea la tua app.
3. (Solo Android) Carica i simboli eseguendo il seguente comando dell'interfaccia a riga di comando di Firebase:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

4. Tocca il pulsante Imposta chiave personalizzata e arresto anomalo, quindi riavvia l'app.
5. Torna alla dashboard di Crashlytics e fai clic sul problema più recente elencato nella tabella Problemi. Anche in questo caso, dovresti vedere qualcosa di simile ai problemi precedenti.
6. Questa volta, però, fai clic sulla scheda Chiavi nel Riepilogo eventi per visualizzare il valore delle chiavi, incluso Current Time:
   

   Importante: la chiave di crash_info_entry_0 viene compilata automaticamente da Crashlytics solo quando l'app viene eseguita dal simulatore iOS.

Perché utilizzare chiavi personalizzate anziché log personalizzati?

• I log sono utili per archiviare dati sequenziali, ma le chiavi personalizzate sono più adatte se vuoi solo il valore più recente.
• Nella console Firebase, puoi filtrare facilmente i problemi in base ai valori delle chiavi nella casella di ricerca della tabella Problemi��.

Analogamente ai log, anche le chiavi personalizzate hanno un limite. Crashlytics supporta un massimo di 64 coppie chiave-valore. Una volta raggiunto questo limite, i valori aggiuntivi non vengono salvati. Ogni coppia chiave-valore può avere una dimensione massima di 1 KB.

11. (Solo Android) Utilizza chiavi e log personalizzati per comprendere e diagnosticare un errore ANR

Importante: la seguente classe di problemi riguarda principalmente Android 11 e versioni successive. Se non corrisponde al tuo caso d'uso di sviluppo, salta questa sezione.

Una delle classi di problemi più difficili da eseguire il debug per gli sviluppatori Android è l'errore L'applicazione non risponde (ANR). Gli errori ANR si verificano quando un'app non risponde all'input per più di 5 secondi. In questo caso, l'app si è bloccata o è molto lenta. Agli utenti viene mostrata una finestra di dialogo in cui possono scegliere se "Attendere" o "Chiudere l'app".

Gli errori ANR sono una cattiva esperienza utente e (come indicato nel link ANR sopra) possono influire sulla rilevabilità della tua app nel Google Play Store. A causa della loro complessità e del fatto che sono spesso causati da codice multithread con un comportamento molto diverso su diversi modelli di smartphone, la riproduzione degli errori ANR durante il debug è spesso molto difficile, se non quasi impossibile. Pertanto, l'approccio analitico e deduttivo è in genere il migliore.

Con questo metodo, utilizzeremo una combinazione di Crashlytics.LogException, Crashlytics.Log e Crashlytics.SetCustomKey per integrare la registrazione automatica dei problemi e ottenere maggiori informazioni.

Importante: tieni presente che il codice di blocco viene eseguito sul thread UI di UnityPlayerActivity. Questo è un po' innaturale in Unity, in quanto il thread non è lo stesso del thread principale di Unity, che è il luogo predefinito in cui viene eseguito il codice di gioco. Il debug degli errori ANR può essere particolarmente difficile perché possono essere causati da plug-in o altro codice che viene eseguito in modo non idiomatico sul thread UI.

1. In Assets/Hamster/Scripts/States/DebugMenu.cs, sovrascrivi SetLogsAndKeysBeforeANR() come segue:

   void SetLogsAndKeysBeforeANR()
   {
       System.Action<string,long> WaitAndRecord =
       (string methodName, long targetCallLength)=>
       {
           System.Diagnostics.Stopwatch stopWatch = new System.Diagnostics.Stopwatch();
           const string CURRENT_FUNCTION = "Current Async Function";
   
           // Initialize key and start timing
           Crashlytics.SetCustomKey(CURRENT_FUNCTION, methodName);
           stopWatch.Start();
   
           // The actual (simulated) work being timed.
           BusyWaitSimulator.WaitOnSimulatedBlockingWork(targetCallLength);
   
           // Stop timing
           stopWatch.Stop();
   
           if(stopWatch.ElapsedMilliseconds>=BusyWaitSimulator.EXTREME_DURATION_MILLIS)
           {
             Crashlytics.Log($"'{methodName}' is long enough to cause an ANR.");
           }
           else if(stopWatch.ElapsedMilliseconds>=BusyWaitSimulator.SEVERE_DURATION_MILLIS)
           {
             Crashlytics.Log($"'{methodName}' is long enough it may cause an ANR");
           }
       };
   
       WaitAndRecord("DoSafeWork",1000L);
       WaitAndRecord("DoSevereWork",BusyWaitSimulator.SEVERE_DURATION_MILLIS);
       WaitAndRecord("DoExtremeWork",2*BusyWaitSimulator.EXTREME_DURATION_MILLIS);
   }
   

2. Crea la tua app.
3. Carica i simboli eseguendo il seguente comando dell'interfaccia a riga di comando di Firebase:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

4. Tocca il pulsante con l'etichetta Imposta log e chiavi → ANR, quindi riavvia l'app.
5. Torna alla dashboard di Crashlytics e fai clic sul nuovo problema nella tabella Problemi per visualizzare il Riepilogo eventi. Se la chiamata è andata a buon fine, dovresti visualizzare un messaggio simile a questo:
   
   
   Come puoi vedere, Firebase ha identificato l'attesa attiva sul thread come il motivo principale per cui la tua app ha attivato un errore ANR.
   
6. Se esamini i log nella scheda Log del Riepilogo eventi, vedrai che l'ultimo metodo registrato come completato è DoSevereWork.
   
   
   Al contrario, l'ultimo metodo elencato come avviato è DoExtremeWork, il che indica che l'errore ANR si è verificato durante questo metodo e che il gioco si è chiuso prima di poter registrare DoExtremeWork.
   
   

Importante: se non vedi un errore ANR su Android e visualizzi invece un errore che menziona InvalidOperationException, leggi i log. Questo errore personalizzato è incluso in questo codelab. Segui le istruzioni registrate dall'eccezione per risolvere il problema. Ricompila, esegui il deployment e itera finché non ricevi l'errore previsto.

Perché dovresti farlo?

• Riprodurre gli errori ANR è incredibilmente difficile, quindi la possibilità di ottenere informazioni dettagliate sull'area del codice e sulle metriche è fondamentale per scoprirlo in modo deduttivo.
• Grazie alle informazioni memorizzate nelle chiavi personalizzate, ora sai quale thread asincrono ha richiesto più tempo per l'esecuzione e quali rischiavano di attivare errori ANR. Questo tipo di dati logici e numerici correlati ti mostrerà in quale parte del codice è più necessario eseguire l'ottimizzazione.

12. Alternare gli eventi Analytics per arricchire ulteriormente i report

Anche i seguenti metodi possono essere chiamati dal menu Debug, ma anziché generare problemi, utilizzano Google Analytics come un'altra fonte di informazioni per comprendere meglio il funzionamento del gioco.

A differenza degli altri metodi che hai scritto in questo codelab, devi utilizzare questi metodi in combinazione con gli altri. Chiama questi metodi (premendo il pulsante corrispondente nel menu di debug) nell'ordine arbitrario che preferisci prima di eseguirne un altro. Poi, quando esamini le informazioni nel problema specifico di Crashlytics, vedrai un log ordinato degli eventi Analytics. Questi dati possono essere utilizzati in un gioco per comprendere meglio una combinazione di flusso del programma o input dell'utente, a seconda di come hai instrumentato la tua app.

Nota: di seguito sono riportati casi d'uso piuttosto semplici per Analytics. Le funzionalità avanzate di Analytics non rientrano nell'ambito di questo codelab. Se vuoi saperne di più, capire meglio cosa viene registrato esattamente da questi strumenti o sapere come eseguire il debug della procedura di generazione dei report, consulta Guida introduttiva a Google Analytics per Unity.

1. In Assets/Hamster/Scripts/States/DebugMenu.cs, sovrascrivi le implementazioni esistenti dei seguenti metodi:

   public void LogProgressEventWithStringLiterals()
   {
         Firebase.Analytics.FirebaseAnalytics.LogEvent("progress", "percent", 0.4f);
   }
   

   public void LogIntScoreWithBuiltInEventAndParams()
   {
         Firebase.Analytics.FirebaseAnalytics
           .LogEvent(
             Firebase.Analytics.FirebaseAnalytics.EventPostScore,
             Firebase.Analytics.FirebaseAnalytics.ParameterScore,
             42
           );
   }
   

2. Crea e implementa il gioco, quindi accedi al menu di debug.
3. (Solo Android) Carica i simboli eseguendo il seguente comando dell'interfaccia a riga di comando di Firebase:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

4. Premi uno o più volte almeno uno dei seguenti tasti per chiamare le funzioni sopra indicate:
   • Log String Event
   • Log Int Event
5. Premi il pulsante Arresta ora.
6. Riavvia il gioco per caricare l'evento di arresto anomalo su Firebase.
7. Quando registri varie sequenze arbitrarie di eventi Analytics e poi il tuo gioco genera un evento da cui Crashlytics crea un report (come hai appena fatto), questi vengono aggiunti alla scheda Log del Riepilogo eventi di Crashlytics, come mostrato di seguito:
   

Importante:la visualizzazione degli eventi personalizzati nella dashboard di Analytics della console Firebase potrebbe richiedere più tempo rispetto alla visualizzazione in un log degli arresti anomali nella dashboard di Crashlytics. Inoltre, gli eventi Analytics potrebbero non essere visualizzati in entrambi i luoghi subito dopo la registrazione.

13. Prospettive future

In questo modo, avrai una base teorica migliore su cui integrare i report sugli arresti anomali generati automaticamente. Queste nuove informazioni ti consentono di utilizzare lo stato attuale, i record degli eventi passati e gli eventi Google Analytics esistenti per analizzare meglio la sequenza di eventi e la logica che ha portato al risultato.

Se la tua app ha come target Android 11 (livello API 30) o versioni successive, valuta la possibilità di incorporare GWP-ASan, una funzionalità di allocazione della memoria nativa utile per il debug degli arresti anomali causati da errori di memoria nativa come bug use-after-free e heap-buffer-overflow. Per sfruttare questa funzionalità di debug, attiva esplicitamente GWP-ASan.

Passaggi successivi

Vai al codelab Strumenta il tuo gioco Unity con Remote Config, dove imparerai a utilizzare Remote Config e i test A/B in Unity.