開始使用 Firebase Crashlytics

本快速入門導覽課程說明如何使用 Firebase Crashlytics SDK，在應用程式中設定 Firebase Crashlytics，方便您在 Firebase 控制台中取得完整的當機報告。

設定 Crashlytics 時，必須同時在 Firebase 控制台和 IDE 中完成工作 (例如新增 Firebase 設定檔和 Crashlytics SDK)，如要完成設定，您必須強制執行測試當機問題，將第一份當機報告傳送至 Firebase。

事前準備

如果您尚未新增 Firebase 至 Unity 專案，請先完成這項操作。如果您沒有 Unity 專案，可以下載範例應用程式。
建議做法：如要自動取得導覽標記記錄，瞭解引發當機、不嚴重或 ANR 事件的使用者動作，您必須在 Firebase 專案中啟用 Google Analytics (分析)。
- 如果現有的 Firebase 專案尚未啟用 Google Analytics (分析)，可以前往 Firebase 控制台，在 >「專案設定」中，透過「Integrations」分頁啟用 Google Analytics (分析)。
- 如果要建立新的 Firebase 專案，請在專案建立工作流程中啟用 Google Analytics (分析)。

步驟 1：在應用程式中新增 Crashlytics SDK

請注意，使用 Firebase 專案註冊 Unity 專案時，您可能已經下載 Firebase Unity SDK 並新增下列步驟中所述的套件。

下載 Firebase Unity SDK，然後將 SDK 解壓縮，Firebase Unity SDK 並非專屬於特定平台。
在開放式 Unity 專案中，依序前往「Assets」 >「Import Package」 >「Custom Package」。
在已解壓縮的 SDK 中，選擇要匯入 Crashlytics SDK (FirebaseCrashlytics.unitypackage)。

如要使用導覽標記記錄，請將 Google Analytics (分析) 專用 Firebase SDK 加進您的應用程式 (FirebaseAnalytics.unitypackage)。請務必在您的 Firebase 專案中啟用 Google Analytics (分析)。

Unity 2017.x 以上版本允許使用 .NET 4.x 架構。如果您的 Unity 專案使用 .NET 4.x，請匯入 dotnet4/FirebaseCrashlytics.unitypackage。
在「Import Unity Package」視窗中，按一下「Import」。

步驟 2：初始化 Crashlytics

建立新的 C# 指令碼，然後將其新增至場景中的 GameObject。
1. 開啟第一個場景，然後建立名為 CrashlyticsInitializer 的空白 GameObject。
2. 在「Inspector」中為新物件按一下「Add Component」。
3. 選取 CrashlyticsInit 指令碼，將其新增至 CrashlyticsInitializer 物件。

在指令碼的 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 編輯器外掛程式會自動設定 Xcode 專案來上傳符號。

Crashlytics 的 Unity SDK 8.6.1 以上版本會自動納入 NDK 當機回報，讓 Crashlytics 可以自動回報 Android 上的 Unity IL2CPP 當機問題。不過，如要在 Crashlytics 資訊主頁中查看原生程式庫的符號化堆疊追蹤異常終止，您必須使用 Firebase CLI 在建構期間上傳符號資訊。

如要設定符號上傳功能，請按照操作說明安裝 Firebase CLI。

如果您已安裝 CLI，請務必更新至最新版本。

步驟 4：建立專案並上傳符號

iOS+ (Apple 平台)

在「Build Settings」對話方塊中，將專案匯出至 Xcode 工作區。
建構應用程式。

針對 Apple 平台，Firebase Unity 編輯器外掛程式會自動設定您的 Xcode 專案，為每個版本產生與 Crashlytics 相容的符號檔案，並將其上傳至 Firebase 伺服器。

Android

在「Build Settings」對話方塊中，執行下列其中一項操作：
- 匯出至 Android Studio 專案以建構專案。
- 直接透過 Unity 編輯器建構 APK。
  建構前，請務必在「Build Settings」對話方塊中勾選「Create signature.zip」核取方塊。

建構完成後，請產生與 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
需要查看您的 Firebase 應用程式 ID 嗎？
你可以透過以下兩種方法找出 Firebase 應用程式 ID：
- 在 google-services.json 檔案中，應用程式 ID 為 mobilesdk_app_id 值；或
- 在 Firebase 控制台中，前往「Project settings」。向下捲動至「Your apps」資訊卡，然後按一下所需的 Firebase 應用程式，即可找到應用程式 ID。
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 產生器不建議使用。建議您使用預設的分行符號檔案產生器。
`--generator=breakpad`	使用 Breakpad 符號檔案產生器請注意，產生符號檔案的預設值是 Breakpad。只有在建構設定中新增 `symbolGenerator { csym() }`，並想要改為使用 Breakpad 時，才能使用這個旗標。
`--dry-run`	產生符號檔案但不會上傳如要檢查已傳送的檔案內容，這個標記就非常實用。
`--debug`	提供其他偵錯資訊

步驟 5：強制執行測試當機以完成設定

如要完成 Crashlytics 設定，並在 Firebase 控制台的 Crashlytics 資訊主頁中查看初始資料，您必須強制執行測試當機。

找出現有的 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");
        }
    }
}

建構應用程式，並在建構完成後上傳符號資訊。
- iOS+：Firebase Unity 編輯器外掛程式會自動設定 Xcode 專案以上傳符號檔案。
- Android：如果是使用 IL2CPP 的 Android 應用程式，請執行 Firebase CLI crashlytics:symbols:upload 指令來上傳符號檔案。
執行應用程式。應用程式執行後，請查看裝置記錄，並等待例外狀況從 CrashlyticsTester 觸發。
- iOS+：在 Xcode 的底部窗格中查看記錄。
- Android：在終端機中執行下列指令，以便查看記錄：adb logcat。
前往 Firebase 控制台的 Crashlytics 資訊主頁，查看測試當機情形。

如果您已重新整理主控台，但五分鐘後仍未看到測試當機情形，請啟用偵錯記錄，查看應用程式是否正在傳送當機報告。

大功告成！Crashlytics 正在監控應用程式的當機情況。請前往 Crashlytics 資訊主頁，查看及調查所有報表和統計資料。

後續步驟

(建議) 如果是使用 IL2CPP 的 Android 應用程式，請收集 GWP-ASan 報告，瞭解原生記憶體錯誤造成的當機問題。這些記憶體相關錯誤可能與應用程式內的記憶體毀損相關聯，是造成應用程式安全漏洞的主要原因。如要利用這項偵錯功能，請確認您的應用程式採用最新的 Unity 專用 Crashlytics SDK (v10.7.0 以上版本)，並已明確啟用 GWP-ASan (須修改 Android 應用程式資訊清單)。

新增選擇接受報告、記錄、金鑰和非重大錯誤追蹤，藉此自訂當機報告設定。

整合 Google Play，直接在 Crashlytics 資訊主頁中，按照 Google Play 測試群組篩選 Android 應用程式的當機報告。如此一來，資訊主頁就能更專注於特定建構。