Firebase Crashlytics 使用入门


此快速入门介绍了如何使用 Firebase Crashlytics SDK 在应用中设置 Firebase Crashlytics,以便您可以在 Firebase 控制台中获得全面的崩溃报告。

设置 Crashlytics 需要在 Firebase 控制台和 IDE 中分别执行一些操作(例如添加 Firebase 配置文件和 Crashlytics SDK)。为了完成设置,您需要强制造成一次测试崩溃,以便向 Firebase 发送您的第一个崩溃报告。

准备工作

  1. 将 Firebase 添加到您的 Unity 项目(如果尚未添加)。如果您没有 Unity 项目,可以下载一个示例应用

  2. 建议:要自动获取路径日志以了解导致崩溃事件、非严重事件或 ANR 事件的用户操作,您需要在 Firebase 项目中启用 Google Analytics

    • 如果您的现有 Firebase 项目未启用 Google Analytics,您可以访问 Firebase 控制台,依次点击 >“项目设置”,然后在集成标签页中启用 Google Analytics

    • 如果您要创建新的 Firebase 项目,请在项目创建工作流中启用 Google Analytics

第 1 步:将 Crashlytics SDK 添加到您的应用

注意:在向 Firebase 项目注册 Unity 项目时,您可能已经下载了 Firebase Unity SDK 并添加了以下步骤中所述的软件包。

  1. 下载 Firebase Unity SDK,然后将此 SDK 解压缩到合适的位置。 Firebase Unity SDK 不局限于特定平台。

  2. 在您打开的 Unity 项目中,依次转到 Assets > Import Package > Custom Package

  3. 从解压缩的 SDK 中,选择导入 Crashlytics SDK (FirebaseCrashlytics.unitypackage)。

    如需利用路径日志,还可以将 Firebase SDK for Google Analytics 添加到您的应用 (FirebaseAnalytics.unitypackage) 中。确保您的 Firebase 项目中启用了 Google Analytics

  4. 在“Import Unity Package”(导入 Unity 软件包)窗口中,点击 Import(导入)。

第 2 步:初始化 Crashlytics

  1. 创建一个新的 C# 脚本,然后将其添加到场景中的 GameObject

    1. 打开您的第一个场景,然后创建一个名为 CrashlyticsInitializer 的空 GameObject

    2. 在新对象的 Inspector(检查器)中点击 Add Component(添加组件)。

    3. 选择 CrashlyticsInit 脚本以将其添加到 CrashlyticsInitializer 对象中。

  2. 在该脚本的 Start 方法中初始化 Crashlytics

    using System.Collections;
    using System.Collections.Generic;
    using UnityEngine;
    
    // Import Firebase and Crashlytics
    using Firebase;
    using Firebase.Crashlytics;
    
    public class CrashlyticsInit : MonoBehaviour {
        // Use this for initialization
        void Start () {
            // Initialize Firebase
            Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWith(task => {
                var dependencyStatus = task.Result;
                if (dependencyStatus == Firebase.DependencyStatus.Available)
                {
                    // Create and hold a reference to your FirebaseApp,
                    // where app is a Firebase.FirebaseApp property of your application class.
                    // Crashlytics will use the DefaultInstance, as well;
                    // this ensures that Crashlytics is initialized.
                    Firebase.FirebaseApp app = Firebase.FirebaseApp.DefaultInstance;
    
                    // When this property is set to true, Crashlytics will report all
                    // uncaught exceptions as fatal events. This is the recommended behavior.
                    Crashlytics.ReportUncaughtExceptionsAsFatal = true;
    
                    // Set a flag here for indicating that your project is ready to use Firebase.
                }
                else
                {
                    UnityEngine.Debug.LogError(System.String.Format(
                      "Could not resolve all Firebase dependencies: {0}",dependencyStatus));
                    // Firebase Unity SDK is not safe to use here.
                }
            });
        }
    
      // Update is called once per frame
      void Update()
        // ...
    }

第 3 步:(仅限 Android)设置符号上传

只有使用 IL2CPP 的 Android 应用才需要执行此步骤。

  • 对于使用 Unity 的 Mono 脚本后端的 Android 应用,不需要执行这些步骤。

  • 对于 Apple 平台应用,不需要执行这些步骤,因为 Firebase Unity Editor 插件会自动配置您的 Xcode 项目以上传符号。

Crashlytics 的 Unity SDK 8.6.1 及更高版本自动包含 NDK 崩溃报告,让 Crashlytics 能够自动报告 Android 上的 Unity IL2CPP 崩溃问题。不过,如需在 Crashlytics 信息中心内查看原生库崩溃的经过符号化解析的堆栈轨迹,您必须在构建时使用 Firebase CLI 上传符号信息。

如需设置符号上传,请按照说明安装 Firebase CLI

如果您已安装 CLI,请务必将其更新为最新版本

第 4 步:构建项目并上传符号

iOS+(Apple 平台)

  1. 在“Build Settings”(构建设置)对话框中,将您的项目导出到 Xcode 工作区。

  2. 构建您的应用。

    对于 Apple 平台,Firebase Unity Editor 插件会自动配置 Xcode 项目,以便为每个 build 生成与 Crashlytics 兼容的符号文件并将其上传到 Firebase 服务器。

Android

  1. 在“Build Settings”(构建设置)对话框中,执行以下操作之一:

    • 导出到 Android Studio 项目以构建您的项目;或

    • 直接通过 Unity 编辑器构建 APK。
      在构建之前,请确保在“Build Settings(构建设置)”对话框中选中 Create symbols.zip(创建 symbols.zip)复选框。

  2. 构建完成后,生成与 Crashlytics 兼容的符号文件,然后运行以下 Firebase CLI 命令将其上传到 Firebase 服务器:

    firebase crashlytics:symbols:upload --app=FIREBASE_APP_ID PATH/TO/SYMBOLS
    • FIREBASE_APP_ID:您的 Firebase Android 应用 ID(而不是您的软件包名称)
      示例 Firebase Android 应用 ID:1:567383003300:android:17104a2ced0c9b9b

    • PATH/TO/SYMBOLS:CLI 生成的符号文件的路径

      • 导出到 Android Studio 项目 - PATH/TO/SYMBOLSunityLibrary/symbols 目录,在您通过 Gradle 或 Android Studio 构建应用后,系统会在导出的项目根目录中创建该目录。

      • 直接在 Unity 中构建 APK - PATH/TO/SYMBOLS 是构建完成时在项目根目录中生成的压缩符号文件的路径(例如:myproject/myapp-1.0-v100.symbols.zip)。

    查看可使用 Firebase CLI 命令生成和上传符号文件的高级选项

    标志 说明
    --generator=csym

    使用旧版 cSYM 符号文件生成器,而不是默认的 Breakpad 生成器

    不推荐使用。我们建议您使用默认的 Breakpad 符号文件生成器。

    --generator=breakpad

    使用 Breakpad 符号文件生成器

    请注意,用于生成符号文件的默认选项是 Breakpad。 只有当您已经在 build 配置中添加了 symbolGenerator { csym() },并且想要替换它以改用 Breakpad 时,才需要使用此标志。

    --dry-run

    生成符号文件,但不将其上传

    如果您要检查所发送文件的内容,此标志将非常有用。

    --debug 提供额外的调试信息

第 5 步:强制造成一次测试崩溃以完成设置

如需完成 Crashlytics 设置并在 Firebase 控制台的 Crashlytics 信息中心内查看初始数据,您需要强制造成一次测试崩溃。

  1. 找到现有的 GameObject,然后向其中添加以下脚本。此脚本将在您运行应用几秒钟后造成一次测试崩溃。

    using System;
    using UnityEngine;
    
    public class CrashlyticsTester : MonoBehaviour {
    
        int updatesBeforeException;
    
        // Use this for initialization
        void Start () {
          updatesBeforeException = 0;
        }
    
        // Update is called once per frame
        void Update()
        {
            // Call the exception-throwing method here so that it's run
            // every frame update
            throwExceptionEvery60Updates();
        }
    
        // A method that tests your Crashlytics implementation by throwing an
        // exception every 60 frame updates. You should see reports in the
        // Firebase console a few minutes after running your app with this method.
        void throwExceptionEvery60Updates()
        {
            if (updatesBeforeException > 0)
            {
                updatesBeforeException--;
            }
            else
            {
                // Set the counter to 60 updates
                updatesBeforeException = 60;
    
                // Throw an exception to test your Crashlytics implementation
                throw new System.Exception("test exception please ignore");
            }
        }
    }
  2. 构建您的应用,并在构建完成后上传符号信息。

    • iOS+:Firebase Unity Editor 插件会自动配置您的 Xcode 项目,以便上传您的符号文件。

    • Android:对于使用 IL2CPP 的 Android 应用,请运行 Firebase CLI crashlytics:symbols:upload 命令来上传您的符号文件。

  3. 运行应用。应用运行后,查看设备日志并等待 CrashlyticsTester 触发异常。

    • iOS+:在 Xcode 的底部窗格中查看日志。

    • Android:在终端中运行以下命令来查看日志:adb logcat

  4. 前往 Firebase 控制台的 Crashlytics 信息中心,查看您的测试崩溃报告。

    如果您已刷新控制台,但在五分钟后仍未看到测试崩溃报告,请启用调试日志记录,查看您的应用是否正在发送崩溃报告。


大功告成!Crashlytics 现在会监控您的应用是否发生崩溃。您可以访问 Crashlytics 信息中心以查看和调查所有报告和统计信息。

后续步骤

  • (推荐)对于使用 IL2CPP 的 Android 应用,请收集 GWP-ASan 报告,以帮助调试由原生内存错误引起的崩溃。这些内存相关错误可能与应用内的内存损坏有关,这也是导致应用安全漏洞的主要原因。要利用此调试功能,请确保您的应用使用最新的 Crashlytics SDK for Unity (v10.7.0+) 并且明确启用了 GWP-ASan(要求您修改 Android 应用清单)。
  • Google Play 集成,以便您可以直接在 Crashlytics 信息中心内按 Google Play 轨道过滤 Android 应用的崩溃报告。这样可让 Crashlytics 信息中心更有侧重地显示特定 build 的崩溃信息。