Crash handling for Unity applications on Android works as a chain of crash handlers. The crash handler at the start of the chain receives the crash first and it can process the crash and also forward the crash to the next crash handler in the chain. The order of the crash handlers in the chain is defined by the order in which they’re installed. The crash handler installed first is the last one to receive the crash and the crash handler installed last is the first one to receive the crash. By default, Unity acts as the first crash handler in the chain. It processes crashes and forwards them to the next crash handler in the chain, which is the Android system crash handler by default.
You can configure Unity to react differently to crashes and also add your own custom crash handler to the chain. This page explains how to specify the method Unity uses to handle crashes and how to create a custom crash handler.
If you don’t want to use Unity’s default crash handling behavior, you can use the -androidChainedSignalHandlerBehavior
command-line argument to change how Unity reacts to crashes. This argument takes one of the following values:
Behavior value | 説明 |
---|---|
legacy |
When a native crash occurs, Unity wraps and throws the crash as a java exception. Unity doesn’t forward the crash to the any installed crash handlers or to the default system. Note: In the future Unity versions, -androidChainedSignalHandlerBehavior command-line argument will no longer support legacy value. |
disabled |
When a native crash occurs, Unity ignores it and Android forwards the crash directly to the next crash handler in the chain. This is either a custom crash handler, if one is installed, or the default system if not. Note: If you use this value, Unity services such as Unity Cloud Diagnostics no longer handle crashes and won’t report them. |
For information on how to pass this command-line argument to Unity, refer to Specify Android Player command-line arguments.
This section contains an example of how to create and set up your own crash handler. For this to work, you must not use Unity’s legacy crash handling behavior. For more information, refer to Specify how Unity handles crashes.
The following code sample shows a custom crash handler. If you use the IL2CPP scripting backend, you can place this example cpp
file directly into your Unity project. Unity then compiles it as part of libil2cpp.cpp
. If you use the Mono scripting backend, you must compile and link your own shared library. For more information, refer to Create a native plug-in for Android.
android_crash_handler.cpp
#include <android/log.h>
#include <jni.h>
#include <signal.h>
struct sigaction s_PreviousHandler;
bool s_SignalHandlerInstalled;
static void MyCustomHandler(int sig, siginfo_t* info, void* ucontext)
{
__android_log_print(ANDROID_LOG_VERBOSE, "CustomCrashHandler", "Handling signal %d", sig);
s_PreviousHandler.sa_sigaction(sig, info, ucontext);
}
extern "C" void InstallCustomSignalHandlers()
{
struct sigaction Action = {};
Action.sa_sigaction = MyCustomHandler;
// Note: Register more signals if you want.
Action.sa_flags = SIGSEGV;
sigaction(SIGSEGV, &Action, &s_PreviousHandler);
s_SignalHandlerInstalled = true;
}
extern "C" JNIEXPORT void Java_com_unity3d_player_UnityPlayerActivity_InstallCustomSignalHandlersFromJava()
{
InstallCustomSignalHandlers();
}
extern "C" void UninstallCustomSignalHandlers()
{
if (s_SignalHandlerInstalled)
{
sigaction(SIGSEGV, &s_PreviousHandler, nullptr);
s_SignalHandlerInstalled = false;
}
}
To install the crash handler and have Unity use it to handle crashes, call the InstallCustomSignalHandlers
method in the above cpp
file. You can do this either through C# or Java code, however it’s best practice to call this method from Java, because a crash can occur after the Unity Player initializes, but before your C# code runs.
The following code sample shows how to call the InstallCustomSignalHandlers
method from Java code. To add it to your project, you can either install the Java file as a plug-in (refer to Create a Java or Kotlin source plug-in) or you can modify an existing Java file in an exported project.
Note: Depending on where you call this method, it changes the behavior of crash handling. If you call it before Unity runtime initialization, which is a line of code that contains mUnityPlayer = new UnityPlayer(this, this);
, then during the native crash Unity’s crash handler is executed first and then your signal handler is executed (if Unity forwards the signal). If you call InstallCustomSignalHandlers
after Unity runtime initialization, then during the native crash your handler is executed first and it’s your responsibility to forward the signal.
UnityPlayerActivity.java
...
public native void InstallCustomSignalHandlersFromJava();
static
{
System.loadLibrary("il2cpp");
}
// Setup activity layout
@Override protected void onCreate(Bundle savedInstanceState)
{
InstallCustomSignalHandlersFromJava();
...
mUnityPlayer = new UnityPlayer(this, this);
setContentView(mUnityPlayer);
mUnityPlayer.requestFocus();
}
...
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.