本快速入門說明如何使用 Firebase Crashlytics SDK 在應用程式中設定 Firebase Crashlytics,以便您在 Firebase 主控台中取得完整的當機報告。
設定 Crashlytics 需要在 Firebase 主控台和 IDE 中執行多項工作 (例如新增 Firebase 設定檔和 Crashlytics SDK)。如要完成設定,您必須強制測試當機,才能將第一份當機報告傳送至 Firebase。
事前準備
建議:如要自動取得導覽標記記錄,瞭解導致當機、非致命或 ANR 事件的使用者動作,您必須在 Firebase 專案中啟用 Google Analytics。
如果現有的 Firebase 專案未啟用 Google Analytics,請前往 Firebase 控制台,依序前往
,依序點選 >「Project settings」「Integrations」分頁和「Project settings」,啟用 Google Analytics。 如果您要建立新的 Firebase 專案,請在專案建立工作流程中啟用 Google Analytics。
步驟 1:在應用程式中加入 Crashlytics SDK
請注意,當您將 Unity 專案註冊至 Firebase 專案時,可能已下載 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。在「Import Unity Package」視窗中,按一下「Import」。
步驟 2:初始化 Crashlytics
建立新的 C# 指令碼,然後將其新增至場景中的
GameObject
。開啟第一個場景,然後建立名為
CrashlyticsInitializer
的空白GameObject
。在新物件的「檢查器」中,按一下「新增元件」。
選取
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 Editor 外掛程式會自動設定 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 Editor 外掛程式會自動設定 Xcode 專案,為每個版本產生並上傳與 Crashlytics 相容的符號檔案至 Firebase 伺服器。
Android
在「Build Settings」對話方塊中,執行下列其中一項操作:
匯出至 Android Studio 專案以建構專案;或
直接透過 Unity 編輯器建立 APK。
建構前,請確認「Build Settings」對話方塊中已勾選「Create symbols.zip」核取方塊。
建置完成後,請執行下列 Firebase CLI 指令,產生 Crashlytics 相容的符號檔案,並將其上傳至 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。只有在您已在建構設定中新增
,且想要覆寫該設定以改用 Breakpad 時,才使用這個標記。symbolGenerator { csym() }
--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 (10.7.0 以上版本),並且已明確啟用 GWP-ASan (需要修改 Android 應用程式資訊清單)。
- 新增選擇啟用報告、記錄、鍵及一般錯誤的追蹤,以自訂當機報告設定。
- 整合 Google Play,即可直接在 Crashlytics 資訊主頁中,依據 Google Play 追蹤記錄篩選 Android 應用程式的當機報告。這樣一來,您就能更專注於特定版本的資訊主頁。