App Center 當機 (React Native)

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

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

無論您在何處使用 App Center 當機,請在檔案頂端新增下列匯入。

// Import App Center Crashes at the top of the file.
import Crashes from 'appcenter-crashes';

產生測試損毀

App Center 損毀提供您 API 來產生測試損毀,以便輕鬆地測試 SDK。 此 API 僅適用于測試/Beta 應用程式,且不會在生產應用程式中執行任何動作。

Crashes.generateTestCrash();

也可以輕鬆地產生 JavaScript 損毀。 將下列程式程式碼新增至您的程式碼,此程式碼會擲回 JavaScript 錯誤並造成損毀。

throw new Error('This is a test javascript crash!');

提示

您的 React Native 應用程式必須在 發行模式 中編譯,此損毀才能傳送到 app Center。

注意

目前,App Center 不支援來源對應以美化適用于 Android React Native 應用程式的 JavaScript 堆疊追蹤。

注意

最佳做法是避免 throw 使用字串值的 JavaScript 語句 (例如: throw 'message') ,因為 React Native 在此案例中不會保留完整的 JavaScript 堆疊。 相反地, throw JavaScript Error (例如: throw Error('message')) 。

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

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

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

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

const hadLowMemoryWarning = await Crashes.hasReceivedMemoryWarningInLastSession();

注意

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

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

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

const didCrash = await Crashes.hasCrashedInLastSession();

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

上次損毀的詳細資料

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

const crashReport = await Crashes.lastSessionCrashReport();

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

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

在 JavaScript 中處理損毀

為了讓您的 Crash.setListener 方法如預期般運作,您必須檢查應用程式是否已正確設定。

  1. 開啟專案的檔案 ios/YourAppName/AppDelegate.m ,並確認您有 [AppCenterReactNativeCrashes register]; 而不是 [AppCenterReactNativeCrashes registerWithAutomaticProcessing];
  2. 開啟專案的檔案 android/app/src/main/res/values/strings.xml ,並確認 appCenterCrashes_whenToSendCrashes 已設定為 ASK_JAVASCRIPT

這份檔中的每個事件接聽程式都有不同的回呼,但您必須設定一個事件接聽項,同時定義所有回呼。

是否應該處理損毀?

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

Crashes.setListener({

    shouldProcess: function (report) {
        return true; // return true if the crash report should be processed, otherwise false.
    },

    // Other callbacks must also be defined at the same time if used.
    // Default values are used if a method with return parameter isn't defined.
});

注意

若要使用該功能,您必須為損毀服務設定適當的應用程式。

這項功能取決於 JavaScript 中的處理損毀。

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

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

注意

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

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

Crashes.setListener({

    shouldAwaitUserConfirmation: function (report) {

        // 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;
    },

    // Other callbacks must also be defined at the same time if used.
    // Default values are used if a method with return parameter isn't defined.
});

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

import Crashes, { UserConfirmation } from 'appcenter-crashes';

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

注意

若要使用這項功能,請為損毀服務設定適當的應用程式。 這項功能取決於 JavaScript 中的處理損毀。

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

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

若要這樣做,請在您的程式碼中定義事件接聽程式,如下列範例所示:

Crashes.setListener({
    onBeforeSending: function (report) {
        // called after Crashes.process and before sending the crash.
    },
    onSendingSucceeded: function (report) {
        // called when crash report sent successfully.
    },
    onSendingFailed: function (report) {
        // called when crash report couldn't be sent.
    }

    // Other callbacks must also be defined at the same time if used.
    // Default values are used if a method with return parameter isn't defined.
});

所有回呼都是選擇性的。 您不需要在事件接聽程式物件中提供這三種方法,例如,您只能執行 onBeforeSending

注意

若要使用該功能,您必須為損毀服務設定適當的應用程式。

這項功能取決於 JavaScript 中的處理損毀。

注意

如果 Crashes.setListener 呼叫一次以上,最後一個會獲勝; 它會覆寫先前設定的接聽程式 Crashes.setListener

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

如果這是網路問題,則不會觸發此回呼。 在此情況下,SDK 會持續重試 (,也會在網路連線) 時暫停重試。 如果我們有網路問題或端點中斷,而您重新開機應用程式, onBeforeSending 則會在進程重新開機後再次觸發。

將附件新增至損毀報告

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

import Crashes, { ErrorAttachmentLog } from 'appcenter-crashes';

Crashes.setListener({
    getErrorAttachments(report) {
        const textAttachment = ErrorAttachmentLog.attachmentWithText('Hello text attachment!', 'hello.txt');
        const binaryAttachment = ErrorAttachmentLog.attachmentWithBinary(`${imageAsBase64string}`, 'logo.png', 'image/png');
        return [textAttachment, binaryAttachment];
    }

    // Other callbacks must also be defined at the same time if used.
    // Default values are used if a method with return parameter isn't defined.
});

fileName參數是選擇性的 (可以 null) ,而且只能在 App Center 入口網站中使用。 從入口網站中的特定損毀情況,您可以看到附件並加以下載。 如果您指定檔案名,這會是要下載的檔案名,否則會為您產生檔案名。

若要設定 getErrorAttachments 回呼來使用 ES2017 async/await 函數,請改為傳回已履行的承諾。 下列範例會以非同步方式將文字和影像附加至損毀:

import Crashes, { ErrorAttachmentLog } from 'appcenter-crashes';

Crashes.setListener({
    getErrorAttachments(report) {
        return (async () => {
            const textContent = await readTextFileAsync(); // use your async function to read text file
            const binaryContent = await readBinaryFileAsync(); // use your async function to read binary file
            const textAttachment = ErrorAttachmentLog.attachmentWithText(textContent, 'hello.txt');
            const binaryAttachment = ErrorAttachmentLog.attachmentWithBinary(binaryContent, 'logo.png', 'image/png');
            return [textAttachment, binaryAttachment];
        })();
    }

    // Other callbacks must also be defined at the same time if used.
    // Default values are used if a method with return parameter isn't defined.
});

注意

若要使用該功能,您必須為損毀服務設定適當的應用程式。

這項功能取決於 JavaScript 中的處理損毀。

注意

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

處理的錯誤

App Center 也可讓您透過方法使用已處理的例外狀況來追蹤錯誤 trackError 。 應用程式可以選擇性地將屬性或/和附件附加至已處理的錯誤報表,以提供進一步的內容。

try {
    // Throw error.
} catch (error) {

    // Prepare properties.
    const properties = { 'Category' : 'Music', 'Wifi' : 'On' };

    // Prepare attachments.
    const textAttachment = ErrorAttachmentLog.attachmentWithText('Hello text attachment!', 'hello.txt');
    const attachments = [textAttachment];

    // Create an exception model from error.
    const exceptionModel1 = ExceptionModel.createFromError(error);

    // ..or generate with your own error data.
    const exceptionModel2 = ExceptionModel.createFromTypeAndMessage("type", "message", "stacktrace");

    // Track error with custom data.
    Crashes.trackError(exceptionModel1, properties, attachments);
    Crashes.trackError(exceptionModel1, properties, nil);
    Crashes.trackError(exceptionModel2, nil, attachments);
    Crashes.trackError(exceptionModel2, nil, nil);
}

Breakpad

App Center 支援在 React Native 應用程式中從 Android NDK Breakpad 損毀。

遵循上述的一般設定步驟,然後在您的覆 MainActivity.java 寫中 OnCreate 新增小型傾印設定,並呼叫原生程式碼來設定您的 Breakpad 設定。

範例:

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    Crashes.getMinidumpDirectory().thenAccept(new AppCenterConsumer<String>() {
      @Override
      public void accept(String path) {
        // Path is null when Crashes is disabled.
        if (path != null) {
          // links to NDK
          setupBreakpadListener(path);
        }
      }
    });
  }

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

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

await Crashes.setEnabled(false);

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

await Crashes.setEnabled(true);

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

檢查是否已啟用 App Center 損毀

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

const enabled = await Crashes.isEnabled();