App Center 오류(Unity 게임용)

중요합니다

Visual Studio App Center는 2026년 6월 30일까지 계속 지원되는 분석 및 진단 기능을 제외하고 2025년 3월 31일에 사용 중지되었습니다. 자세히 알아보기.

• 안드로이드
• iOS
• MAUI/Xamarin
• UWP
• WPF/WinForms
• React Native
• macOS
• tvOS
• 유니티

App Center Crashes는 앱이 충돌할 때마다 자동으로 충돌 로그를 생성하고, 이 로그를 디바이스 저장소에 저장합니다. 사용자가 앱을 다시 시작하면 SDK는 App Center에 크래시 보고서를 보냅니다. 크래시 수집은 베타 앱과 라이브 앱 모두에서 작동합니다. 즉, Google Play에 제출된 크래시에도 적용됩니다. 크래시 로그에는 충돌을 해결하는 데 도움이 되는 중요한 정보가 포함되어 있습니다.

애플리케이션에서 SDK를 아직 설정하지 않은 경우 Unity 시작 섹션의 지침을 따릅니다.

iOS의 충돌 로그에는 기호화가 필요합니다. 기호화를 사용하도록 설정하려면 앱에 대한 기호를 제공하는 방법을 설명하는 App Center 진단 설명서를 참조하세요.

중요합니다

Unity용 크래시 SDK는 UWP를 지원하지 않습니다. 이 페이지의 지침은 Android 및 iOS만 다룹니다.

비고

디버거를 연결한 경우 SDK는 충돌 로그를 전달하지 않습니다. 앱을 크래시할 때 디버거가 연결되지 않았는지 확인합니다.

비고

Enable CrashReport API에서 사용하도록 설정한 경우 SDK는 충돌 로그를 수집하지 않습니다.

테스트 크래시 생성

App Center Crashes 기능은 SDK를 쉽게 테스트할 수 있도록 테스트 크래시를 생성하는 API를 제공합니다. 이 API는 디버그 및 릴리스 구성을 확인합니다. 따라서 릴리스 앱에서 작동하지 않으므로 디버깅할 때만 사용할 수 있습니다.

Crashes.GenerateTestCrash();

비고

이 메서드는 개발 빌드 설정이 켜져 있는 경우에만 작동합니다.

이전 충돌에 대한 자세한 정보 가져오기

App Center 크래시에는 앱이 충돌하는 경우에 더 많은 정보를 제공하는 두 개의 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 Crashes는 개발자가 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 Crashs에 지시하는 콜백을 노출합니다.

코드에서 이 콜백을 사용하는 경우 사용자의 확인을 받아야 합니다. 한 가지 옵션은 대화 상자 프롬프트를 통해 Always Send, Send 및 Don't send 옵션 중 하나를 사용하는 것입니다. 입력에 따라 App Center Crashes에 실행할 작업을 지시하면, 그에 따라 크래시가 적절히 처리됩니다.

비고

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를 표시하는 것입니다. 또 다른 시나리오는 다시 시작한 직후 크래시 로그를 제출할 수 있도록 앱의 동작을 조정하려는 경우입니다. App Center 크래시에서는 어떤 일이 발생했는지를 알리기 위해 이용할 수 있는 세 가지의 다른 콜백을 제공합니다.

다음 콜백은 SDK가 크래시 로그를 보내기 전에 호출됩니다.

Crashes.SendingErrorReport += (errorReport) =>
{
    // Your code, e.g. to present a custom UI.
};

엔드포인트에 네트워크 문제나 장애가 발생하여 앱을 SendingErrorReport 재시작하면, 프로세스가 다시 시작될 때 SendingErrorReport가 다시 트리거됩니다.

다음 콜백은 SDK가 크래시 로그를 성공적으로 보낸 후에 호출됩니다.

Crashes.SentErrorReport += (errorReport) =>
{
    // Your code, e.g. to hide the custom UI.
};

SDK에서 크래시 로그를 보내지 못한 경우 다음 콜백이 호출됩니다.

Crashes.FailedToSendErrorReport += (errorReport, exception) =>
{
    // Your code goes here.
};

수신은 FailedToSendErrorReport4xx 코드와 같은 복구할 수 없는 오류가 발생했음을 의미합니다. 예를 들어 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입니다.

비고

크기 제한은 현재 7MB의 첨부 파일에 대한 것입니다. 더 큰 첨부 파일을 보내려고 하면 오류가 트리거됩니다.

비고

GetErrorAttachments 는 주 스레드에서 호출되며 프레임에 대해 작업을 분할하지 않습니다. 게임 루프를 차단하지 않으려면 이 콜백에서 장기 실행 작업을 수행하지 마세요.

런타임에 App Center 충돌 사용 또는 사용 안 함

런타임에 App Center 크래시 기능을 사용하거나 사용하지 않도록 설정할 수 있습니다. 사용하지 않도록 설정하면 SDK는 앱에 대한 크래시 보고를 수행하지 않습니다.

Crashes.SetEnabledAsync(false);

App Center Crashes를 다시 활성화하려면 동일한 API를 사용하되, 매개 변수로 true을(를) 전달합니다.

Crashes.SetEnabledAsync(true);

다른 API 호출(예: IsEnabledAsync와 같은)을 일관되게 만들기 위해 이 호출을 기다릴 필요가 없습니다.

상태는 애플리케이션 시작 시 디바이스의 스토리지에 유지됩니다.

App Center 크래시가 사용하도록 설정되어 있는지 확인

App Center 크래시가 사용하도록 설정되어 있는지 여부도 확인할 수 있습니다.

bool isEnabled = await Crashes.IsEnabledAsync();

Unity에서 처리된 예외들

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

Unity에서 처리되지 않은 예외

처리되지 않은 예외 보고

기본적으로 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 콜백을 구현하여 처리되지 않은 예외 보고서에 첨부 파일을 추가할 수 있습니다.

NDK 충돌 보고

충돌 보고

App Center에서 적절한 크래시 보고서를 받으려면 먼저 위에 나열된 지침에 따라 App Center 충돌 SDK를 설정했는지 확인합니다.

Breakpad 라이브러리 빌드

다음으로, Android 추가 정보용 공식 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 에뮬레이터에서 충돌을 캡처할 수 없게 만드는 알려진 버그가 있습니다.

기호화

충돌 처리에 대한 자세한 내용은 진단 설명서를 참조하세요.