Mit erweiterten Crashlytics-Funktionen Abstürze von Unity-Spielen nachvollziehen

1. Einführung

In diesem Codelab erfahren Sie, wie Sie die erweiterten Funktionen von Crashlytics verwenden, um Abstürze und die Umstände, die zu ihnen geführt haben könnten, besser nachvollziehen zu können.

Sie werden dem Beispielspiel MechaHamster: Level Up with Firebase Edition neue Funktionen hinzufügen. Bei diesem Beispielspiel handelt es sich um eine neue Version des klassischen Firebase-Spiels MechaHamster, in der die meisten integrierten Firebase-Funktionen entfernt wurden. So haben Sie die Möglichkeit, stattdessen neue Firebase-Funktionen zu implementieren.

Sie fügen dem Spiel ein Debug-Menü hinzu. Dieses Menü zur Fehlerbehebung ruft Methoden auf, die Sie ausführen, und ermöglicht es Ihnen, die verschiedenen Funktionen von Crashlytics auszuführen. Anhand dieser Methoden erfahren Sie, wie Sie Ihre automatischen Absturzberichte unter anderem mit benutzerdefinierten Schlüsseln, benutzerdefinierten Protokollen und nicht kritischen Fehlern annotieren.

Nachdem Sie das Spiel erstellt haben, verwenden Sie das Debug-Menü und prüfen die Ergebnisse, um einen einzigartigen Einblick in die Funktionsweise Ihres Spiels zu erhalten.

Lerninhalte

• Die Arten von Fehlern, die von Crashlytics automatisch erkannt werden.
• Zusätzliche Fehler, die absichtlich aufgezeichnet werden können.
• Wie Sie diesen Fehlern weitere Informationen hinzufügen, damit sie leichter verständlich sind.

Voraussetzungen

• Unity (empfohlene Mindestversion ab 2019) mit einer oder beiden der folgenden Bedingungen:
  • Unterstützung für iOS-Builds
  • Android Build-Support
• (Nur für Android) Firebase CLI (zum Hochladen von Symbolen für Absturzberichte)
  • Folgen Sie der Anleitung zum Installieren von Firebase CLI.
    Wenn Sie die Befehlszeile bereits installiert haben, müssen Sie ein Update auf die neueste Version durchführen.

2. Entwicklungsumgebung einrichten

In den folgenden Abschnitten wird beschrieben, wie Sie den Code für Level Up mit Firebase herunterladen und in Unity öffnen.

Dieses Beispielspiel Level Up with Firebase wird in mehreren anderen Firebase + Unity-Codelabs verwendet. Möglicherweise haben Sie die Aufgaben in diesem Abschnitt also bereits abgeschlossen. In diesem Fall können Sie direkt mit dem letzten Schritt auf dieser Seite fortfahren: „Firebase SDKs für Unity hinzufügen“.

Code herunterladen

Klonen Sie das GitHub-Repository dieses Codelab über die Befehlszeile:

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

Wenn Sie Git nicht installiert haben, können Sie das Repository auch als ZIP-Datei herunterladen.

Level Up with Firebase im Unity-Editor öffnen

1. Öffnen Sie den Unity Hub und klicken Sie auf dem Tab Projects (Projekte) neben Open (Öffnen) auf den Drop-down-Pfeil.
2. Klicken Sie auf Projekt vom Laufwerk hinzufügen.
3. Rufen Sie das Verzeichnis mit dem Code auf und klicken Sie dann auf OK.
4. Wählen Sie auf Aufforderung eine Version des Unity-Editors und Ihre Zielplattform (Android oder iOS) aus.
5. Klicken Sie auf den Projektnamen level-up-with-firebase. Das Projekt wird im Unity-Editor geöffnet.
6. Wenn der Editor es nicht automatisch öffnet, öffnen Sie MainGameScene im Unity-Editor auf dem Tab Project (Projekt) unter Assets > Hamster.
   

Weitere Informationen zur Installation und Verwendung von Unity finden Sie unter In Unity arbeiten.

3. Firebase zu Ihrem Unity-Projekt hinzufügen

Firebase-Projekt erstellen

1. Klicken Sie in der Firebase Console auf Projekt hinzufügen.
2. Geben Sie den gewünschten Projektnamen ein, um ein neues Projekt zu erstellen.
   Dadurch wird auch die Projekt-ID (unter dem Projektnamen angezeigt) auf einen Wert festgelegt, der auf dem Projektnamen basiert. Optional können Sie bei der Projekt-ID auf das Symbol Bearbeiten klicken, um sie weiter anzupassen.
3. Lesen Sie sich die Firebase-Nutzungsbedingungen durch und akzeptieren Sie sie.
4. Klicken Sie auf Weiter.
5. Wählen Sie die Option Google Analytics für dieses Projekt aktivieren aus und klicken Sie dann auf Weiter.
6. Wählen Sie ein vorhandenes Google Analytics-Konto aus oder klicken Sie auf Neues Konto erstellen, um ein neues Konto zu erstellen.
7. Klicken Sie auf Projekt erstellen.
8. Wenn das Projekt erstellt wurde, klicken Sie auf Weiter.

App bei Firebase registrieren

1. Klicken Sie in der Firebase Console in der Mitte der Projektübersichtsseite auf das Unity-Symbol, um den Einrichtungsworkflow zu starten. Wenn Sie Ihrem Firebase-Projekt bereits eine App hinzugefügt haben, klicken Sie auf App hinzufügen, um die Plattformoptionen aufzurufen.
2. Wählen Sie diese Option aus, um sowohl die Build-Ziele von Apple (iOS) als auch Android zu registrieren.
3. Geben Sie die plattformspezifischen IDs Ihres Unity-Projekts ein. Geben Sie für dieses Codelab Folgendes ein:
   • Für Apple (iOS): Geben Sie com.google.firebase.level-up in das Feld iOS-Bundle-ID ein.
   • Android: Geben Sie com.google.firebase.level_up in das Feld Android-Paketname ein.

   Wichtig: Die iOS-Bundle-ID und der Android-Paketname oben unterscheiden sich. Die iOS-ID ist für Android ungültig und umgekehrt. Achten Sie darauf, dass Sie die richtige Kennung verwenden.

4. Optional: Geben Sie die plattformspezifischen Aliasse Ihres Unity-Projekts ein.
5. Klicken Sie auf App registrieren und fahren Sie mit dem Abschnitt Konfigurationsdatei herunterladen fort.

Firebase-Konfigurationsdateien hinzufügen

Nachdem Sie auf App registrieren geklickt haben, werden Sie aufgefordert, zwei Konfigurationsdateien herunterzuladen (eine Konfigurationsdatei für jedes Build-Ziel). Ihr Unity-Projekt benötigt die Firebase-Metadaten in diesen Dateien, um eine Verbindung zu Firebase herzustellen.

1. Laden Sie die beiden verfügbaren Konfigurationsdateien herunter:
   • Für Apple (iOS): Lade GoogleService-Info.plist herunter.
   • Android: Laden Sie google-services.json herunter.
2. Öffnen Sie das Fenster Project (Projekt) Ihres Unity-Projekts und verschieben Sie beide Konfigurationsdateien in den Ordner Assets.

   Wichtig:Auch wenn Sie nur iOS oder Android entwickeln möchten, sollten Sie beide Dateien herunterladen und Ihrem Projekt hinzufügen.

3. Klicken Sie in der Firebase Console im Einrichtungsworkflow auf Weiter und fahren Sie mit „Firebase SDKs für Unity hinzufügen“ fort.

Hinweis:Sie können diese Dateien jederzeit noch einmal herunterladen. Öffnen Sie dazu die allgemeinen Einstellungen Ihres Projekts, scrollen Sie nach unten zum Abschnitt Meine Apps und klicken Sie auf die Schaltfläche zum Herunterladen der gewünschten Konfigurationsdatei.

Firebase SDKs für Unity hinzufügen

1. Klicken Sie in der Firebase Console auf Firebase Unity SDK herunterladen.

   Hinweis: Der Download dieses SDK kann einige Zeit dauern. Hol dir einen Kaffee oder Tee – trinke ausreichend, meine Freunde.

2. Entpacken Sie das SDK an einem für Sie geeigneten Ort.
3. Gehen Sie in Ihrem offenen Unity-Projekt zu Assets > Paket importieren > Benutzerdefiniertes Paket.
4. Rufen Sie im Dialogfeld Paket importieren das Verzeichnis auf, das das entpackte SDK enthält, wählen Sie FirebaseAnalytics.unitypackage aus und klicken Sie dann auf Öffnen.
5. Klicken Sie im Dialogfeld Import Unity Package (Unity-Paket importieren) auf Import (Importieren).
6. Wiederholen Sie die vorherigen Schritte, um FirebaseCrashlytics.unitypackage zu importieren.
7. Kehren Sie zur Firebase Console zurück und klicken Sie im Einrichtungsworkflow auf Weiter.

Weitere Informationen zum Hinzufügen von Firebase SDKs zu Unity-Projekten finden Sie unter Zusätzliche Unity-Installationsoptionen.

4. Crashlytics in Ihrem Unity-Projekt einrichten

Wenn Sie Crashlytics in Unity-Projekten verwenden möchten, sind einige weitere Einrichtungsschritte erforderlich. Natürlich müssen Sie das SDK initialisieren. Sie müssen jedoch auch Ihre Symbole hochladen, damit symbolisch dargestellte Stacktraces in der Firebase Console angezeigt werden. Außerdem müssen Sie einen Testabsturz erzwingen, um sicherzustellen, dass Firebase Ihre Absturzereignisse erhält.

Crashlytics SDK initialisieren

1. Fügen Sie in Assets/Hamster/Scripts/MainGame.cs die folgenden using-Anweisungen hinzu:

   using Firebase.Crashlytics;
   using Firebase.Extensions;
   

   Im ersten Modul können Sie Methoden aus dem Crashlytics SDK verwenden. Das zweite Modul enthält einige Erweiterungen der C# Tasks API. Ohne beide using-Anweisungen funktioniert der folgende Code nicht.
2. Fügen Sie in MainGame.cs der vorhandenen Start()-Methode die Firebase-Initialisierung hinzu, indem Sie InitializeFirebaseAndStartGame() aufrufen:

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

3. Suchen Sie auch hier in MainGame.cs nach InitializeFirebaseAndStartGame(), deklarieren Sie eine App-Variable und überschreiben Sie dann die Implementierung der Methode so:

   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");
         }
       });
   }
   

Wenn Sie die Initialisierungslogik hier platzieren, wird verhindert, dass Spieler mit dem Spiel interagieren, bevor die Firebase-Abhängigkeiten initialisiert wurden.

Die Vorteile und Auswirkungen der Meldung nicht abgefangener Ausnahmen als schwerwiegend werden in den häufig gestellten Fragen zu Crashlytics erläutert.

Projekt erstellen und Symbole hochladen

Hinweis:Führen Sie die Schritte in diesem Abschnitt aus, um Crashlytics einzurichten. Führen Sie diese Schritte in Zukunft jedes Mal aus, wenn Sie einen Release-Build oder einen Build erstellen, für den Sie symbolisch dargestellte Stacktraces in der Firebase Console (in diesem Codelab nach jedem Schritt) sehen möchten.

Die Schritte zum Erstellen und Hochladen von Symbolen unterscheiden sich für iOS- und Android-Apps.

iOS + (Apple-Plattform)

1. Exportieren Sie Ihr Projekt im Dialogfeld Build-Einstellungen in einen Xcode-Arbeitsbereich.
2. Erstellen Sie Ihre App.
    Auf Apple-Plattformen konfiguriert das Firebase Unity Editor-Plug-in Ihr Xcode-Projekt automatisch so, dass für jeden Build eine Crashlytics-kompatible Symboldatei generiert und auf die Firebase-Server hochgeladen wird. Diese Symbolinformationen sind erforderlich, um symbolisch dargestellte Stacktraces im Crashlytics-Dashboard anzusehen.

Android

1. (nur bei der Ersteinrichtung, nicht für jeden Build) Richten Sie Ihren Build ein:
   1. Erstellen Sie im Stammverzeichnis Ihres Projektverzeichnisses (d. h. als übergeordnetes Verzeichnis des Assets-Verzeichnisses) einen neuen Ordner mit dem Namen Builds und dann einen Unterordner mit dem Namen Android.
   2. Gehen Sie zu Datei > Build Settings > Player-Einstellungen > Configuration (Konfiguration): Setzen Sie das Skript-Back-End auf IL2CPP.
      • IL2CPP führt in der Regel zu kleineren Builds mit besserer Leistung.
      • IL2CPP ist außerdem die einzige verfügbare Option unter iOS. Wenn Sie diese Option hier auswählen, können die beiden Plattformen besser aufeinander abgestimmt sein und die Debugging-Unterschiede zwischen den beiden vereinfachen (falls Sie beide erstellen).
2. Erstellen Sie Ihre App. Führen Sie unter File > Build Settings die folgenden Schritte aus:
   1. Achten Sie darauf, dass bei Symbole.zip erstellen ein Häkchen gesetzt ist. Falls ein Drop-down-Menü zu sehen ist, wählen Sie Debugging aus.
   2. Erstellen Sie Ihr APK direkt über den Unity Editor in den soeben erstellten Unterordner Builds/Android.
3. Sobald Ihr Build fertig ist, müssen Sie eine Crashlytics-kompatible Symboldatei generieren und auf die Firebase-Server hochladen. Diese Symbolinformationen sind erforderlich, um symbolisch dargestellte Stacktraces für Abstürze nativer Bibliotheken im Crashlytics-Dashboard anzusehen.
   
   Führen Sie den folgenden Firebase CLI-Befehl aus, um diese Symboldatei zu generieren und hochzuladen:

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

   • FIREBASE_APP_ID: Ihre Firebase-Android-App-ID (nicht Ihr Paketname). Suchen Sie diesen Wert in der Datei google-services.json, die Sie zuvor heruntergeladen haben. Das ist der Wert mobilesdk_app_id.
     Beispiel für eine Firebase-Android-App-ID: 1:567383003300:android:17104a2ced0c9b9b
   • PATH/TO/SYMBOLS: Der Pfad der gezippten Symboldatei, die im Verzeichnis Builds/Android generiert wurde, als der Build abgeschlossen wurde (z. B. Builds/Android/myapp-1.0-v100.symbols.zip).

     Hinweis:Dieser Dateiname ändert sich, da im Projekt verschiedene Nummern für Version und Bundle Version Code festgelegt sind. Diese finden Sie unter Datei > Build Settings > Player-Einstellungen > Identifikation:

Testabsturz erzwingen, um die Einrichtung abzuschließen

Um die Einrichtung von Crashlytics abzuschließen und erste Daten im Crashlytics-Dashboard der Firebase Console zu sehen, müssen Sie einen Testabsturz erzwingen.

1. Suchen Sie in MainGameScene das EmptyObjectGameObject in der Hierarchy des Editors, fügen Sie das folgende Skript hinzu und speichern Sie die Szene. Dieses Skript löst einige Sekunden nach der Ausführung der App einen Testabsturz aus.

   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. Erstellen Sie Ihre App und laden Sie Symbolinformationen hoch, nachdem der Build fertiggestellt ist.
   • iOS: Das Firebase Unity-Editor-Plug-in konfiguriert Ihr Xcode-Projekt automatisch für den Upload Ihrer Symboldatei.
   • Android: Führen Sie den Firebase CLI-Befehl crashlytics:symbols:upload aus, um Ihre Symboldatei hochzuladen.

   Hinweis: Wenn Sie zum ersten Mal einen Build für ein bestimmtes mobiles Ziel erstellen, kann diese Erstellungszeit einige Minuten dauern. Weitere Builds werden wesentlich schneller ausgeführt.

3. Führen Sie die App aus. Beobachten Sie das Geräteprotokoll und warten Sie, bis die Ausnahme durch die CrashlyticsTester ausgelöst wird.
   • iOS: Sehen Sie sich Protokolle im unteren Bereich von Xcode an.
   • Android: Führen Sie den folgenden Befehl im Terminal aus, um Logs aufzurufen: adb logcat.
4. Rufen Sie das Crashlytics-Dashboard auf, um die Ausnahme anzusehen. Sie finden sie in der Tabelle Probleme unten im Dashboard. Später im Codelab erfahren Sie mehr darüber, wie Sie diese Berichte analysieren.
5. Sobald Sie bestätigt haben, dass das Ereignis in Crashlytics hochgeladen wurde, wählen Sie das EmptyObject GameObject aus, an das es angehängt ist, entfernen Sie nur die Komponente CrashlyticsTester und speichern Sie die Szene, um ihren ursprünglichen Zustand wiederherzustellen.

5. Debug-Menü aktivieren und verwenden

Bisher haben Sie Crashlytics Ihrem Unity-Projekt hinzugefügt, die Einrichtung abgeschlossen und bestätigt, dass das Crashlytics SDK Ereignisse in Firebase hochlädt. Jetzt erstellen Sie in Ihrem Unity-Projekt ein Menü, in dem Sie sehen, wie Sie die erweiterten Crashlytics-Funktionen in Ihrem Spiel nutzen können. Das Unity-Projekt Level Up with Firebase enthält bereits ein ausgeblendetes Debug-Menü, das Sie sichtbar machen und für das Sie die Funktionalität schreiben.

Menü „Fehlerbehebung“ aktivieren

Die Schaltfläche für den Zugriff auf das Menü zur Fehlerbehebung gibt es in Ihrem Unity-Projekt, ist aber derzeit nicht aktiviert. Sie müssen die Schaltfläche aktivieren, um über das MainMenu-Prefab darauf zuzugreifen:

1. Öffnen Sie im Unity-Editor das Prefab mit dem Namen MainMenu..
2. Suchen Sie in der Fertigungshierarchie das deaktivierte Unterobjekt DebugMenuButton und wählen Sie es dann aus.
3. Aktivieren Sie das DebugMenuButton, indem Sie das Kästchen oben links neben dem Textfeld mit dem DebugMenuButton anklicken.
4. Speichern Sie die Fertigung.
5. Führen Sie das Spiel entweder im Editor oder auf Ihrem Gerät aus. Das Menü sollte jetzt zugänglich sein.

Wichtig: Da die Absturzmethoden derzeit nicht implementiert sind, wird beim Tippen auf die entsprechenden Schaltflächen eine System.NotImplementedException ausgegeben und es passiert sonst nichts.

Methodeinträge für das Debug-Menü in der Vorschau ansehen und verstehen

Später in diesem Codelab schreiben Sie Methodenkörper für einige vorkonfigurierte Crashlytics-Debugmethoden. Im Unity-Projekt Level Up with Firebase werden die Methoden jedoch im DebugMenu.cs definiert und aufgerufen.

Einige dieser Methoden rufen Crashlytics-Methoden auf und lösen Fehler aus. Ob Crashlytics diese Fehler jedoch abfangen kann, hängt nicht davon ab, ob diese Methoden zuerst aufgerufen werden. Vielmehr werden die durch das automatische Abfangen von Fehlern generierten Absturzberichte durch die mit diesen Methoden hinzugefügten Informationen verbessert.

Öffnen Sie DebugMenu.cs und suchen Sie nach den folgenden Methoden:

Methoden zum Generieren und Kommentieren von Crashlytics-Problemen:

• CrashNow
• LogNonfatalError
• LogStringsAndCrashNow
• SetAndOverwriteCustomKeyThenCrash
• SetLogsAndKeysBeforeANR

Methoden zum Logging von Analytics-Ereignissen zur Unterstützung der Fehlerbehebung:

• LogProgressEventWithStringLiterals
• LogIntScoreWithBuiltInEventAndParams

In den späteren Schritten dieses Codelabs implementieren Sie diese Methoden und erfahren, wie Sie damit bestimmte Situationen in der Spieleentwicklung angehen können.

6. Bereitstellung von Absturzberichten in der Entwicklung sicherstellen

Bevor Sie diese Debug-Methoden implementieren und sehen, wie sie sich auf Absturzberichte auswirken, sollten Sie wissen, wie Ereignisse an Crashlytics gesendet werden.

Bei Unity-Projekten werden Absturz- und Ausnahmeereignisse in Ihrem Spiel sofort auf die Festplatte geschrieben. Nicht erfasste Ausnahmen, die Ihr Spiel nicht zum Absturz bringen (z. B. nicht abgefangene C#-Ausnahmen in der Spiellogik), können vom Crashlytics SDK als schwerwiegende Ereignisse gemeldet werden. Setzen Sie dazu die Crashlytics.ReportUncaughtExceptionsAsFatal-Eigenschaft auf true, um Crashlytics in Ihrem Unity-Projekt zu initialisieren. Diese Ereignisse werden in Echtzeit an Crashlytics gemeldet, ohne dass der Endnutzer das Spiel neu starten muss. Hinweis: Native Abstürze werden immer als fatale Ereignisse gemeldet und gesendet, wenn ein Endnutzer das Spiel neu startet.

Hinweis:Wenn Sie nicht abgefangene Ausnahmen als schwerwiegende Ereignisse melden möchten, muss Ihr Unity-Projekt das Firebase Crashlytics Unity SDK 10.4.0 oder höher verwenden.

Beachten Sie außerdem die folgenden kleinen, aber wichtigen Unterschiede zwischen den verschiedenen Laufzeitumgebungen beim Senden von Crashlytics-Informationen an Firebase:

iOS-Simulator:

• Crashlytics-Informationen werden nur dann erfasst, wenn Sie Xcode vom Simulator trennen. Wenn Xcode angehängt ist, werden die Fehler vorgelagert, wodurch die Übermittlung von Informationen verhindert wird.

Physische Mobilgeräte (Android und iOS):

• Android-spezifisch: ANRs werden nur unter Android 11 und höher erfasst. ANRs und nicht schwerwiegende Ereignisse werden bei der nächsten Ausführung erfasst.

Unity-Editor:

• Crashlytics-Informationen aus dem Editor im Play-Modus oder im eigenständigen Modus werden NICHT aufgezeichnet oder in Firebase hochgeladen. Außerdem wird Crashlytics vom Entwicklungsworkflow für Firebase Desktop nicht unterstützt.

In CrashNow() können Sie mit nur einem Tastendruck testen, ob Ihr Spiel abstürzt

Nachdem Crashlytics in Ihrem Spiel eingerichtet wurde, zeichnet das Crashlytics SDK Abstürze und nicht abgefangene Ausnahmen automatisch auf und lädt sie zur Analyse in Firebase hoch. Die Berichte werden im Crashlytics-Dashboard der Firebase Console angezeigt.

1. Um zu zeigen, dass dies tatsächlich automatisch geschieht, öffnen Sie DebugMenu.cs und überschreiben Sie die Methode CrashNow() so:

   void CrashNow()
   {
       TestCrash();
   }
   

2. Erstellen Sie Ihre App.
3. (Nur Android) Laden Sie Ihre Symbole mit dem folgenden Firebase CLI-Befehl hoch:

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

4. Tippen Sie auf die Schaltfläche Jetzt abstürzen und fahren Sie mit dem nächsten Schritt dieses Codelabs fort, um zu erfahren, wie Sie den Absturzbericht aufrufen und interpretieren.

7. Problemberichte in der Firebase Console

Wenn es um die Anzeige von Absturzberichten geht, müssen Sie noch ein paar Dinge wissen, um sie optimal zu nutzen. Jede der Methoden, die Sie schreiben, zeigt, wie Sie unterschiedliche Arten von Informationen zu Crashlytics-Berichten hinzufügen können.

1. Tippen Sie auf die Schaltfläche Jetzt absturz und starten Sie die App neu.
2. Rufen Sie das Crashlytics-Dashboard auf. Scrollen Sie nach unten zur Tabelle Probleme am Ende des Dashboards. Dort sind Ereignisse, die alle dieselbe Ursache haben, in „Probleme“ gruppiert.
3. Klicken Sie auf das neue Problem, das in der Tabelle Probleme aufgeführt ist. Daraufhin wird die Ereignisübersicht für jedes einzelne Ereignis angezeigt, das an Firebase gesendet wurde.
   
   Die Ausgabe sollte in etwa so aussehen: In der Ereignisübersicht ist der Stack-Trace des Aufrufs, der zum Absturz geführt hat, gut sichtbar.

Zusätzliche Metadaten

Ein weiterer hilfreicher Tab ist der Unity-Metadaten. In diesem Abschnitt finden Sie Informationen zu den Attributen des Geräts, auf dem das Ereignis aufgetreten ist, einschließlich physischer Merkmale, des CPU-Modells und -Spezifikationen sowie aller möglichen GPU-Messwerte.

Die Informationen auf diesem Tab können in diesem Beispiel hilfreich sein:
Stell dir vor, dein Spiel nutzt intensiv Shader, um ein bestimmtes Erscheinungsbild zu erreichen, aber nicht alle Smartphones haben GPUs, die diese Funktion rendern können. Anhand der Informationen auf dem Tab Unity-Metadaten können Sie besser nachvollziehen, auf welche Hardware Ihre App prüfen sollte, wenn Sie entscheiden, welche Funktionen automatisch verfügbar gemacht oder vollständig deaktiviert werden sollen.

Fehler oder Abstürze können auf deinem Gerät unter Umständen nie auftreten. Aufgrund der riesigen Vielfalt an Android-Geräten ist es aber hilfreich, die jeweiligen Hotspots besser zu verstehen. der Geräte Ihrer Zielgruppe.

8. Ausnahmen auslösen, abfangen und protokollieren

Auch wenn Ihr Code eine Laufzeitausnahme korrekt abfängt und verarbeitet, ist es oft sinnvoll, als Entwickler zu notieren, dass sie aufgetreten ist und unter welchen Umständen. Crashlytics.LogException kann genau zu diesem Zweck verwendet werden, um ein Ausnahmeereignis an Firebase zu senden, damit Sie das Problem in der Firebase Console weiter beheben können.

1. Fügen Sie in Assets/Hamster/Scripts/States/DebugMenu.cs den using-Anweisungen Folgendes an:

   // Import Firebase
   using Firebase.Crashlytics;
   

2. Überschreiben Sie LogNonfatalError() in DebugMenu.cs so:

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

3. Erstellen Sie Ihre App.
4. (Nur Android) Laden Sie Ihre Symbole mit dem folgenden Firebase CLI-Befehl hoch:

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

5. Tippen Sie auf die Schaltfläche Nicht schwerwiegenden Fehler protokollieren und starten Sie die App neu.
6. Rufen Sie das Crashlytics-Dashboard auf. Es sollte etwas Ähnliches sehen, das Sie im letzten Schritt dieses Codelabs gesehen haben.
7. Beschränken Sie den Filter Ereignistyp diesmal jedoch auf Nicht kritisch, damit nur nicht kritische Fehler angezeigt werden, z. B. der, den Sie gerade protokolliert haben.
   

9. Strings in Crashlytics protokollieren, um den Ablauf der Programmausführung besser zu verstehen

Haben Sie schon einmal versucht herauszufinden, warum eine Codezeile, die aus mehreren Pfaden aufgerufen wird, hunderte oder tausende Male pro Sitzung, plötzlich eine Ausnahme oder einen Absturz verursachen kann? Es kann zwar hilfreich sein, den Code in einer IDE durchzugehen und sich die Werte genauer anzusehen, aber was ist, wenn das nur bei einem verschwindend kleinen Prozentsatz Ihrer Nutzer passiert? Noch schlimmer: Was würden Sie tun, wenn Sie diesen Absturz nicht reproduzieren können, unabhängig davon, was Sie tun?

In Situationen wie diesen kann ein gewisser Kontext einen großen Unterschied ausmachen. Mit Crashlytics.Log können Sie den erforderlichen Kontext formulieren. Betrachten Sie diese Nachrichten als Hinweise für Ihr zukünftiges Ich, was möglicherweise passiert.

Protokolle können auf vielfältige Weise verwendet werden, sind aber in der Regel am hilfreichsten, um Situationen aufzuzeichnen, in denen die Reihenfolge und/oder das Fehlen von Aufrufen eine wichtige Information ist.

1. Überschreiben Sie LogStringsAndCrashNow() in Assets/Hamster/Scripts/States/DebugMenu.cs so:

   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. Erstellen Sie Ihre App.
3. (Nur Android) Laden Sie Ihre Symbole mit dem folgenden Firebase CLI-Befehl hoch:

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

4. Tippen Sie auf die Schaltfläche Strings protokollieren und jetzt abstürzen und starten Sie dann die App neu.
5. Kehren Sie zum Crashlytics-Dashboard zurück und klicken Sie in der Tabelle Probleme auf die neueste Ausgabe. Auch hier sollte etwas Ähnliches wie bei den vorhergehenden Problemen angezeigt werden.
   
6. Wenn Sie jedoch in einer Ereigniszusammenfassung auf den Tab Protokolle klicken, wird eine Ansicht wie diese angezeigt:
   

Hinweis: Diese Protokolle sind nicht nur wegen der Meldungen, sondern auch wegen der Zeitstempel nützlich. Anhand dieser Zeitstempel können Sie die Reihenfolge nachvollziehen, in der sie generiert wurden.

Wichtig: Um eine Verlangsamung Ihrer App zu vermeiden, begrenzt Crashlytics Protokolle auf 64 KB und löscht ältere Protokolleinträge, wenn das Protokoll einer Sitzung dieses Limit überschreitet.

10. Benutzerdefinierten Schlüssel schreiben und überschreiben

Angenommen, Sie möchten einen Absturz besser nachvollziehen, der mit Variablen zusammenhängt, die auf eine kleine Anzahl von Werten oder Konfigurationen festgelegt sind. Es könnte hilfreich sein, die Möglichkeit zu haben, auf der Grundlage der Kombination von Variablen und möglichen Werten, die Sie sich gerade ansehen, zu einem bestimmten Zeitpunkt zu filtern.

Neben der Protokollierung beliebiger Strings bietet Crashlytics eine weitere Form der Fehlerbehebung, wenn es von Vorteil ist, den genauen Status Ihres Programms nach dem Absturz zu kennen: benutzerdefinierte Schlüssel.

Dies sind Schlüssel/Wert-Paare, die Sie für eine Sitzung festlegen können. Im Gegensatz zu Protokollen, die angesammelt werden und rein additiv sind, können Schlüssel überschrieben werden, um nur den neuesten Status einer Variablen oder Bedingung wiederzugeben.

Diese Schlüssel sind nicht nur ein Verzeichnis des letzten aufgezeichneten Zustands Ihres Programms, sondern können auch als leistungsstarke Filter für Crashlytics-Probleme verwendet werden.

1. Überschreiben Sie in Assets/Hamster/Scripts/States/DebugMenu.cs SetAndOverwriteCustomKeyThenCrash() so:

   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. Erstellen Sie Ihre App.
3. (Nur Android) Laden Sie Ihre Symbole mit dem folgenden Firebase CLI-Befehl hoch:

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

4. Tippen Sie auf die Schaltfläche Benutzerdefinierten Schlüssel und Absturz festlegen und starten Sie die App neu.
5. Kehren Sie zum Crashlytics-Dashboard zurück und klicken Sie in der Tabelle Probleme auf die neueste Ausgabe. Auch hier sollten Sie etwas Ähnliches sehen wie die vorherigen Probleme.
6. Dieses Mal klicken Sie jedoch in der Ereigniszusammenfassung auf den Tab Schlüssel, um den Wert der Schlüssel zu sehen, darunter Current Time:
   

   Wichtig: Der Schlüssel von crash_info_entry_0 wird nur dann automatisch von Crashlytics ausgefüllt, wenn Ihre App vom iOS-Simulator ausgeführt wird.

Warum sollten Sie benutzerdefinierte Schlüssel anstelle von benutzerdefinierten Logs verwenden?

• Logs eignen sich gut zum Speichern sequenzieller Daten. Benutzerdefinierte Schlüssel sind jedoch besser, wenn Sie nur den neuesten Wert verwenden möchten.
• In der Firebase Console können Sie Probleme ganz einfach anhand der Schlüsselwerte im Suchfeld der Tabelle Probleme filtern.

Ähnlich wie bei Logs haben benutzerdefinierte Schlüssel jedoch ein Limit. Crashlytics unterstützt maximal 64 Schlüssel/Wert-Paare. Wenn Sie diesen Grenzwert erreichen, werden keine weiteren Werte gespeichert. Jedes Schlüssel/Wert-Paar kann eine Größe von bis zu 1 KB haben.

11. (Nur Android) Benutzerdefinierte Schlüssel und Protokolle verwenden, um eine ANR zu analysieren und zu diagnostizieren

Wichtig: Die folgende Art von Problem betrifft hauptsächlich Android 11 und höher. Wenn dies nicht zu Ihrem Anwendungsfall für die Entwicklung passt, überspringen Sie diesen Abschnitt.

Eine der schwierigsten Probleme beim Beheben von Problemen für Android-Entwickler ist der ANR-Fehler Application Not Responding. ANR-Fehler treten auf, wenn eine App länger als 5 Sekunden nicht auf Eingaben reagiert. Wenn dies geschieht, ist die App entweder eingefroren oder wird sehr langsam ausgeführt. Den Nutzern wird ein Dialogfeld angezeigt, in dem sie zwischen „Warten“ und „App schließen“ wählen können.

ANR-Fehler verursachen eine negative Nutzererfahrung und können – wie oben unter dem ANR-Link erwähnt – die Sichtbarkeit Ihrer App im Google Play Store beeinträchtigen. Aufgrund ihrer Komplexität und weil sie oft durch Multithread-Code mit stark unterschiedlichem Verhalten auf verschiedenen Smartphone-Modellen verursacht werden, ist es oft sehr schwierig, wenn nicht nahezu unmöglich, ANRs beim Debuggen zu reproduzieren. Daher ist es in der Regel am besten, sie analytisch und deduktiv anzugehen.

Bei dieser Methode verwenden wir eine Kombination aus Crashlytics.LogException, Crashlytics.Log und Crashlytics.SetCustomKey, um die automatische Fehlerprotokollierung zu ergänzen und mehr Informationen zu erhalten.

Wichtig: Der blockierende Code wird im UI-Thread von UnityPlayerActivity ausgeführt. Dies ist in Unity etwas unnatürlich, da der Thread nicht mit dem Unity-Hauptthread identisch ist, wo standardmäßig Spielcode ausgeführt wird. ANRs können besonders schwierig zu beheben sein, da sie durch Plug-ins oder anderen Code verursacht werden können, der nicht idiomatisch im UI-Thread ausgeführt wird.

1. Überschreiben Sie in Assets/Hamster/Scripts/States/DebugMenu.cs SetLogsAndKeysBeforeANR() so:

   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. Erstellen Sie Ihre App.
3. Führen Sie den folgenden Firebase CLI-Befehl aus, um Ihre Symbole hochzuladen:

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

4. Tippen Sie auf die Schaltfläche Protokolle und Schlüssel festlegen → ANR und starten Sie dann Ihre App neu.
5. Gehen Sie zurück zum Crashlytics-Dashboard und klicken Sie in der Tabelle Probleme auf das neue Problem, um die Ereigniszusammenfassung aufzurufen. Wenn der Anruf wie gewünscht funktioniert hat, sollten Sie in etwa Folgendes sehen:
   
   
   Wie Sie sehen, hat Firebase die lange Wartezeit im Thread als Hauptgrund für einen ANR-Fehler erkannt.
   
6. Wenn Sie sich die Protokolle auf dem Tab Protokolle der Ereigniszusammenfassung ansehen, sehen Sie, dass die letzte Methode, die als abgeschlossen erfasst wurde, DoSevereWork ist.
   
   
   Die letzte Methode, die als gestartet aufgeführt ist, ist dagegen DoExtremeWork. Das bedeutet, dass die ANR während dieser Methode aufgetreten ist und das Spiel geschlossen wurde, bevor DoExtremeWork protokolliert werden konnte.
   
   

Wichtig: Wenn Sie unter Android keinen ANR-Fehler sehen und stattdessen eine Fehlermeldung mit dem Hinweis InvalidOperationException angezeigt wird, lesen Sie die Protokolle. Dieser benutzerdefinierte Fehler ist in diesem Codelab enthalten. Folgen Sie der von der Ausnahme protokollierten Anleitung, um das Problem zu beheben. Erstellen Sie die App neu, stellen Sie sie bereit und iterieren Sie, bis Sie den gewünschten Fehler erhalten.

Was spricht dafür?

• Das Reproduzieren von ANR-Fehlern ist extrem schwierig. Daher ist es äußerst wichtig, umfassende Informationen zum Codebereich und zu Messwerten zu erhalten, um diese deduktiv zu ermitteln.
• Dank der gespeicherten Informationen in den benutzerdefinierten Schlüsseln wissen Sie jetzt, welcher asynchrone Thread am längsten gedauert hat und bei welchem Threads möglicherweise ANR-Fehler ausgelöst wurden. Diese Art verwandter logischer und numerischer Daten zeigt Ihnen, an welcher Stelle im Code die Optimierung am wichtigsten ist.

12. Analytics-Ereignisse einfügen, um Berichte weiter zu ergänzen

Die folgenden Methoden können auch über das Menü zur Fehlerbehebung aufgerufen werden. Statt selbst Probleme zu generieren, wird Google Analytics als zusätzliche Informationsquelle verwendet, um die Funktionsweise Ihres Spiels besser zu verstehen.

Im Gegensatz zu den anderen Methoden, die Sie in diesem Codelab geschrieben haben, sollten Sie diese Methoden in Kombination mit den anderen verwenden. Rufen Sie diese Methoden in beliebiger Reihenfolge auf (durch Drücken der entsprechenden Schaltfläche im Menü zur Fehlerbehebung), bevor Sie eine der anderen Methoden ausführen. Wenn Sie sich dann die Informationen im jeweiligen Crashlytics-Problem ansehen, finden Sie ein geordnetes Protokoll der Analytics-Ereignisse. Diese Daten können in einem Spiel verwendet werden, um eine Kombination aus Programmablauf oder Nutzereingaben besser zu verstehen, je nachdem, wie Sie Ihre App instrumentiert haben.

Hinweis: Die folgenden Anwendungsfälle für Analytics sind recht einfach. Die Details zu Analytics werden in diesem Codelab nicht behandelt. Weitere Informationen dazu, was genau mit diesen Ereignissen erfasst wird, und wie Sie den Berichtsvorgang beheben können, finden Sie im Hilfeartikel Einstieg in Google Analytics for Unity.

1. Überschreiben Sie in Assets/Hamster/Scripts/States/DebugMenu.cs die vorhandenen Implementierungen der folgenden Methoden:

   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. Erstellen und stellen Sie Ihr Spiel bereit und rufen Sie dann das Debug-Menü auf.
3. (Nur Android) Laden Sie Ihre Symbole mit dem folgenden Firebase CLI-Befehl hoch:

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

4. Drücke mindestens einmal oder mehrmals eine der folgenden Tasten, um die oben genannten Funktionen aufzurufen:
   • Protokollstringereignis
   • Log-In-Ereignis
5. Klicken Sie auf die Schaltfläche Jetzt absturz.
6. Starte das Spiel neu, damit das Absturzereignis in Firebase hochgeladen wird.
7. Wenn Sie verschiedene beliebige Sequenzen von Analytics-Ereignissen protokollieren und Ihr Spiel dann ein Ereignis generieren soll, für das Crashlytics einen Bericht erstellt (wie Sie gerade), werden sie dem Tab Protokolle der Ereigniszusammenfassung in Crashlytics hinzugefügt:
   

Wichtig: Es kann länger dauern, bis benutzerdefinierte Ereignisse im Analytics-Dashboard in der Firebase Console angezeigt werden, als bis sie in einem Absturzprotokoll im Crashlytics-Dashboard erscheinen. Außerdem werden Analytics-Ereignisse möglicherweise nicht sofort an beiden Stellen angezeigt, nachdem Sie sie protokolliert haben.

13. Künftig

So sollten Sie eine bessere theoretische Grundlage haben, auf der Sie Ihre automatisch generierten Absturzberichte ergänzen können. Anhand dieser neuen Informationen können Sie den aktuellen Status, Daten zu vergangenen Ereignissen und vorhandene Google Analytics-Ereignisse verwenden, um die Abfolge der Ereignisse und die Logik, die zu dem Ergebnis geführt haben, besser zu analysieren.

Wenn Ihre App auf Android 11 (API-Level 30) oder höher ausgerichtet ist, sollten Sie GWP-ASan integrieren. Dies ist eine Funktion zur nativen Arbeitsspeicherzuweisung, die sich zum Beheben von Abstürzen eignet, die durch Fehler im nativen Arbeitsspeicher wie use-after-free- und heap-buffer-overflow-Fehler verursacht werden. Wenn Sie diese Debugging-Funktion nutzen möchten, müssen Sie GWP-ASan explizit aktivieren.

Nächste Schritte

Fahren Sie mit dem Codelab Ihr Unity-Spiel mit Remote Config instrumentieren fort. Dort erfahren Sie mehr über die Verwendung von Remote Config und A/B Testing in Unity.