查看 2022 年 Google I/O 大会上介绍的 Firebase 新动态。了解详情

Firebase Crashlytics 使用入门

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

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

准备工作

  1. 为您的 Unity 项目添加 Firebase（如果尚未添加）。如果您没有 Unity 项目，可以下载一个示例应用。

  2. 建议做法：如需使用“未遇到崩溃问题的用户”、“面包屑导航日志”和“疾速崩溃提醒”等功能，您需要在 Firebase 项目中启用 Google Analytics（分析）。

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

    • 如果您要创建新的 Firebase 项目，请在项目创建过程中启用 Google Analytics（分析）。

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

注意：在向 Firebase 项目注册 Unity 项目时，您可能已经下载了 Firebase Unity SDK 并添加了 Crashlytics 软件包。

  1. 下载 Firebase Unity SDK，然后将其解压缩到方便的位置。

    Firebase Unity SDK 不局限于特定平台。

  2. 在您打开的 Unity 项目中，依次转到 Assets（资产）> Import Package（导入软件包）> Custom Package（自定义软件包）。

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

    您也可以导入其他任何受支持的 Firebase 产品。

  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
using Firebase;

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;

                // 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 上传符号信息。

如需进行设置以上传符号，请完成以下步骤：

  1. 按照说明安装 Firebase CLI。

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

  2. （仅适用于使用 Android API 级别 30 及更高级别的应用）更新应用的 AndroidManifest.xml 模板以停用指针标记：

    1. 依次勾选 Android Player Settings（Android 播放器设置）> Publishing Settings（发布设置）> Build（构建）> Custom Main Manifest（自定义主清单）对应的复选框。

    2. 打开位于 Assets/Plugins/Android/AndroidManifest.xml 的清单模板。

    3. 将以下特性添加到应用标记：<application android:allowNativeHeapPointerTagging="false" ... />

第 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/SYMBOLS 是 unityLibrary/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 non-fatal errors 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。

  5. 请转到 Firebase 控制台的 Crashlytics 信息中心 以查看您的测试崩溃报告。

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


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

后续步骤

  • 与 Google Play 集成，以便您可以直接在 Crashlytics 信息中心内按 Google Play 轨道过滤 Android 应用的崩溃报告。这样可让 Crashlytics 信息中心更有侧重地显示特定 build。