App Center のクラッシュ (Unity)
重要
Visual Studio App Center は、2025 年 3 月 31 日に廃止される予定です。 完全に廃止されるまで Visual Studio App Center を引き続き使用できますが、移行を検討できる推奨される代替手段がいくつかあります。
App Center のクラッシュでは、アプリがクラッシュするたびにクラッシュ ログが自動的に生成され、デバイス ストレージへのログが生成されます。 ユーザーがアプリを再度起動すると、SDK によってクラッシュ レポートが App Center に送信されます。 クラッシュの収集は、ベータ版アプリとライブ アプリの両方で機能します。つまり、Google Play に送信されたクラッシュです。 クラッシュ ログには、クラッシュの修正に役立つ重要な情報が含まれています。
アプリケーションで SDK をまだ設定していない場合は、「Unity はじめに」セクションの手順に従います。
iOS のクラッシュ ログにはシンボリック化が必要です。 シンボリック化を有効にするには、 App Center 診断に関するドキュメントを参照してください。このドキュメントでは、アプリのシンボルを指定する方法について説明しています。
重要
Unity 用のクラッシュ SDK では、UWP はサポートされていません。 このページの手順では、Android と iOS についてのみ説明します。
注意
デバッガーをアタッチした場合、SDK はクラッシュ ログを転送しません。 アプリをクラッシュさせたときにデバッガーがアタッチされていないことを確認します。
注意
PlayerSettings で有効にしたEnable CrashReport API
場合、SDK はクラッシュ ログを収集しません。
App Center のクラッシュには、SDK を簡単にテストするためのテスト クラッシュを生成する API が用意されています。 この API は、デバッグ構成とリリース構成をチェックします。 そのため、リリース アプリでは機能しないため、デバッグ時にのみ使用できます。
Crashes.GenerateTestCrash();
注意
このメソッドは、 開発ビルド の設定が有効になっている場合にのみ機能します。
App Center のクラッシュには、アプリがクラッシュした場合に備えて詳細情報を提供する 2 つの API があります。
SDK を開始した後は、いつでも、アプリが前のセッションでメモリ警告を受信したかどうかをチェックできます。
bool hadLowMemoryWarning = Crashes.HasReceivedMemoryWarningInLastSessionAsync().Result;
注意
このメソッドは では Awake()
機能しません。
注意
場合によっては、メモリが不足しているデバイスでイベントを送信できない場合があります。
SDK を起動した後は、いつでも、前の起動でアプリがクラッシュした場合にチェックできます。
bool didAppCrash = await Crashes.HasCrashedInLastSessionAsync();
呼び出し HasCrashedInLastSessionAsync
は、クラッシュが発生した後にアプリの動作または UI を調整する場合に便利です。 一部の開発者は、ユーザーに申し訳ない UI を表示したり、クラッシュが発生した後に連絡を取ったりします。
アプリが以前にクラッシュした場合は、最後のクラッシュに関する詳細を取得できます。
ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();
この API の最も一般的なユース ケースは、ユーザーがカスタム のクラッシュ デリゲートまたはリスナーを実装している場合です。
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 のクラッシュに指示するコールバックを公開します。
コードでこのコールバックを使用する場合は、ユーザーの確認を取得する責任があります。 1 つのオプションは、ダイアログ プロンプトを使用して、[常に送信]、[送信]、[送信しない] のいずれかのオプションを使用する方法です。 入力に基づいて、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 を表示することです。 もう 1 つのシナリオは、再起動後すぐにクラッシュ ログを送信できるようにアプリの動作を調整する場合です。 App Center のクラッシュには、何が行われたかを通知するために行うことができる 3 つの異なるコールバックが用意されています。
Crashes.SendingErrorReport += (errorReport) =>
{
// Your code, e.g. to present a custom UI.
};
エンドポイントでネットワークの問題や停止が発生し、アプリを再起動した場合は、 SendingErrorReport
プロセスの再起動後に再度トリガーされます。
Crashes.SentErrorReport += (errorReport) =>
{
// Your code, e.g. to hide the custom UI.
};
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 のクラッシュを有効または無効にすることができます。 無効にした場合、SDK はアプリのクラッシュ レポートを実行しません。
Crashes.SetEnabledAsync(false);
App Center のクラッシュを再度有効にするには、同じ API を使用しますが、 パラメーターとして を渡 true
します。
Crashes.SetEnabledAsync(true);
他の API 呼び出し (など IsEnabledAsync
) を一貫性のあるものにするために、この呼び出しを待機する必要はありません。
状態は、アプリケーションの起動間でデバイスのストレージに保持されます。
App Center のクラッシュが有効になっているかどうかをチェックすることもできます。
bool isEnabled = await Crashes.IsEnabledAsync();
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);
}
既定では、App Center SDK では、致命的なクラッシュを引き起こさない、アプリでスローされた未処理の例外は報告されません。 この機能を有効にするには、次のメソッドを呼び出します。
Crashes.ReportUnhandledExceptions(true);
この API を呼び出した後、App Center では、前述の処理された例外と同様に、すべての未処理の例外が App Center ポータルの問題としてログに記録されます。 この機能を無効にするには、 パラメーターと同じ API パッシング false
を呼び出します。
Crashes.ReportUnhandledExceptions(false);
注意
App Center SDK によって検出された一部のハンドルされない例外は、App Center UI にエラーとして表示されます。 これは、Unity が既定でハンドルされない例外をキャッチするためです。つまり、アプリは終了せず、クラッシュとは見なされません。
既定では、App Center SDK では、未処理の例外に対する添付ファイルは有効になりません。 この機能を有効にするには、 メソッドの enableAttachmentsCallback
ブール値パラメーターを ReportUnhandledExceptions
に true
設定します。
Crashes.ReportUnhandledExceptions(true, true);
必要に応じて 、GetErrorAttachments コールバックを実装することで、ハンドルされない例外レポートに添付ファイルを追加できます。
App Center で適切なクラッシュ レポートを受信するには、まず、上記の手順に従って、App Center クラッシュ SDK が設定されていることを確認します。
次に、Android README 用の公式 Google Breakpad に記載されている手順に従って 、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
が使用されます。 適切に処理できるように、添付ファイルがミニダンプ ファイルでない限り、添付ファイルに別の名前を付けてください。
警告
ブレークパッドには既知のバグがあり、x86 エミュレーターでクラッシュをキャプチャできなくなります。
クラッシュの処理の詳細については、診断に関する ドキュメントを参照してください 。