App Center (Unity) 損毀

重要

Visual Studio App Center 已排定於 2025 年 3 月 31 日淘汰。 雖然您可以繼續使用 Visual Studio App Center，直到它完全淘汰為止，但有數個建議您考慮移轉至的建議替代方案。

深入瞭解支持時程表和替代方案。

• Android
• iOS
• MAUI/Xamarin
• UWP
• WPF/WinForms
• React Native \(英文\)
• macOS
• tvOS
• Unity
• Cordova

App Center 當機會在每次應用程式當機時自動產生當機記錄，並記錄到裝置記憶體。 當使用者再次啟動應用程式時，SDK 會將當機報告傳送至 App Center。 收集當機適用於 Beta 和即時應用程式，也就是提交至 Google Play 的當機。 當機記錄包含協助您修正損毀的重要資訊。

如果您尚未在應用程式中設定 SDK，請遵循 Unity 使用者入門 一節中的指示。

iOS 上的當機記錄需要符號。 若要啟用符號，請參閱 App Center 診斷檔，其說明如何為您的應用程式提供符號。

重要

適用於 Unity 的當機 SDK 不支援 UWP。 此頁面中的指示僅涵蓋Android和iOS。

注意

如果您已附加調試程式，SDK 將不會轉送任何損毀記錄。 當您損毀應用程式時，請確定調試程式未附加。

注意

如果您已在 Enable CrashReport APIPlayerSettings 中啟用，SDK 將不會收集損毀記錄。

產生測試損毀

App Center 當機提供 API 來產生測試損毀，以便輕鬆測試 SDK。 此 API 會檢查偵錯與發行組態。 因此，您只能在偵錯時使用它，因為它不適用於發行應用程式。

Crashes.GenerateTestCrash();

注意

這個方法只適用於開啟 [開發組建 ] 設定。

取得先前損毀的詳細資訊

App Center 當機有兩個 API，可讓您在應用程式損毀時取得詳細資訊。

應用程式在上一個會話中是否收到低記憶體警告？

在啟動 SDK 之後，您可以隨時檢查應用程式是否在上一個工作階段中收到記憶體警告：

bool hadLowMemoryWarning = Crashes.HasReceivedMemoryWarningInLastSessionAsync().Result;

注意

這個方法無法在 中 Awake()運作。

注意

在某些情況下，記憶體不足的裝置無法傳送事件。

應用程式在上一個會話中當機嗎？

在啟動 SDK 之後，您可以隨時檢查應用程式是否在上一次啟動時當機：

bool didAppCrash = await Crashes.HasCrashedInLastSessionAsync();

如果您想要在發生當機之後調整應用程式的行為或 UI，呼叫 HasCrashedInLastSessionAsync 會很有用。 有些開發人員會向用戶顯示其他UI，或想要在發生當機之後連絡。

上次損毀的詳細數據

如果您的應用程式先前損毀，您可以取得上次損毀的詳細數據。

ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();

此 API 最常見的使用案例是當用戶實作其自定義 當機委派或接聽程式時。

自訂 App Center 損毀的使用方式

App Center 當機提供回呼，讓開發人員在將損毀記錄傳送至 App Center 之前和何時採取其他動作。

注意

在 App Center 啟動時設定回呼，例如在 方法中 Awake ，因為 App Center 會在啟動後立即開始處理當機。

應該處理當機嗎？

如果您想要決定是否需要處理特定的當機，請設定下列回呼。 例如，您可能想要忽略系統層級損毀，而不會傳送至 App Center。

Crashes.ShouldProcessErrorReport = (ErrorReport report) =>
{
     // Check the report in here and return true or false depending on the ErrorReport.
    return true;
};

要求使用者同意傳送損毀記錄

如果用戶隱私權對您很重要，您可能會想要在將損毀報告傳送至 App Center 之前先取得使用者確認。 SDK 會公開回呼，告知 App Center 當機在傳送任何損毀報告之前，先等候使用者確認。

如果您的程式代碼使用此回呼，您必須負責取得使用者的確認。 其中一個選項是透過具有下列其中一個選項的對話框提示： 永遠傳送、 傳送和 不要傳送。 根據輸入，您會告訴 App Center 損毀要執行的動作，然後會據以處理當機。

注意

SDK 不會顯示此對話框，應用程式必須提供自己的 UI 以要求使用者同意。

下列回呼示範如何告訴 SDK 在傳送當機之前等候使用者確認：

Crashes.ShouldAwaitUserConfirmation = () =>
{
    // Build your own UI to ask for user consent here. SDK doesn't provide one by default.

    // Return true if you built a UI for user consent and are waiting for user input on that custom UI, otherwise false.
    return true;
};

如果回呼傳 true回 ，您必須使用下列 API 取得使用者許可權並訊息 SDK 與結果：

// Depending on the user's choice, call Crashes.NotifyUserConfirmation() with the right value.
Crashes.NotifyUserConfirmation(UserConfirmation.DontSend);
Crashes.NotifyUserConfirmation(UserConfirmation.Send);
Crashes.NotifyUserConfirmation(UserConfirmation.AlwaysSend);

例如，您可以參考 我們的自定義對話框範例。

取得損毀記錄傳送狀態的相關信息

有時候，您想要知道應用程式當機的狀態。 常見的使用案例是顯示UI，通知使用者應用程式正在提交當機報告。 另一個案例是當您想要調整應用程式的行為，以確保在重新啟動後很快就會提交當機記錄。 App Center 當機提供三個不同的回呼，您可以提出通知，以通知發生什麼事：

在 SDK 傳送當機記錄之前，將會叫用下列回呼

Crashes.SendingErrorReport += (errorReport) =>
{
    // Your code, e.g. to present a custom UI.
};

如果端點發生網路問題或中斷，且您重新啟動應用程式， SendingErrorReport 則會在進程重新啟動后再次觸發。

在 SDK 成功傳送損毀記錄之後，將會叫用下列回呼

Crashes.SentErrorReport += (errorReport) =>
{
    // Your code, e.g. to hide the custom UI.
};

如果 SDK 無法傳送損毀記錄檔，將會叫用下列回呼

Crashes.FailedToSendErrorReport += (errorReport, exception) =>
{
    // Your code goes here.
};

FailedToSendErrorReport接收表示發生無法復原的錯誤，例如發生 4xx 碼。 例如， 401 表示 appSecret 錯誤。

如果這是網路問題，則不會觸發此回呼。 在此情況下，SDK 會持續重試 (，並在網路連線關閉時暫停重試) 。

將附件新增至損毀或未處理的例外狀況報告

您也可以選擇性地將二進位和文字附件新增至當機或 未處理的例外 狀況報告。 SDK 會連同報表一起傳送，以便您可以在 App Center 入口網站中看到它們。 在傳送預存報表之前，會立即叫用下列回呼。 針對當機，會在下一個應用程式啟動時發生。 針對未處理的例外狀況，您必須 加入加入 以傳送附件。 請確定附件檔案 未 命名 minidump.dmp 為該名稱保留給迷你傾印檔案。 以下是如何將文字和影像附加至報表的範例：

Crashes.GetErrorAttachments = (ErrorReport report) =>
{
    // Your code goes here.
    return new ErrorAttachmentLog[]
    {
        ErrorAttachmentLog.AttachmentWithText("Hello world!", "hello.txt"),
        ErrorAttachmentLog.AttachmentWithBinary(Encoding.UTF8.GetBytes("Fake image"), "fake_image.jpeg", "image/jpeg")
    };
};

當機與具有 屬性的報表 IsCrash 中未處理的例外狀況有所區別。 如果當機則為 true，否則為 false。

注意

大小限制適用於目前為 7 MB 的附件。 嘗試傳送較大的附件將會觸發錯誤。

注意

GetErrorAttachments 會在主線程上叫用，而且不會將工作分割在畫面上。 若要避免封鎖遊戲迴圈，請勿在此回呼中執行任何長時間執行的工作。

在運行時間啟用或停用 App Center 當機

您可以在執行時間啟用和停用 App Center 當機。 如果您將其停用，SDK 將不會針對應用程式執行任何損毀報告。

Crashes.SetEnabledAsync(false);

若要再次啟用App Center當機，請使用相同的API，但傳遞 true 做為參數。

Crashes.SetEnabledAsync(true);

您不需要等候此呼叫，才能 (進行其他 API 呼叫，例如 IsEnabledAsync) 一致。

狀態會保存在應用程式啟動的裝置記憶體中。

檢查 App Center 當機是否已啟用

您也可以檢查 App Center 當機是否已啟用：

bool isEnabled = await Crashes.IsEnabledAsync();

Unity 中已處理的例外狀況

App Center 也可讓您使用 Unity 中已處理的例外狀況來追蹤錯誤。 若要這樣做，請使用 TrackError 方法：

try {
    // your code goes here.
} catch (Exception exception) {
    Crashes.TrackError(exception);
}

如需錯誤的相關進一步內容，您也可以將屬性附加至該錯誤。 傳遞屬性做為字串的字典。 此步驟是選用的。

try {
    // your code goes here.
} catch (Exception exception) {
    var properties = new Dictionary<string, string>
    {
        { "Category", "Music" },
        { "Wifi", "On" }
    };
    Crashes.TrackError(exception, properties);
}

您也可以選擇性地將二進位和文字附件新增至已處理的錯誤報告。 傳遞附件做為 對象的陣列 ErrorAttachmentLog ，如下列範例所示。

try {
    // your code goes here.
} catch (Exception exception) {
    var attachments = new ErrorAttachmentLog[]
    {
        ErrorAttachmentLog.AttachmentWithText("Hello world!", "hello.txt"),
        ErrorAttachmentLog.AttachmentWithBinary(Encoding.UTF8.GetBytes("Fake image"), "fake_image.jpeg", "image/jpeg")
    };
    Crashes.TrackError(exception, attachments: attachments);
}

Unity 中未處理的例外狀況

報告未處理的例外狀況

根據預設，App Center SDK 不會回報應用程式中擲回的未處理例外狀況，而不會造成嚴重損毀。 若要啟用這項功能，請呼叫下列方法：

Crashes.ReportUnhandledExceptions(true);

呼叫此 API 之後，App Center 會將所有未處理的例外狀況記錄為 App Center 入口網站中的問題，類似於先前所述的已處理例外狀況。 若要停用這項功能，請呼叫與 參數傳遞 false 相同的 API。

Crashes.ReportUnhandledExceptions(false);

注意

App Center SDK 偵測到的某些未處理的例外狀況會在 App Center UI 中顯示為錯誤。 這是因為 Unity 預設會攔截未處理的例外狀況，這表示應用程式不會結束且不會被視為當機。

將附件新增至未處理的例外狀況報告

根據預設，App Center SDK 不會在未處理的例外狀況上啟用附件。 若要啟用這項功能，請將 enableAttachmentsCallback 方法的 ReportUnhandledExceptions 布林參數設定為 true：

Crashes.ReportUnhandledExceptions(true, true);

然後，您可以藉由實作 GetErrorAttachments 回呼 ，選擇性地將附件新增至未處理的例外狀況報告。

報告 NDK 當機

報告當機

若要在 App Center 中接收適當的當機報告，請先依照上述指示，確定您已設定 App Center 當機 SDK。

建置斷板連結庫

接下來，您必須遵循 官方 Google Breakpad for Android 自述檔所列的指示來包含及編譯 Google Breakpad。 若要在 Unity 中使用，請將二進位檔包含在您的應用程式中。

注意

App Center SDK 預設不會組合 Google Breakpad。

附加例外狀況處理程式

一旦您包含Google Breakpad，請附加NDK損毀處理程式：

/* Attach NDK Crash Handler. */
var minidumpDir = Crashes.GetMinidumpDirectoryAsync();
setupNativeCrashesListener(minidumpDir.Result);

...

[DllImport("YourLib")]
private static extern void setupNativeCrashesListener(string path);

方法 setupNativeCrashesListener 是您必須在 C/C++ 中實作的原生方法：

#include <android/log.h>
#include "google-breakpad/src/client/linux/handler/exception_handler.h"
#include "google-breakpad/src/client/linux/handler/minidump_descriptor.h"

static google_breakpad::ExceptionHandler exception_handler(google_breakpad::MinidumpDescriptor(), NULL, dumpCallback, NULL, true, -1);

/**
 * Registers breakpad as the exception handler for NDK code.
 * @param path minidump directory path returned from Crashes.GetMinidumpDirectoryAsync()
 */
extern "C" void setupNativeCrashesListener(const char *path) {
    google_breakpad::MinidumpDescriptor descriptor(path);
    exception_handler.set_minidump_descriptor(descriptor);
}

其中 dumpCallback 用於疑難解答：

/*
 * Triggered automatically after an attempt to write a minidump file to the breakpad folder.
 */
static bool dumpCallback(const google_breakpad::MinidumpDescriptor &descriptor,
                         void *context,
                         bool succeeded) {

    /* Allow system to log the native stack trace. */
    __android_log_print(ANDROID_LOG_INFO, "YourLogTag",
                        "Wrote breakpad minidump at %s succeeded=%d\n", descriptor.path(),
                        succeeded);
    return false;
}

正確設定這些方法之後，應用程式會在重新啟動時自動將迷你傾印傳送至 App Center。 若要進行疑難解答，您可以使用詳細資訊記錄來檢查應用程式重新啟動後是否傳送迷你記錄。

注意

App Center 會使用迷你傾印附件的保留名稱 minidump.dmp 。 除非您是迷你傾印檔案，否則請務必為附件提供不同的名稱，以便我們可以正確處理。

警告

斷板中有已知的 Bug，因此無法在 x86 模擬器上擷取損毀。

符號

如需有關損毀處理的詳細資訊，請參閱 診斷檔 。