Awarie usługi App Center (Unity)
Ważne
Program Visual Studio App Center ma zostać wycofany 31 marca 2025 r. Chociaż możesz nadal używać programu Visual Studio App Center do momentu jego pełnego wycofania, istnieje kilka zalecanych alternatyw, do których można rozważyć migrację.
Dowiedz się więcej o osiach czasu pomocy technicznej i alternatywach.
Awarie usługi App Center automatycznie generują dziennik awarii za każdym razem, gdy aplikacja ulega awarii, a dziennik do magazynu urządzeń. Gdy użytkownik ponownie uruchomi aplikację, zestaw SDK wysyła raport o awarii do Centrum aplikacji. Zbieranie awarii działa zarówno w przypadku aplikacji w wersji beta, jak i na żywo, czyli awarii przesłanych do sklepu Google Play. Dzienniki awarii zawierają cenne informacje ułatwiające naprawienie awarii.
Jeśli zestaw SDK nie został jeszcze skonfigurowany w aplikacji, postępuj zgodnie z instrukcjami w sekcji Wprowadzenie aparatu Unity.
Dzienniki awarii w systemie iOS wymagają symboliczności. Aby włączyć symbole, zapoznaj się z dokumentacją diagnostyki centrum aplikacji, w której wyjaśniono, jak udostępniać symbole aplikacji.
Ważne
Zestaw SDK awarii dla aparatu Unity nie obsługuje platformy UWP. Instrukcje na tej stronie obejmują tylko systemy Android i iOS.
Uwaga
Zestaw SDK nie będzie przekazywać żadnych dzienników awarii, jeśli dołączono debuger. Upewnij się, że debuger nie jest dołączony podczas awarii aplikacji.
Uwaga
Jeśli włączono Enable CrashReport API funkcję PlayerSettings, zestaw SDK nie będzie zbierać dzienników awarii.
Generowanie awarii testowej
Awarie usługi App Center udostępnia interfejs API do generowania awarii testowej w celu łatwego testowania zestawu SDK. Ten interfejs API sprawdza konfiguracje debugowania i wydania. Dlatego można go używać tylko podczas debugowania, ponieważ nie będzie działać w przypadku aplikacji wydań.
Crashes.GenerateTestCrash();
Uwaga
Ta metoda będzie działać tylko z włączonym ustawieniem kompilacji programistycznej .
Uzyskaj więcej informacji o poprzedniej awarii
Usługa App Center Crash ma dwa interfejsy API, które zapewniają więcej informacji na wypadek awarii aplikacji.
Czy aplikacja otrzymała ostrzeżenie o niskiej ilości pamięci w poprzedniej sesji?
W dowolnym momencie po uruchomieniu zestawu SDK możesz sprawdzić, czy aplikacja otrzymała ostrzeżenie o pamięci w poprzedniej sesji:
bool hadLowMemoryWarning = Crashes.HasReceivedMemoryWarningInLastSessionAsync().Result;
Uwaga
Ta metoda nie będzie działać w pliku Awake().
Uwaga
W niektórych przypadkach urządzenie z małą ilością pamięci nie może wysyłać zdarzeń.
Czy aplikacja uległa awarii w poprzedniej sesji?
W dowolnym momencie po uruchomieniu zestawu SDK możesz sprawdzić, czy aplikacja uległa awarii w poprzednim uruchomieniu:
bool didAppCrash = await Crashes.HasCrashedInLastSessionAsync();
Wywołanie HasCrashedInLastSessionAsync jest przydatne, jeśli chcesz dostosować zachowanie lub interfejs użytkownika aplikacji po wystąpieniu awarii. Niektórzy deweloperzy pokazują dodatkowy interfejs użytkownika, aby przeprosić swoich użytkowników lub skontaktować się po wystąpieniu awarii.
Szczegółowe informacje o ostatniej awarii
Jeśli aplikacja uległa awarii wcześniej, możesz uzyskać szczegółowe informacje o ostatniej awarii.
ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();
Najbardziej typowym przypadkiem użycia tego interfejsu API jest to, gdy użytkownik implementuje niestandardowy delegat lub odbiornik awarii.
Dostosowywanie użycia awarii usługi App Center
Awarie usługi App Center udostępniają deweloperom wywołania zwrotne umożliwiające wykonywanie dodatkowych akcji przed i po wysłaniu dzienników awarii do Centrum aplikacji.
Uwaga
Ustaw wywołanie zwrotne przed uruchomieniem usługi App Center, na przykład w Awake metodzie, ponieważ usługa App Center rozpoczyna przetwarzanie awarii natychmiast po uruchomieniu.
Czy awaria powinna zostać przetworzona?
Ustaw następujące wywołanie zwrotne, jeśli chcesz zdecydować, czy określona awaria musi zostać przetworzona, czy nie. Na przykład może wystąpić awaria na poziomie systemu, którą chcesz zignorować i nie wysłać do Centrum aplikacji.
Crashes.ShouldProcessErrorReport = (ErrorReport report) =>
{
// Check the report in here and return true or false depending on the ErrorReport.
return true;
};
Poproś użytkownika o zgodę na wysłanie dziennika awarii
Jeśli prywatność użytkownika jest dla Ciebie ważna, możesz uzyskać potwierdzenie użytkownika przed wysłaniem raportu o awarii do Centrum aplikacji. Zestaw SDK uwidacznia wywołanie zwrotne, które informuje usługę App Center o awarii w celu oczekiwania na potwierdzenie użytkownika przed wysłaniem raportów o awarii.
Jeśli kod używa tego wywołania zwrotnego, odpowiadasz za uzyskanie potwierdzenia użytkownika. Jedną z opcji jest wyświetlenie monitu dialogowego z jedną z następujących opcji: Zawsze wysyłaj, Wysyłaj i Nie wysyłaj. Na podstawie danych wejściowych poinformujesz centrum aplikacji o awarii, co należy zrobić, a awaria zostanie odpowiednio obsłużona.
Uwaga
Zestaw SDK nie wyświetla w tym celu okna dialogowego. Aplikacja musi podać własny interfejs użytkownika, aby poprosić o zgodę użytkownika.
Następujące wywołanie zwrotne pokazuje, jak poinformować zestaw SDK o oczekiwaniu na potwierdzenie użytkownika przed wysłaniem awarii:
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;
};
Jeśli wywołanie zwrotne zwróci truewartość , musisz uzyskać uprawnienia użytkownika i wyświetlić komunikat o zestawie SDK z wynikiem przy użyciu następującego interfejsu API:
// 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);
Przykładowy przykład można znaleźć w naszym niestandardowym przykładzie okna dialogowego.
Uzyskiwanie informacji o stanie wysyłania dziennika awarii
Czasami chcesz znać stan awarii aplikacji. Typowy przypadek użycia to wyświetlanie interfejsu użytkownika, który informuje użytkownika, że aplikacja przesyła raport o awarii. Innym scenariuszem jest dostosowanie zachowania aplikacji w celu zapewnienia, że dzienniki awarii można przesłać wkrótce po ponownym uruchomieniu. Awarie usługi App Center udostępniają trzy różne wywołania zwrotne, które można zgłaszać w celu powiadomienia o tym, co się stało:
Następujące wywołanie zwrotne zostanie wywołane przed wysłaniem dziennika awarii przez zestaw SDK
Crashes.SendingErrorReport += (errorReport) =>
{
// Your code, e.g. to present a custom UI.
};
W przypadku problemów z siecią lub awarii w punkcie końcowym i ponownego uruchomienia aplikacji SendingErrorReport zostanie ponownie wyzwolona po ponownym uruchomieniu procesu.
Następujące wywołanie zwrotne zostanie wywołane po pomyślnym wysłaniu dziennika awarii przez zestaw SDK
Crashes.SentErrorReport += (errorReport) =>
{
// Your code, e.g. to hide the custom UI.
};
Następujące wywołanie zwrotne zostanie wywołane, jeśli zestaw SDK nie może wysłać dziennika awarii
Crashes.FailedToSendErrorReport += (errorReport, exception) =>
{
// Your code goes here.
};
Odbieranie FailedToSendErrorReport oznacza, że wystąpił błąd niemożliwy do odzyskania, taki jak kod 4xx . Na przykład 401 oznacza, że błąd appSecret jest nieprawidłowy.
To wywołanie zwrotne nie jest wyzwalane, jeśli jest to problem z siecią. W takim przypadku zestaw SDK ponawia próbę (a także wstrzymuje ponawianie próby, gdy połączenie sieciowe nie działa).
Dodawanie załączników do raportu o awarii lub nieobsługiwanym wyjątku
Opcjonalnie możesz również dodać załączniki binarne i tekstowe do awarii lub nieobsługiwanego raportu wyjątku . Zestaw SDK wyśle je wraz z raportem, aby można było je wyświetlić w portalu Centrum aplikacji. Następujące wywołanie zwrotne zostanie wywołane bezpośrednio przed wysłaniem przechowywanego raportu. W przypadku awarii dzieje się to podczas następnego uruchamiania aplikacji. W przypadku nieobsługiwane wyjątki należy wyrazić zgodę na wysyłanie załączników. Upewnij się, że plik załącznika nie ma nazwy minidump.dmp , ponieważ ta nazwa jest zarezerwowana dla plików minidump. Oto przykład dołączania tekstu i obrazu do raportu:
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")
};
};
Awarie są rozróżniane od nieobsługiwane wyjątki w raportach z właściwością IsCrash . Właściwość będzie mieć wartość true w przypadku awarii i wartości false w przeciwnym razie.
Uwaga
Limit rozmiaru jest przeznaczony dla załączników obecnie 7 MB. Próba wysłania większego załącznika spowoduje wystąpienie błędu.
Uwaga
GetErrorAttachments jest wywoływany w wątku głównym i nie dzieli pracy na klatkach. Aby uniknąć blokowania pętli gry, nie wykonuj żadnych długotrwałych zadań w tym wywołaniu zwrotnym.
Włączanie lub wyłączanie awarii usługi App Center w czasie wykonywania
Możesz włączyć i wyłączyć awarie usługi App Center w czasie wykonywania. Jeśli ją wyłączysz, zestaw SDK nie będzie wykonywać żadnych raportów o awarii dla aplikacji.
Crashes.SetEnabledAsync(false);
Aby ponownie włączyć awarie usługi App Center, użyj tego samego interfejsu API, ale przekaż true go jako parametr.
Crashes.SetEnabledAsync(true);
Nie musisz czekać na to wywołanie, aby inne wywołania interfejsu API (takie jak IsEnabledAsync) były spójne.
Stan jest utrwalany w magazynie urządzenia w ramach uruchamiania aplikacji.
Sprawdzanie, czy w centrum aplikacji jest włączona awaria
Możesz również sprawdzić, czy usługa App Center Ulega awarii jest włączona:
bool isEnabled = await Crashes.IsEnabledAsync();
Obsługiwane wyjątki w środowisku Unity
Usługa App Center umożliwia również śledzenie błędów przy użyciu obsługiwanych wyjątków w środowisku Unity. W tym celu użyj TrackError metody :
try {
// your code goes here.
} catch (Exception exception) {
Crashes.TrackError(exception);
}
Aby uzyskać dalszy kontekst dotyczący błędu, możesz również dołączyć do niego właściwości. Przekaż właściwości jako słownik ciągów. Ta czynność jest opcjonalna.
try {
// your code goes here.
} catch (Exception exception) {
var properties = new Dictionary<string, string>
{
{ "Category", "Music" },
{ "Wifi", "On" }
};
Crashes.TrackError(exception, properties);
}
Możesz również opcjonalnie dodać załączniki binarne i tekstowe do obsługiwanego raportu o błędach. Przekaż załączniki jako tablicę ErrorAttachmentLog obiektów, jak pokazano w poniższym przykładzie.
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);
}
Nieobsługiwane wyjątki w środowisku Unity
Zgłaszanie nieobsługiwanych wyjątków
Domyślnie zestaw SDK centrum aplikacji nie zgłasza nieobsługiwanych wyjątków zgłaszanych w aplikacji, które nie powodują awarii krytycznej. Aby włączyć tę funkcję, wywołaj następującą metodę:
Crashes.ReportUnhandledExceptions(true);
Po wywołaniu tego interfejsu API centrum app center rejestruje wszystkie nieobsługiwane wyjątki jako problemy w portalu Centrum aplikacji, podobnie jak wcześniej obsługiwane wyjątki. Aby wyłączyć tę funkcję, wywołaj ten sam interfejs API przekazujący false parametr.
Crashes.ReportUnhandledExceptions(false);
Uwaga
Niektóre nieobsługiwane wyjątki wykryte przez zestaw SDK centrum aplikacji będą wyświetlane jako błędy w interfejsie użytkownika centrum aplikacji. Dzieje się tak, ponieważ aparat Unity domyślnie przechwytuje nieobsługiwane wyjątki, co oznacza, że aplikacja nie kończy działania i nie jest uznawana za awarię.
Dodawanie załączników do nieobsługiwanego raportu wyjątku
Domyślnie zestaw SDK centrum aplikacji nie włącza załączników w nieobsługiwanych wyjątkach. Aby włączyć tę funkcję, ustaw enableAttachmentsCallback parametr ReportUnhandledExceptions logiczny metody na true:
Crashes.ReportUnhandledExceptions(true, true);
Następnie możesz opcjonalnie dodać załączniki do nieobsługiwanego raportu wyjątku, implementując wywołanie zwrotne GetErrorAttachments .
Raportowanie awarii NDK
Raportowanie awarii
Aby otrzymywać odpowiednie raporty o awarii w centrum aplikacji, najpierw upewnij się, że masz skonfigurowany zestaw SDK awarii centrum aplikacji, postępując zgodnie z instrukcjami wymienionymi powyżej.
Tworzenie biblioteki breakpad
Następnie należy uwzględnić i skompilować aplikację Google Breakpad, postępując zgodnie z instrukcjami wymienionymi w oficjalnym notatniku Google Breakpad dla systemu Android README. Aby używać go w środowisku Unity, dołącz plik binarny do aplikacji.
Uwaga
Zestaw SDK centrum aplikacji domyślnie nie zawiera zestawu Google Breakpad.
Dołączanie procedury obsługi wyjątków
Po dołączeniu aplikacji Google Breakpad dołącz program obsługi awaryjnej NDK:
/* Attach NDK Crash Handler. */
var minidumpDir = Crashes.GetMinidumpDirectoryAsync();
setupNativeCrashesListener(minidumpDir.Result);
...
[DllImport("YourLib")]
private static extern void setupNativeCrashesListener(string path);
Metoda jest natywną setupNativeCrashesListener metodą, którą należy zaimplementować w języku 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);
}
Gdzie dumpCallback służy do rozwiązywania problemów:
/*
* 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;
}
Po poprawnym skonfigurowaniu tych metod aplikacja wysyła minidump do usługi App Center automatycznie po ponownym uruchomieniu. Aby rozwiązać problemy, możesz użyć pełnych dzienników, aby sprawdzić, czy minidumps są wysyłane po ponownym uruchomieniu aplikacji.
Uwaga
Usługa App Center używa nazwy minidump.dmp zarezerwowanej dla załączników minidump. Pamiętaj, aby nadać załącznikowi inną nazwę, chyba że jest to plik minidump, abyśmy mogli go prawidłowo obsłużyć.
Ostrzeżenie
Istnieje znana usterka w breakpad, która uniemożliwia przechwytywanie awarii na emulatorach x86.
Symbolizacja
Aby uzyskać więcej informacji na temat przetwarzania awarii, zobacz dokumentację diagnostyki .