App Center 損毀 (Android)

App Center 損毀會在每次應用程式損毀時自動產生損毀記錄檔。 記錄檔會先寫入裝置的儲存體,當使用者再次啟動應用程式時,會將損毀報告傳送至 App Center。 收集在 Beta 版和即時應用程式(也就是提交給 Google Play 的損毀)都能正常運作。 損毀記錄檔包含可協助您修正損毀的重要資訊。

如果您還沒有在應用程式中設定 SDK,請遵循 開始使用 一節。

產生測試損毀

App Center 損毀提供您 API 來產生測試損毀,以便輕鬆地測試 SDK。 此 API 只能用在 debug 組建中,而且不會在發行組建中進行任何動作。

Crashes.generateTestCrash();
Crashes.generateTestCrash()

取得有關先前損毀的詳細資訊

App Center 損毀有兩個 Api,可提供您應用程式損毀時的詳細資訊。

應用程式是否在前一個會話中收到記憶體不足的警告?

啟動 SDK 之後,您可以隨時檢查應用程式是否在前一個會話中收到記憶體警告:

Crashes.hasReceivedMemoryWarningInLastSession();
Crashes.hasReceivedMemoryWarningInLastSession()

此 API 是非同步,您可以在我們的 App Center 非同步 api 指南中閱讀更多相關資訊。

注意

只有在啟動之後,才會使用這個方法 Crashes ,在開始之前,它一定會傳回 false

注意

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

應用程式是否在前一個會話中損毀?

啟動 SDK 之後,您可以隨時檢查應用程式在上一次啟動時是否損毀:

Crashes.hasCrashedInLastSession();
Crashes.hasCrashedInLastSession()

此 API 是非同步,您可以在我們的 App Center 非同步 api 指南中閱讀更多相關資訊。

如果您想要在發生損毀之後調整應用程式的行為或 UI,這會很有用。 有些開發人員選擇對他們的使用者顯示額外的 UI,或想要在發生損毀之後取得觸控的方式。

注意

只有在啟動之後,才會使用這個方法 Crashes ,在開始之前,它一定會傳回 false

上次損毀的詳細資料

如果您的應用程式先前已損毀,您可以取得最後一個損毀的詳細資料。

Crashes.getLastSessionCrashReport();
Crashes.getLastSessionCrashReport()

此 API 是非同步,您可以在我們的 App Center 非同步 api 指南中閱讀更多相關資訊。

此 API 有許多使用案例,最常見的是呼叫此 API 並執行其自訂 CrashesListener的人員。

注意

只有在啟動之後,才會使用這個方法 Crashes ,在開始之前,它一定會傳回 null

自訂您的 App Center 損毀使用狀況

App Center 損毀提供回呼,讓開發人員在將損毀記錄傳送至 App Center 之前和之後執行其他動作。

若要處理回呼,請在介面中執行所有方法 CrashesListener ,或覆寫 AbstractCrashesListener 類別,只挑選您感興趣的類別。

使用您自己的 CrashesListener

建立您自己的 CrashesListener,並將其指派如下:

CrashesListener customListener = new CrashesListener() {
    // Implement all callbacks here.
};
Crashes.setListener(customListener);
val customListener = object : CrashesListener {
    // Implement all callbacks here.
}
Crashes.setListener(customListener)

如果您只想要自訂某些回呼,請 AbstractCrashesListener 改用:

AbstractCrashesListener customListener = new AbstractCrashesListener() {
    // Implement any callback here as required.
};
Crashes.setListener(customListener);
val customListener = object : AbstractCrashesListener() {
    // Implement any callback here as required.
}
Crashes.setListener(customListener)

注意

在呼叫 之前 設定接聽 AppCenter.start() 程式,因為 App Center 會在啟動後立即開始處理損毀。

是否應該處理損毀?

如果您想要決定是否需要處理特定的損毀,請執行此回呼。 例如,可能會有您想要忽略的系統層級損毀,而且您不想要傳送到 App Center。

@Override
public boolean shouldProcess(ErrorReport report) {
    return true; // return true if the crash report should be processed, otherwise false.
}
override fun shouldProcess(report: ErrorReport?): Boolean {
    return true
}

如果使用者隱私權對您很重要,您可能會想要在將損毀報告傳送至 App Center 之前確認使用者。 SDK 會公開回呼,以在傳送任何損毀報告之前,讓 App Center 損毀等待使用者確認。

如果您選擇這麼做,您必須負責取得使用者的確認,例如透過使用下列其中一個選項的對話提示: [ 一律傳送]、[ 傳送] 和 [ 不要傳送]。 根據輸入,您將告知 App Center 損毀要進行的工作,然後將會據此處理損毀。

注意

SDK 不會顯示對話方塊,應用程式必須提供自己的 UI,要求使用者同意。

下列回呼顯示如何告知 SDK 在傳送損毀之前等候使用者確認:

@Override
public boolean 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;
}
override fun shouldAwaitUserConfirmation(): Boolean {
    return true
}

如果您傳回 true ,您的應用程式必須使用您自己的程式碼來取得 () 使用者的許可權,並使用下列 API 將 SDK 與結果訊息:

// Depending on the user's choice, call Crashes.notifyUserConfirmation() with the right value.
Crashes.notifyUserConfirmation(Crashes.DONT_SEND);
Crashes.notifyUserConfirmation(Crashes.SEND);
Crashes.notifyUserConfirmation(Crashes.ALWAYS_SEND);
Crashes.notifyUserConfirmation(Crashes.DONT_SEND)
Crashes.notifyUserConfirmation(Crashes.SEND)
Crashes.notifyUserConfirmation(Crashes.ALWAYS_SEND)

例如,您可以參考我們的 自訂對話方塊範例

取得損毀記錄檔的傳送狀態相關資訊

有時,您會想要知道應用程式損毀的狀態。 常見的使用案例是,您可能會想要顯示 UI,告訴使用者您的應用程式正在提交損毀報告,或者,如果您的應用程式在啟動後快速當機,則您想要調整應用程式的行為,以確保可以提交損毀記錄。 App Center 損毀有三個不同的回呼,您可以在應用程式中使用這些回呼來通知發生的狀況:

在 SDK 傳送損毀記錄檔之前,將會叫用下列回呼

@Override
public void onBeforeSending(ErrorReport errorReport) {
    // Your code, e.g. to present a custom UI.
}
override fun onBeforeSending(report: ErrorReport?) {
    // Your code, e.g. to present a custom UI.
}

如果我們有網路問題或端點中斷,而您重新開機應用程式, onBeforeSending 則會在進程重新開機後再次觸發。

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

@Override
public void onSendingSucceeded(ErrorReport report) {
    // Your code, e.g. to hide the custom UI.
}
override fun onSendingSucceeded(report: ErrorReport?) {
    // Your code, e.g. to hide the custom UI.
}

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

@Override
public void onSendingFailed(ErrorReport report, Exception e) {
    // Your code goes here.
}
override fun onSendingFailed(report: ErrorReport?, e: Exception?) {
    // Your code goes here.
}

接收 onSendingFailed 表示無法復原的錯誤,例如發生 4xx 程式碼。 例如, 401 表示 appSecret 錯誤。

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

將附件新增至損毀報告

您可以將二進位檔和文字附件新增至損毀報表。 SDK 會將它們連同損毀一起傳送,讓您可以在 App Center 入口網站中看到它們。 從先前的應用程式啟動傳送儲存的損毀之前,將會叫用下列回呼。 當發生損毀時,不會叫用它。 請確定附件檔案 命名 minidump.dmp ,因為該名稱已保留給小型傾印檔案。 以下是如何將文字和影像附加至損毀的範例:

@Override
public Iterable<ErrorAttachmentLog> getErrorAttachments(ErrorReport report) {

    // Attach some text.
    ErrorAttachmentLog textLog = ErrorAttachmentLog.attachmentWithText("This is a text attachment.", "text.txt");

    // Attach binary data.
    byte[] binaryData = getYourBinary();
    ErrorAttachmentLog binaryLog = ErrorAttachmentLog.attachmentWithBinary(binaryData, "your_filename.jpeg", "image/jpeg");

    // Return attachments as list.
    return Arrays.asList(textLog, binaryLog);
}
override fun getErrorAttachments(report: ErrorReport?): MutableIterable<ErrorAttachmentLog> {

    // Attach some text.
    val textLog = ErrorAttachmentLog.attachmentWithText("This is a text attachment.", "text.txt")

    // Attach binary data.
    val binaryData = getYourBinary()
    val binaryLog = ErrorAttachmentLog.attachmentWithBinary(binaryData, "your_filename.jpeg", "image/jpeg")

    // Return attachments as list.
    return listOf(textLog, binaryLog)
}

注意

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

啟用或停用在執行時間的 App Center 損毀

您可以在執行時間啟用和停用 App Center 損毀。 如果您停用它,SDK 將不會對應用程式進行任何損毀報告。

Crashes.setEnabled(false);
Crashes.setEnabled(false)

若要再次啟用 App Center 損毀,請使用相同的 API,但以 true 參數形式傳遞。

Crashes.setEnabled(true);
Crashes.setEnabled(true)

狀態會保存在應用程式啟動之間的裝置儲存區中。

此 API 是非同步,您可以在我們的 App Center 非同步 api 指南中閱讀更多相關資訊。

注意

只有在啟動之後,才必須使用這個方法 Crashes

檢查是否已啟用 App Center 損毀

您也可以檢查是否已啟用 App Center 損毀:

Crashes.isEnabled();
Crashes.isEnabled()

此 API 是非同步,您可以在我們的 App Center 非同步 api 指南中閱讀更多相關資訊。

注意

只有在啟動之後,才會使用這個方法 Crashes ,在開始之前,它一定會傳回 false

處理的錯誤

App Center 也可讓您使用已處理的例外狀況來追蹤錯誤。 若要這樣做,請使用 trackError 方法:

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

應用程式可以選擇性地將屬性附加至已處理的錯誤報表,以提供進一步的內容。 將屬性做為索引鍵/值組的對應傳遞 (字串) ,如下列範例所示。

try {
    // your code goes here.
} catch (Exception exception) {
    Map<String, String> properties = new HashMap<String, String>() {{
        put("Category", "Music");
        put("Wifi", "On");
    }};
    Crashes.trackError(exception, properties, null);
}
try {
    // your code goes here.
} catch (exception: Exception) {
    val properties = mapOf("Category" to "Music", "Wifi" to "On")
    Crashes.trackError(exception, properties, null)
}

您也可以選擇性地將二進位和文字附件新增至已處理的錯誤報表。 將附件傳遞為, Iterable 如下列範例所示。

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

    // Attach some text.
    ErrorAttachmentLog textLog = ErrorAttachmentLog.attachmentWithText("This is a text attachment.", "text.txt");

    // Attach binary data.
    byte[] binaryData = getYourBinary();
    ErrorAttachmentLog binaryLog = ErrorAttachmentLog.attachmentWithBinary(binaryData, "your_filename.jpeg", "image/jpeg");

    // Track an exception with attachments.
    Crashes.trackError(exception, null, Arrays.asList(textLog, binaryLog));
}
try {
    // your code goes here.
} catch (exception: Exception) {

    // Attach some text.
    val textLog = ErrorAttachmentLog.attachmentWithText("This is a text attachment.", "text.txt")

    // Attach binary data.
    val binaryData = getYourBinary()
    val binaryLog = ErrorAttachmentLog.attachmentWithBinary(binaryData, "your_filename.jpeg", "image/jpeg")

    // Track an exception with attachments.
    Crashes.trackError(exception, null, listOf(textLog, binaryLog))
}

報告 NDK 當機

報告當機

若要在 App Center 中接收適當的損毀報告,請先確定您已遵循上述的指示設定 App Center 損毀 SDK。

建立 breakpad 程式庫

接下來,遵循官方 Google Breakpad For ANDROID 讀我檔案中所列的指示,來納入及編譯 Google Breakpad。

注意

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

附加例外狀況處理常式

包含 Google Breakpad 之後,請在下列情況之後附加 NDK 損毀處理常式 AppCenter.start

// Attach NDK Crash Handler after SDK is initialized.
Crashes.getMinidumpDirectory().thenAccept(new AppCenterConsumer<String>() {
    @Override
    public void accept(String path) {

        // Path is null when Crashes is disabled.
        if (path != null) {
            setupNativeCrashesListener(path);
        }
    }
});

方法 setupNativeCrashesListener 是您必須在 C/c + + 中執行的原生方法:

#include "google-breakpad/src/client/linux/handler/exception_handler.h"
#include "google-breakpad/src/client/linux/handler/minidump_descriptor.h"

void Java_com_microsoft_your_package_YourActivity_setupNativeCrashesListener(
        JNIEnv *env, jobject, jstring path) {
    const char *dumpPath = (char *) env->GetStringUTFChars(path, NULL);
    google_breakpad::MinidumpDescriptor descriptor(dumpPath);
    new google_breakpad::ExceptionHandler(descriptor, NULL, dumpCallback, NULL, true, -1);
    env->ReleaseStringUTFChars(path, dumpPath);
}

dumpCallback用於疑難排解的位置:

/*
 * Triggered automatically after an attempt to write a minidump file to the breakpad folder.
 */
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。 若要進行疑難排解,您可以在) 之前使用詳細資訊記錄 (, AppCenter.setLogLevel(Log.VERBOSE) AppCenter.start 檢查小型傾印是否在應用程式重新開機之後傳送。

注意

App Center 會針對小型傾印附件使用保留名稱 minidump.dmp 。 請務必將您的附件命名為不同的名稱,除非它是小型傾印檔案,以便我們能夠正確處理。

注意

Breakpad 中有一個已知的錯誤,這使得在 x86 模擬器上無法捕捉損毀。

符號化

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