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 堆疊追蹤。

注意

最佳做法是避免具有字串值的 JavaScript throw 語句 (例如: 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 在啟動後快速當機,您想要調整應用程式的行為,以確保可以提交當機記錄。 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.
});

所有回呼都是選擇性的。 您不需要在事件接聽程式物件中提供所有 3 個方法,例如,您只能 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 函式,請改為傳回已完成的 Promise。 下列範例會以非同步方式將文字和影像附加至當機:

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);
}

分欄

App Center 支援在React Native應用程式中,從 Android NDK 損毀的斷欄。

遵循上述的一般設定步驟,並在覆 MainActivity.javaOnCreate 中新增迷你傾印組態,並呼叫您的機器碼,以設定您的 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();