Verstehen Sie die Abstürze eines Unity-Spiels mithilfe der erweiterten Crashlytics-Funktionen

1. Einleitung

In diesem Codelab erfahren Sie, wie Sie die erweiterten Funktionen von Crashlytics nutzen, um einen besseren Einblick in Abstürze und die Umstände zu erhalten, die sie möglicherweise verursacht haben.

Sie werden einem 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, das die meisten seiner integrierten Firebase-Funktionen entfernt und Ihnen die Möglichkeit gibt, stattdessen neue Verwendungsmöglichkeiten von Firebase zu implementieren.

Sie fügen dem Spiel ein Debug-Menü hinzu. Dieses Debug-Menü ruft die von Ihnen erstellten Methoden auf und ermöglicht Ihnen die Ausübung der verschiedenen Funktionalitäten von Crashlytics. Diese Methoden zeigen Ihnen, wie Sie Ihre automatischen Absturzberichte mit benutzerdefinierten Schlüsseln, benutzerdefinierten Protokollen, nicht schwerwiegenden Fehlern und mehr kommentieren.

Nachdem Sie das Spiel erstellt haben, verwenden Sie das Debug-Menü und prüfen die Ergebnisse, um zu verstehen, welch einzigartige Sicht sie auf die Funktionsweise Ihres Spiels in der freien Natur bieten.

Was Sie lernen werden

  • Die Arten von Fehlern, die Crashlytics automatisch erkennt.
  • Zusätzliche Fehler, die gezielt erfasst werden können.
  • So fügen Sie diesen Fehlern weitere Informationen hinzu, um sie leichter verständlich zu machen.

Was du brauchen wirst

  • Unity (empfohlene Mindestversion 2019+) mit einem oder beiden der folgenden Elemente:
    • iOS-Build-Unterstützung
    • Android-Build-Unterstützung
  • (Nur für Android) Die Firebase-CLI (wird zum Hochladen von Symbolen für Absturzberichte verwendet)

2. Richten Sie Ihre Entwicklungsumgebung ein

In den folgenden Abschnitten wird beschrieben, wie Sie den Level Up with Firebase- Code herunterladen und in Unity öffnen.

Beachten Sie, dass dieses Beispielspiel „Level Up with Firebase“ von mehreren anderen Firebase + Unity-Codelabs verwendet wird, sodass Sie die Aufgaben in diesem Abschnitt möglicherweise bereits abgeschlossen haben. Wenn ja, können Sie direkt zum letzten Schritt auf dieser Seite gehen: „Firebase SDKs für Unity hinzufügen“.

Laden Sie den Code herunter

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

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

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

Öffnen Sie Level Up mit Firebase im Unity-Editor

  1. Starten Sie den Unity Hub und klicken Sie auf der Registerkarte „Projekte“ auf den Dropdown-Pfeil neben „Öffnen“ .
  2. Klicken Sie auf Projekt von Datenträger hinzufügen .
  3. Navigieren Sie zu dem Verzeichnis, das den Code enthält, und klicken Sie dann auf OK .
  4. Wenn Sie dazu aufgefordert werden, wählen Sie eine zu verwendende Unity-Editor-Version und Ihre Zielplattform (Android oder iOS) aus.
  5. Klicken Sie auf den Projektnamen „ level-upwith-firebase“ und das Projekt wird im Unity-Editor geöffnet.
  6. Wenn Ihr Editor es nicht automatisch öffnet, öffnen Sie MainGameScene unter Assets > Hamster auf der Registerkarte „ Projekt“ des Unity-Editors.
    ff4ea3f3c0d29379.png

Weitere Informationen zur Installation und Verwendung von Unity finden Sie unter Arbeiten in Unity .

3. Fügen Sie Firebase zu Ihrem Unity-Projekt hinzu

Erstellen Sie ein Firebase-Projekt

  1. Klicken Sie in der Firebase-Konsole auf Projekt hinzufügen .
  2. Um ein neues Projekt zu erstellen, geben Sie den gewünschten Projektnamen ein.
    Dadurch wird auch die Projekt-ID (die unter dem Projektnamen angezeigt wird) auf etwas basierend auf dem Projektnamen festgelegt. Sie können optional auf das Bearbeitungssymbol der Projekt-ID klicken, um sie weiter anzupassen.
  3. Wenn Sie dazu aufgefordert werden, lesen Sie die Firebase-Bedingungen durch und akzeptieren Sie sie.
  4. Klicken Sie auf Weiter .
  5. Wählen Sie die Option „Google Analytics für dieses Projekt aktivieren“ und klicken Sie dann auf „Weiter“ .
  6. Wählen Sie ein vorhandenes Google Analytics-Konto aus, das Sie verwenden möchten, oder wählen Sie „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 .

Registrieren Sie Ihre App bei Firebase

  1. Klicken Sie immer noch in der Firebase-Konsole in der Mitte der Projektübersichtsseite auf das Unity-Symbol, um den Setup-Workflow zu starten. Wenn Sie Ihrem Firebase-Projekt bereits eine App hinzugefügt haben, klicken Sie auf App hinzufügen , um die Plattformoptionen anzuzeigen.
  2. Wählen Sie diese Option aus, um sowohl die Build-Ziele Apple (iOS) als auch Android zu registrieren.
  3. Geben Sie die plattformspezifischen ID(s) 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.
    • Für Android : Geben Sie com.google.firebase.level_up in das Feld „Android-Paketname“ ein.
  4. (Optional) Geben Sie die plattformspezifischen Spitznamen Ihres Unity-Projekts ein.
  5. Klicken Sie auf App registrieren und fahren Sie dann mit dem Abschnitt Konfigurationsdatei herunterladen fort.

Fügen Sie Firebase-Konfigurationsdateien hinzu

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 mit Firebase herzustellen.

  1. Laden Sie beide verfügbaren Konfigurationsdateien herunter:
    • Für Apple (iOS) : Laden Sie GoogleService-Info.plist herunter.
    • Für Android : Laden Sie google-services.json herunter.
  2. Öffnen Sie das Projektfenster Ihres Unity-Projekts und verschieben Sie dann beide Konfigurationsdateien in den Ordner „Assets“ .
  3. Klicken Sie zurück in der Firebase-Konsole im Setup-Workflow auf Weiter und fahren Sie mit Firebase SDKs für Unity hinzufügen fort.

Fügen Sie Firebase SDKs für Unity hinzu

  1. Klicken Sie in der Firebase-Konsole auf Firebase Unity SDK herunterladen .
  2. Entpacken Sie das SDK an einem geeigneten Ort.
  3. Navigieren Sie in Ihrem geöffneten Unity-Projekt zu Assets > Paket importieren > Benutzerdefiniertes Paket .
  4. Navigieren Sie im Dialogfeld „Paket importieren“ zu dem Verzeichnis, das das entpackte SDK enthält, wählen Sie FirebaseAnalytics.unitypackage aus und klicken Sie dann auf „Öffnen“ .
  5. Klicken Sie im angezeigten Dialogfeld „Unity-Paket importieren“ auf „Importieren“ .
  6. Wiederholen Sie die vorherigen Schritte, um FirebaseCrashlytics.unitypackage zu importieren.
  7. Kehren Sie zur Firebase-Konsole zurück und klicken Sie im Setup-Workflow auf Weiter .

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

4. Richten Sie Crashlytics in Ihrem Unity-Projekt ein

Um Crashlytics in Unity-Projekten verwenden zu können, müssen Sie einige weitere Einrichtungsschritte durchführen. Natürlich müssen Sie das SDK initialisieren. Sie müssen aber auch Ihre Symbole hochladen, damit Sie symbolisierte Stacktraces in der Firebase-Konsole sehen können, und Sie müssen einen Testabsturz erzwingen, um sicherzustellen, dass Firebase Ihre Absturzereignisse erhält.

Initialisieren Sie das Crashlytics SDK

  1. Fügen Sie in Assets/Hamster/Scripts/MainGame.cs die folgenden using Anweisungen hinzu:
    using Firebase.Crashlytics;
using Firebase.Extensions;
    Das erste Modul ermöglicht Ihnen die Verwendung von Methoden aus dem Crashlytics SDK und das zweite enthält einige Erweiterungen der C#-Aufgaben-API . Ohne beide using Anweisungen funktioniert der folgende Code nicht.
  2. Fügen Sie in MainGame.cs die Firebase-Initialisierung zur vorhandenen Start() Methode hinzu, indem Sie InitializeFirebaseAndStartGame() :
    void Start()
{
  Screen.SetResolution(Screen.width / 2, Screen.height / 2, true);
  InitializeFirebaseAndStartGame();
}
    aufrufen
  3. Und noch einmal: Suchen Sie in MainGame.cs nach InitializeFirebaseAndStartGame() , deklarieren Sie eine App-Variable und überschreiben Sie dann die Implementierung der Methode wie folgt:
    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");
      }
    });
}

Durch die Platzierung der Initialisierungslogik an dieser Stelle wird die Spielerinteraktion verhindert, bevor die Firebase-Abhängigkeiten initialisiert werden.

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

Erstellen Sie Ihr Projekt und laden Sie Symbole hoch

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.
    Für Apple-Plattformen konfiguriert das Firebase Unity Editor-Plugin Ihr Xcode-Projekt automatisch so, dass für jeden Build eine Crashlytics-kompatible Symboldatei generiert und auf Firebase-Server hochgeladen wird. Diese Symbolinformationen sind erforderlich, um symbolisierte Stack-Traces im Crashlytics-Dashboard anzuzeigen.

Android

  1. (nur während der Ersteinrichtung, nicht für jeden Build) Richten Sie Ihren Build ein:
    1. Erstellen Sie einen neuen Ordner mit dem Namen „ Builds“ im Stammverzeichnis Ihres Projektverzeichnisses (d. h. als gleichgeordnetes Verzeichnis zu Ihrem Assets- Verzeichnis) und erstellen Sie dann einen Unterordner mit dem Namen „ Android“ .
    2. Legen Sie unter Datei > Build-Einstellungen > Player-Einstellungen > Konfiguration das Scripting-Backend auf IL2CPP fest.
      • IL2CPP führt im Allgemeinen dazu, dass Builds kleiner sind und eine bessere Leistung aufweisen.
      • IL2CPP ist auch die EINZIGE verfügbare Option unter iOS. Wenn Sie diese Option hier auswählen, können die beiden Plattformen eine bessere Parität aufweisen und das Debuggen von Unterschieden zwischen den beiden (wenn Sie sich dafür entscheiden, beide zu erstellen) einfacher machen.
  2. Erstellen Sie Ihre App. Führen Sie unter Datei > Build-Einstellungen Folgendes aus:
    1. Stellen Sie sicher, dass „Symbole erstellen.zip“ aktiviert ist (oder wählen Sie „Debuggen“ aus, wenn ein Dropdown-Menü angezeigt wird).
    2. Erstellen Sie Ihr APK direkt aus dem Unity-Editor in den Unterordner „Builds/Android“ , den Sie gerade erstellt haben.
  3. Sobald Ihr Build abgeschlossen ist, müssen Sie eine Crashlytics-kompatible Symboldatei generieren und diese auf Firebase-Server hochladen. Diese Symbolinformationen sind erforderlich, um symbolisierte Stack-Traces für Abstürze der nativen Bibliothek im Crashlytics-Dashboard anzuzeigen.

    Generieren Sie diese Symboldatei und laden Sie sie hoch, indem Sie den folgenden Firebase-CLI- Befehl ausführen:
    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. Es ist der mobilesdk_app_id Wert.
      Beispiel-ID einer Firebase-Android-App: 1:567383003300:android:17104a2ced0c9b9b
    • PATH/TO/SYMBOLS : der Pfad der komprimierten Symboldatei, die nach Abschluss Ihres Builds im Builds/Android- Verzeichnis generiert wurde (zum Beispiel: Builds/Android/myapp-1.0-v100.symbols.zip ).

Erzwingen Sie einen Testabsturz, um die Einrichtung abzuschließen

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

  1. Suchen Sie in der MainGameScene das EmptyObject GameObject im Editor Hierarchy , fügen Sie das folgende Skript hinzu und speichern Sie dann die Szene. Dieses Skript führt einige Sekunden nach der Ausführung Ihrer App zu einem Testabsturz.
    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 die Erstellung abgeschlossen ist.
    • iOS : Das Firebase Unity Editor-Plugin konfiguriert Ihr Xcode-Projekt automatisch zum Hochladen Ihrer Symboldatei.
    • Android : Führen Sie den Befehl crashlytics:symbols:upload der Firebase-CLI aus, um Ihre Symboldatei hochzuladen.
  3. Führen Sie Ihre App aus. Sobald Ihre App ausgeführt wird, beobachten Sie das Geräteprotokoll und warten Sie, bis die Ausnahme vom CrashlyticsTester ausgelöst wird.
    • iOS : Protokolle im unteren Bereich von Xcode anzeigen.
    • Android : Zeigen Sie Protokolle an, indem Sie den folgenden Befehl im Terminal ausführen: adb logcat .
  4. Besuchen Sie das Crashlytics-Dashboard , um die Ausnahme anzuzeigen! Sie sehen es in der Tabelle „Probleme“ unten im Dashboard. Später im Codelab erfahren Sie mehr darüber, wie Sie diese Berichte erkunden können.
  5. Nachdem Sie bestätigt haben, dass das Ereignis auf Crashlytics hochgeladen wurde, wählen Sie das EmptyObject GameObject aus, an das Sie es angehängt haben, entfernen Sie nur die CrashlyticsTester Komponente und speichern Sie dann die Szene, um sie in ihren ursprünglichen Zustand zurückzusetzen.

5. Aktivieren und verstehen Sie das Debug-Menü

Bisher haben Sie Crashlytics zu Ihrem Unity-Projekt hinzugefügt, die Einrichtung abgeschlossen und bestätigt, dass das Crashlytics SDK Ereignisse in Firebase hochlädt. Sie erstellen nun in Ihrem Unity-Projekt ein Menü, das zeigt, wie Sie erweiterte Crashlytics-Funktionen in Ihrem Spiel verwenden. Das Level Up with Firebase Unity-Projekt verfügt bereits über ein verstecktes Debug-Menü, das Sie sichtbar machen und die Funktionalität dafür schreiben.

Aktivieren Sie das Debug-Menü

Die Schaltfläche zum Zugriff auf das Debug-Menü ist in Ihrem Unity-Projekt vorhanden, aber derzeit nicht aktiviert. Sie müssen die Schaltfläche aktivieren, um über das MainMenu Fertigobjekt darauf zuzugreifen:

  1. Öffnen Sie im Unity-Editor das Prefab mit dem Namen MainMenu . 4148538cbe9f36c5.png
  2. Suchen Sie in der Fertighaushierarchie das deaktivierte Unterobjekt mit dem Namen DebugMenuButton und wählen Sie es dann aus. 816f8f9366280f6c.png
  3. Aktivieren Sie den DebugMenuButton , indem Sie das Kontrollkästchen in der oberen linken Ecke links neben dem Textfeld mit DebugMenuButton aktivieren. 8a8089d2b4886da2.png
  4. Speichern Sie das Fertigteil.
  5. Führen Sie das Spiel entweder im Editor oder auf Ihrem Gerät aus. Das Menü sollte nun zugänglich sein.

Sehen Sie sich die Methodenkörper für das Debug-Menü in der Vorschau an und verstehen Sie sie

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

Während einige dieser Methoden sowohl Crashlytics-Methoden aufrufen als auch Fehler auslösen, hängt die Fähigkeit von Crashlytics, diese Fehler abzufangen, nicht davon ab, ob diese Methoden zuerst aufgerufen werden. Vielmehr werden die Absturzberichte, die durch das automatische Erkennen von Fehlern generiert werden, durch die durch diese Methoden hinzugefügten Informationen verbessert.

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

Methoden zum Generieren und Kommentieren von Crashlytics-Problemen:

  • CrashNow
  • LogNonfatalError
  • LogStringsAndCrashNow
  • SetAndOverwriteCustomKeyThenCrash
  • SetLogsAndKeysBeforeANR

Methoden zum Protokollieren von Analytics-Ereignissen zur Unterstützung beim Debuggen:

  • LogProgressEventWithStringLiterals
  • LogIntScoreWithBuiltInEventAndParams

In späteren Schritten dieses Codelabs implementieren Sie diese Methoden und erfahren, wie sie dabei helfen, bestimmte Situationen zu bewältigen, die bei der Spieleentwicklung auftreten können.

6. Stellen Sie die Bereitstellung von Absturzberichten in der Entwicklung sicher

Bevor Sie mit der Implementierung dieser Debug-Methoden beginnen und sehen, wie sie sich auf Absturzberichte auswirken, stellen Sie sicher, dass Sie verstehen, wie Ereignisse an Crashlytics gemeldet werden.

Bei Unity-Projekten werden Absturz- und Ausnahmeereignisse in Ihrem Spiel sofort auf die Festplatte geschrieben. Nicht abgefangene 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, indem Sie die Crashlytics.ReportUncaughtExceptionsAsFatal -Eigenschaft auf true setzen, wo Sie Crashlytics in Ihrem Unity-Projekt initialisieren . Diese Ereignisse werden Crashlytics in Echtzeit gemeldet, ohne dass ein Endbenutzer das Spiel neu starten muss. Beachten Sie, dass native Abstürze immer als schwerwiegende Ereignisse gemeldet und mitgesendet werden, wenn ein Endbenutzer das Spiel neu startet.

Beachten Sie außerdem die folgenden kleinen, aber bedeutenden Unterschiede zwischen der Art und Weise, wie die verschiedenen Laufzeitumgebungen Crashlytics-Informationen an Firebase senden:

iOS-Simulator:

  • Crashlytics-Informationen werden nur dann gemeldet, wenn Sie Xcode vom Simulator trennen. Wenn Xcode angehängt ist, fängt es die Fehler im Vorfeld ab und verhindert so die Informationsübermittlung.

Mobile physische Geräte (Android und iOS):

  • Android-spezifisch: ANRs werden nur auf Android 11+ gemeldet. ANRs und nicht tödliche Ereignisse werden beim nächsten Lauf gemeldet.

Unity-Editor:

Testen Sie in CrashNow() wie Sie Ihr Spiel auf Knopfdruck zum Absturz bringen können.

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

  1. Um zu zeigen, dass dies tatsächlich automatisch geschieht: Öffnen Sie DebugMenu.cs und überschreiben Sie dann die Methode CrashNow() wie folgt:
    void CrashNow()
{
    TestCrash();
}
  2. Erstellen Sie Ihre App.
  3. (Nur Android) Laden Sie Ihre Symbole hoch, indem Sie den folgenden Firebase-CLI-Befehl ausführen:
    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 herauszufinden, wie Sie den Absturzbericht anzeigen und interpretieren können.

7. Problemberichte in der Firebase-Konsole verstehen

Wenn Sie Ihre Absturzberichte anzeigen möchten, müssen Sie noch ein wenig mehr darüber wissen, wie Sie sie optimal nutzen können. Jede der von Ihnen geschriebenen Methoden zeigt, wie Sie Crashlytics-Berichten verschiedene Arten von Informationen hinzufügen.

  1. Tippen Sie auf die Schaltfläche „Jetzt abstürzen“ und starten Sie dann Ihre App neu.
  2. Gehen Sie zum Crashlytics-Dashboard . Scrollen Sie nach unten zur Tabelle „Probleme “ unten im Dashboard, wo Crashlytics Ereignisse, die alle dieselbe Grundursache haben, in „Probleme“ gruppiert.
  3. Klicken Sie auf das neue Problem, das in der Tabelle „Probleme“ aufgeführt ist. Dadurch wird die Ereigniszusammenfassung zu jedem einzelnen Ereignis angezeigt, das an Firebase gesendet wurde.

    Sie sollten etwa den folgenden Screenshot sehen. Beachten Sie, dass in der Ereigniszusammenfassung deutlich der Stack-Trace des Aufrufs aufgeführt ist, der zum Absturz geführt hat. 40c96abe7f90c3aa.png

Zusätzliche Metadaten

Eine weitere hilfreiche Registerkarte ist die Registerkarte Unity-Metadaten . Dieser Abschnitt informiert Sie über die Attribute des Geräts, auf dem das Ereignis aufgetreten ist, einschließlich physischer Merkmale, des CPU-Modells/der CPU-Spezifikationen und aller Arten von GPU-Metriken.

Hier ist ein Beispiel, bei dem die Informationen auf dieser Registerkarte nützlich sein könnten:
Stellen Sie sich vor, Ihr Spiel nutzt stark Shader, um ein bestimmtes Aussehen zu erzielen, aber nicht alle Telefone verfügen über GPUs, die diese Funktion rendern können. Die Informationen auf der Registerkarte „Unity-Metadaten“ können Ihnen eine bessere Vorstellung davon geben, auf welche Hardware Ihre App testen sollte, wenn Sie entscheiden, welche Funktionen automatisch verfügbar gemacht oder vollständig deaktiviert werden sollen.

Obwohl auf Ihrem Gerät möglicherweise nie ein Fehler oder Absturz auftritt, ist es aufgrund der enormen Vielfalt an Android-Geräten hilfreich, die jeweiligen „Hotspots“ der Geräte Ihrer Zielgruppe besser zu verstehen.

41d8d7feaa87454d.png

8. Eine Ausnahme auslösen, abfangen und protokollieren

Selbst wenn Ihr Code als Entwickler eine Laufzeitausnahme ordnungsgemäß abfängt und behandelt, ist es oft gut zu beachten, dass sie aufgetreten ist und unter welchen Umständen. Crashlytics.LogException kann genau für diesen Zweck verwendet werden – um ein Ausnahmeereignis an Firebase zu senden, damit Sie das Problem in der Firebase-Konsole weiter debuggen können.

  1. Hängen Sie in Assets/Hamster/Scripts/States/DebugMenu.cs Folgendes an die using Anweisungen an:
    // Import Firebase
using Firebase.Crashlytics;
  2. Überschreiben Sie LogNonfatalError() immer noch in DebugMenu.cs wie folgt:
    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 hoch, indem Sie den folgenden Firebase-CLI-Befehl ausführen:
    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 dann Ihre App neu.
  6. Gehen Sie zum Crashlytics-Dashboard und Sie sollten etwas Ähnliches sehen wie im letzten Schritt dieses Codelabs.
  7. Beschränken Sie dieses Mal jedoch den Filter „Ereignistyp“ auf „Nicht schwerwiegend“ , sodass Sie nur nicht schwerwiegende Fehler anzeigen, z. B. den Fehler, den Sie gerade protokolliert haben.
    a39ea8d9944cbbd9.png

9. Protokollieren Sie Zeichenfolgen in Crashlytics, um den Ablauf der Programmausführung besser zu verstehen

Haben Sie jemals versucht herauszufinden, warum eine Codezeile, die von mehreren Pfaden aus Hunderte, wenn nicht Tausende Male pro Sitzung aufgerufen wird, plötzlich eine Ausnahme oder einen Absturz erzeugen kann? Es mag zwar schön sein, den Code in einer IDE durchzugehen und sich die Werte genauer anzusehen, aber was passiert, wenn dies nur bei einem verschwindend kleinen Prozentsatz Ihrer Benutzer geschieht? Schlimmer noch: Was würden Sie tun, wenn Sie diesen Absturz nicht reproduzieren können, egal, was Sie tun?

In Situationen wie dieser kann ein gewisser Kontext einen großen Unterschied machen. Mit Crashlytics.Log haben Sie die Möglichkeit, den benötigten Kontext aufzuschreiben. Betrachten Sie diese Nachrichten als Hinweise für Ihr zukünftiges Ich darüber, was möglicherweise vor sich geht.

Während Protokolle auf vielfältige Weise verwendet werden können, sind sie in der Regel am hilfreichsten für die Aufzeichnung von Situationen, in denen die Reihenfolge und/oder Abwesenheit von Anrufen eine äußerst wichtige Information darstellt.

  1. Überschreiben Sie in Assets/Hamster/Scripts/States/DebugMenu.cs LogStringsAndCrashNow() wie folgt:
    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 hoch, indem Sie den folgenden Firebase-CLI-Befehl ausführen:
    firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
  4. Tippen Sie auf die Schaltfläche „Zeichenfolgen protokollieren und jetzt abstürzen“ und starten Sie dann Ihre App neu.
  5. Gehen Sie zurück zum Crashlytics-Dashboard und klicken Sie auf das neueste Problem, das in der Tabelle „Probleme“ aufgeführt ist. Auch hier sollten Sie etwas Ähnliches wie in den vorherigen Ausgaben sehen.
    7aabe103b8589cc7.png
  6. Wenn Sie jedoch in einer Ereigniszusammenfassung auf die Registerkarte „Protokolle“ klicken, erhalten Sie eine Ansicht wie diese:
    4e27aa407b7571cf.png

10. Schreiben und überschreiben Sie einen benutzerdefinierten Schlüssel

Angenommen, Sie möchten einen Absturz besser verstehen, der auf Variablen zurückzuführen ist, die auf eine kleine Anzahl von Werten oder Konfigurationen festgelegt sind. Es könnte hilfreich sein, jederzeit auf der Grundlage der Kombination von Variablen und möglichen Werten, die Sie betrachten, filtern zu können.

Zusätzlich zur Protokollierung beliebiger Zeichenfolgen bietet Crashlytics eine weitere Form des Debuggens, wenn es hilfreich ist, den genauen Status Ihres Programms zum Zeitpunkt des Absturzes zu kennen: benutzerdefinierte Schlüssel.

Dabei handelt es sich um Schlüssel-Wert-Paare, die Sie für eine Sitzung festlegen können. Im Gegensatz zu Protokollen, die sich ansammeln und rein additiv sind, können Schlüssel überschrieben werden, um nur den aktuellsten Status einer Variablen oder Bedingung wiederzugeben.

Diese Schlüssel dienen nicht nur dazu, den zuletzt aufgezeichneten Status Ihres Programms aufzuzeichnen, sondern können auch als leistungsstarke Filter für Crashlytics-Probleme verwendet werden.

  1. Überschreiben Sie in Assets/Hamster/Scripts/States/DebugMenu.cs SetAndOverwriteCustomKeyThenCrash() wie folgt:
    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 hoch, indem Sie den folgenden Firebase-CLI-Befehl ausführen:
    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 dann Ihre App neu.
  5. Gehen Sie zurück zum Crashlytics-Dashboard und klicken Sie auf das neueste Problem, das in der Tabelle „Probleme“ aufgeführt ist. Auch hier sollten Sie etwas Ähnliches wie in den vorherigen Ausgaben sehen.
  6. Klicken Sie dieses Mal jedoch auf die Registerkarte „Schlüssel“ in der Ereigniszusammenfassung , damit Sie den Wert der Schlüssel einschließlich Current Time anzeigen können:
    7dbe1eb00566af98.png

Warum sollten Sie benutzerdefinierte Schlüssel anstelle benutzerdefinierter Protokolle verwenden?

  • Protokolle eignen sich gut zum Speichern sequenzieller Daten, aber benutzerdefinierte Schlüssel sind besser, wenn Sie nur den neuesten Wert benötigen.
  • In der Firebase-Konsole können Sie Probleme ganz einfach nach den Werten der Schlüssel im Suchfeld der Tabelle „Probleme“ filtern.

Ähnlich wie bei Protokollen gibt es jedoch auch für benutzerdefinierte Schlüssel ein Limit. Crashlytics unterstützt maximal 64 Schlüssel-Wert-Paare. Nach Erreichen dieses Schwellenwerts werden keine weiteren Werte gespeichert. Jedes Schlüssel-Wert-Paar kann bis zu 1 KB groß sein.

11. (Nur Android) Verwenden Sie benutzerdefinierte Schlüssel und Protokolle, um eine ANR zu verstehen und zu diagnostizieren

Eine der am schwierigsten zu debuggenden Problemklassen für Android-Entwickler ist der ANR-Fehler ( Application Not Responding ). ANRs treten auf, wenn eine App länger als 5 Sekunden nicht auf Eingaben reagiert. Wenn dies passiert, bedeutet das, dass die App entweder eingefroren ist oder sehr langsam läuft. Benutzern wird ein Dialog angezeigt, in dem sie wählen können, ob sie „Warten“ oder „App schließen“ möchten.

ANRs stellen eine schlechte Benutzererfahrung dar und können (wie im ANR-Link oben erwähnt) die Auffindbarkeit Ihrer App im Google Play Store beeinträchtigen. Aufgrund ihrer Komplexität und weil sie häufig durch Multithread-Code mit stark unterschiedlichem Verhalten auf verschiedenen Telefonmodellen verursacht werden, ist die Reproduktion von ANRs beim Debuggen oft sehr schwierig, wenn nicht sogar nahezu unmöglich. Daher ist es in der Regel der beste Ansatz, sie analytisch und deduktiv anzugehen.

Bei dieser Methode verwenden wir eine Kombination aus Crashlytics.LogException , Crashlytics.Log und Crashlytics.SetCustomKey , um die automatische Problemprotokollierung zu ergänzen und uns weitere Informationen zu liefern.

  1. Überschreiben Sie in Assets/Hamster/Scripts/States/DebugMenu.cs SetLogsAndKeysBeforeANR() wie folgt:
    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. Laden Sie Ihre Symbole hoch, indem Sie den folgenden Firebase-CLI-Befehl ausführen:
    firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
  4. Tippen Sie auf die Schaltfläche mit der Bezeichnung Protokolle und Schlüssel festlegen → ANR und starten Sie dann Ihre App neu.
  5. Gehen Sie zurück zum Crashlytics-Dashboard und klicken Sie dann in der Tabelle „Probleme“ auf das neue Problem, um die Ereigniszusammenfassung anzuzeigen. Wenn der Anruf ordnungsgemäß durchgeführt wurde, sollten Sie etwa Folgendes sehen:
    876c3cff7037bd07.png

    Wie Sie sehen können, hat Firebase das geschäftige Warten im Thread als Hauptgrund dafür identifiziert, dass Ihre App eine ANR ausgelöst hat.
  6. Wenn Sie sich die Protokolle auf der Registerkarte „Protokolle“ der Ereigniszusammenfassung ansehen, werden Sie feststellen, dass die letzte als abgeschlossen aufgezeichnete Methode DoSevereWork ist.
    5a4bec1cf06f6984.png

    Im Gegensatz dazu ist die letzte als startend aufgeführte Methode DoExtremeWork , was darauf hinweist, dass die ANR während dieser Methode aufgetreten ist und das Spiel geschlossen wurde, bevor es DoExtremeWork protokollieren konnte.

    89d86d5f598ecf3a.png

Warum das tun?

  • Das Reproduzieren von ANRs ist unglaublich schwierig, daher ist es unglaublich wichtig, umfangreiche Informationen über den Codebereich und die Metriken zu erhalten, um dies deduktiv herauszufinden.
  • Anhand der in den benutzerdefinierten Schlüsseln gespeicherten Informationen wissen Sie nun, welcher asynchrone Thread für die Ausführung am längsten gedauert hat und bei welchen die Gefahr bestand, ANRs auszulösen. Diese Art verwandter logischer und numerischer Daten zeigt Ihnen, wo in Ihrem Code eine Optimierung am nötigsten ist.

12. Einsetzen von Analytics-Ereignissen zur weiteren Bereicherung von Berichten

Die folgenden Methoden können auch über das Debug-Menü aufgerufen werden, aber anstatt selbst Probleme zu generieren, nutzen sie Google Analytics als weitere Informationsquelle, 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 (durch Drücken der entsprechenden Schaltfläche im Debug-Menü) in beliebiger Reihenfolge auf, bevor Sie eine der anderen ausführen. Wenn Sie dann die Informationen in der spezifischen Crashlytics-Ausgabe untersuchen, sehen Sie ein geordnetes Protokoll der Analytics-Ereignisse. Diese Daten können in einem Spiel verwendet werden, um eine Kombination aus Programmablauf oder Benutzereingaben besser zu verstehen, je nachdem, wie Sie Ihre App instrumentiert haben.

  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 Sie Ihr Spiel, stellen Sie es bereit und rufen Sie dann das Debug-Menü auf.
  3. (Nur Android) Laden Sie Ihre Symbole hoch, indem Sie den folgenden Firebase-CLI-Befehl ausführen:
    firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
  4. Drücken Sie mindestens eine der folgenden Tasten einmal oder mehrmals, um die oben genannten Funktionen aufzurufen:
    • Protokollzeichenfolgenereignis
    • Log Int-Ereignis
  5. Klicken Sie auf die Schaltfläche „Jetzt abstürzen“ .
  6. Starten Sie Ihr Spiel neu, damit es das Absturzereignis in Firebase hochlädt.
  7. Wenn Sie verschiedene beliebige Sequenzen von Analytics-Ereignissen protokollieren und Ihr Spiel dann ein Ereignis generieren lässt, aus dem Crashlytics einen Bericht erstellt (wie Sie es gerade getan haben), werden diese wie folgt zur Registerkarte „ Protokolle “ der Crashlytics -Ereigniszusammenfassung hinzugefügt:
    d3b16d78f76bfb04.png

13. Vorwärts gehen

Und damit sollten Sie über eine bessere theoretische Grundlage verfügen, auf der Sie Ihre automatisch generierten Absturzberichte ergänzen können. Mit diesen neuen Informationen können Sie den aktuellen Status, Aufzeichnungen vergangener Ereignisse und vorhandene Google Analytics-Ereignisse nutzen, um die Abfolge der Ereignisse und die Logik, die zu ihrem Ergebnis geführt hat, besser aufzuschlüsseln.

Wenn Ihre App auf Android 11 (API-Level 30) oder höher abzielt, sollten Sie die Integration von GWP-ASan in Betracht ziehen, einer nativen Speicherzuweisungsfunktion, die zum Debuggen von Abstürzen nützlich ist, die durch native Speicherfehler wie use-after-free und heap-buffer-overflow Fehler verursacht werden. Um diese Debugging-Funktion nutzen zu können, aktivieren Sie GWP-ASan explizit .

Nächste Schritte

Fahren Sie mit dem Codelab „Instrumentieren Sie Ihr Unity-Spiel mit Remote Config“ fort , in dem Sie mehr über die Verwendung von Remote Config und A/B-Tests in Unity erfahren.