Arresti anomali di App Center (Unity)
Importante
Visual Studio App Center è previsto per il ritiro il 31 marzo 2025. Anche se è possibile continuare a usare Visual Studio App Center fino a quando non viene completamente ritirato, esistono diverse alternative consigliate che è possibile considerare la migrazione a.
Altre informazioni sulle sequenze temporali di supporto e sulle alternative.
Gli arresti anomali di App Center generano automaticamente un log di arresto anomalo ogni volta che l'app si arresta in modo anomalo, con un log per l'archiviazione del dispositivo. Quando un utente avvia di nuovo l'app, l'SDK invia il report di arresto anomalo a App Center. La raccolta di arresti anomali funziona sia per le app beta che per le app live, ovvero gli arresti anomali inviati a Google Play. I log di arresto anomalo contengono informazioni preziose per facilitare la correzione dell'arresto anomalo.
Seguire le istruzioni nella sezione Unity Introduzione se non è ancora stato configurato l'SDK nell'applicazione.
I log di arresto anomalo in iOS richiedono simbolicamente. Per abilitare la simbolica, fare riferimento alla documentazione di Diagnostica di App Center, che illustra come fornire simboli per l'app.
Importante
L'SDK arresti anomali per Unity non supporta UWP. Le istruzioni contenute in questa pagina illustrano solo Android e iOS.
Nota
L'SDK non inoltra i log di arresto anomalo se è stato collegato il debugger. Assicurarsi che il debugger non sia collegato quando si arresta l'arresto anomalo dell'app.
Nota
Se è stato Enable CrashReport API abilitato in PlayerSettings, l'SDK non raccoglie i log di arresto anomalo.
Generare un arresto anomalo del test
Gli arresti anomali di App Center offrono un'API per generare un arresto anomalo del test per un semplice test dell'SDK. Questa API controlla le configurazioni di debug e versione. È quindi possibile usarlo solo quando si esegue il debug perché non funzionerà per le app per la versione.
Crashes.GenerateTestCrash();
Nota
Questo metodo funzionerà solo con l'impostazione build di sviluppo attivata.
Ottenere altre informazioni su un arresto anomalo precedente
Gli arresti anomali di App Center hanno due API che forniscono altre informazioni in caso di arresto anomalo dell'app.
L'app ha ricevuto un avviso di memoria insufficiente nella sessione precedente?
In qualsiasi momento dopo l'avvio dell'SDK, è possibile verificare se l'app ha ricevuto un avviso di memoria nella sessione precedente:
bool hadLowMemoryWarning = Crashes.HasReceivedMemoryWarningInLastSessionAsync().Result;
Nota
Questo metodo non funzionerà in Awake().
Nota
In alcuni casi, un dispositivo con memoria ridotta non può inviare eventi.
L'app si è arrestata in modo anomalo nella sessione precedente?
In qualsiasi momento dopo l'avvio dell'SDK, è possibile verificare se l'app si è arrestata in modo anomalo nell'avvio precedente:
bool didAppCrash = await Crashes.HasCrashedInLastSessionAsync();
La chiamata HasCrashedInLastSessionAsync è utile se si vuole modificare il comportamento o l'interfaccia utente dell'app dopo un arresto anomalo. Alcuni sviluppatori mostrano un'interfaccia utente aggiuntiva per scusarsi con gli utenti o vogliono entrare in contatto dopo un arresto anomalo.
Dettagli sull'ultimo arresto anomalo
Se l'app si è bloccata in precedenza, è possibile ottenere informazioni dettagliate sull'ultimo arresto anomalo.
ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();
Il caso d'uso più comune per questa API è quando un utente implementa il delegato o il listener personalizzati degli arresti anomali.
Personalizzare l'utilizzo degli arresti anomali di App Center
Gli arresti anomali di App Center offrono callback per gli sviluppatori per eseguire azioni aggiuntive prima e quando inviano i log di arresto anomalo a App Center.
Nota
Impostare il callback prima dell'avvio di App Center, ad esempio nel Awake metodo, poiché App Center avvia l'elaborazione si arresta in modo anomalo immediatamente dopo l'avvio.
L'arresto anomalo deve essere elaborato?
Impostare il callback seguente se si vuole decidere se è necessario elaborare o meno un arresto anomalo specifico. Ad esempio, potrebbe verificarsi un arresto anomalo a livello di sistema che si vuole ignorare e non inviare a App Center.
Crashes.ShouldProcessErrorReport = (ErrorReport report) =>
{
// Check the report in here and return true or false depending on the ErrorReport.
return true;
};
Chiedere il consenso dell'utente per inviare un log di arresto anomalo
Se la privacy degli utenti è importante per te, potresti voler ottenere la conferma dell'utente prima di inviare un report di arresto anomalo all'App Center. L'SDK espone un callback che indica agli arresti anomali di App Center di attendere la conferma dell'utente prima di inviare eventuali report di arresto anomalo.
Se il codice usa questo callback, è possibile ottenere la conferma dell'utente. Un'opzione è tramite una finestra di dialogo con una delle opzioni seguenti: Always Send, Send e Don't send. In base all'input, si indicherà agli arresti anomali di App Center cosa fare e l'arresto anomalo verrà quindi gestito di conseguenza.
Nota
L'SDK non visualizza una finestra di dialogo per questa operazione, l'app deve fornire la propria interfaccia utente per richiedere il consenso dell'utente.
Il callback seguente illustra come indicare all'SDK di attendere la conferma dell'utente prima di inviare arresti anomali:
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;
};
Se il callback restituisce true, è necessario ottenere l'autorizzazione utente e il messaggio dell'SDK con il risultato usando l'API seguente:
// 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);
Come esempio è possibile fare riferimento all'esempio di dialogo personalizzato.
Ottenere informazioni sullo stato di invio per un log di arresto anomalo
A volte, si vuole conoscere lo stato dell'arresto anomalo dell'app. Un caso d'uso comune visualizza un'interfaccia utente che informa l'utente che invia un report di arresto anomalo. Un altro scenario è quando si vuole modificare il comportamento dell'app per garantire che i log di arresto anomalo possano essere inviati poco dopo il riavvio. Gli arresti anomali del Centro app offrono tre callback diversi che è possibile effettuare per ricevere una notifica di ciò che si è verificato:
Il callback seguente verrà richiamato prima che l'SDK invii un log di arresto anomalo
Crashes.SendingErrorReport += (errorReport) =>
{
// Your code, e.g. to present a custom UI.
};
In caso di problemi di rete o interruzione nell'endpoint e riavvio dell'app, SendingErrorReport viene attivata nuovamente dopo il riavvio del processo.
Il callback seguente verrà richiamato dopo che l'SDK ha inviato correttamente un log di arresto anomalo
Crashes.SentErrorReport += (errorReport) =>
{
// Your code, e.g. to hide the custom UI.
};
Il callback seguente verrà richiamato se l'SDK non è riuscito a inviare un log di arresto anomalo
Crashes.FailedToSendErrorReport += (errorReport, exception) =>
{
// Your code goes here.
};
La ricezione FailedToSendErrorReport indica un errore non recuperabile, ad esempio un codice 4xx . Ad esempio, 401 significa che l'errore appSecret è errato.
Questo callback non viene attivato se si tratta di un problema di rete. In questo caso, l'SDK continua a ripetere i tentativi (e sospende anche i tentativi mentre la connessione di rete è inattiva).
Aggiungere allegati a un arresto anomalo o a un report di eccezione non gestito
È anche possibile aggiungere allegati binari e di testo a un arresto anomalo o a un report di eccezione non gestito . L'SDK li invierà insieme al report in modo da poterli visualizzare nel portale di App Center. Il callback seguente verrà richiamato direttamente prima di inviare il report archiviato. Per gli arresti anomali si verifica all'avvio dell'applicazione successiva. Per le eccezioni non gestite, è necessario acconsentire esplicitamente all'invio di allegati. Assicurarsi che il file allegato non sia denominato minidump.dmp come tale nome è riservato per i file minidump. Ecco un esempio di come collegare testo e un'immagine a un report:
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")
};
};
Gli arresti anomali sono diversi da eccezioni non gestite nei report con la IsCrash proprietà . La proprietà sarà true per gli arresti anomali e false in caso contrario.
Nota
Il limite di dimensioni è per gli allegati attualmente 7 MB. Il tentativo di inviare un allegato più grande attiverà un errore.
Nota
GetErrorAttachments viene richiamato sul thread principale e non divide il lavoro su frame. Per evitare di bloccare il ciclo del gioco, non eseguire attività a esecuzione prolungata in questo callback.
Abilitare o disabilitare arresti anomali di App Center in fase di esecuzione
È possibile abilitare e disabilitare arresti anomali di App Center in fase di esecuzione. Se la si disabilita, l'SDK non eseguirà alcuna segnalazione di arresto anomalo per l'app.
Crashes.SetEnabledAsync(false);
Per abilitare di nuovo gli arresti anomali di App Center, usare la stessa API ma passare true come parametro.
Crashes.SetEnabledAsync(true);
Non è necessario attendere questa chiamata per rendere coerenti altre chiamate API ( ad esempio IsEnabledAsync).
Lo stato viene salvato in modo permanente nella risorsa di archiviazione del dispositivo tra i lanci dell'applicazione.
Controllare se Gli arresti anomali di App Center sono abilitati
È anche possibile controllare se Gli arresti anomali di App Center sono abilitati:
bool isEnabled = await Crashes.IsEnabledAsync();
Eccezioni gestite in Unity
App Center consente anche di tenere traccia degli errori usando le eccezioni gestite in Unity. A tale scopo, usare il TrackError metodo :
try {
// your code goes here.
} catch (Exception exception) {
Crashes.TrackError(exception);
}
Per ulteriori informazioni sull'errore, è anche possibile allegare le proprietà. Passare le proprietà come dizionario di stringhe. Questo passaggio è facoltativo.
try {
// your code goes here.
} catch (Exception exception) {
var properties = new Dictionary<string, string>
{
{ "Category", "Music" },
{ "Wifi", "On" }
};
Crashes.TrackError(exception, properties);
}
È anche possibile aggiungere allegati binari e di testo a un report degli errori gestito. Passare gli allegati come matrice di ErrorAttachmentLog oggetti, come illustrato nell'esempio seguente.
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);
}
Eccezioni non gestite in Unity
Segnalare eccezioni non gestite
Per impostazione predefinita, App Center SDK non segnala eccezioni non gestite generate nell'app che non causano un arresto anomalo irreversibile. Per abilitare questa funzionalità, chiamare il metodo seguente:
Crashes.ReportUnhandledExceptions(true);
Dopo aver chiamato questa API, App Center registra tutte le eccezioni non gestite come problemi nel portale di App Center, in modo analogo alle eccezioni gestite indicate in precedenza. Per disabilitare questa funzionalità, chiamare la stessa API passando false il parametro .
Crashes.ReportUnhandledExceptions(false);
Nota
Alcune eccezioni non gestite rilevate da App Center SDK verranno visualizzate come errori nell'interfaccia utente di App Center. Questo perché Unity rileva le eccezioni non gestite per impostazione predefinita, ovvero l'app non viene chiusa e non è considerata un arresto anomalo.
Aggiungere allegati a un report di eccezione non gestito
Per impostazione predefinita, App Center SDK non abilita gli allegati in eccezioni non gestite. Per abilitare questa funzionalità, impostare il enableAttachmentsCallback parametro booleano del ReportUnhandledExceptions metodo su true:
Crashes.ReportUnhandledExceptions(true, true);
È quindi possibile aggiungere allegati a un report delle eccezioni non gestite implementando il callback GetErrorAttachments .
Segnalazione di arresti anomali di NDK
Segnalazione di arresti anomali
Per ricevere report di arresto anomalo corretti in App Center, assicurarsi di avere configurato App Center Crashes SDK seguendo le istruzioni elencate in precedenza.
Compilazione della libreria del breakpad
Successivamente, è necessario includere e compilare Google Breakpad seguendo le istruzioni elencate nel Google Breakpad ufficiale per Android README. Per usarlo in Unity, includere il file binario con l'app.
Nota
App Center SDK non aggrega Google Breakpad per impostazione predefinita.
Collegamento del gestore eccezioni
Dopo aver incluso Google Breakpad, allegare NDK Crash Handler:Once you have Google Breakpad included, attach the NDK Crash Handler:
/* Attach NDK Crash Handler. */
var minidumpDir = Crashes.GetMinidumpDirectoryAsync();
setupNativeCrashesListener(minidumpDir.Result);
...
[DllImport("YourLib")]
private static extern void setupNativeCrashesListener(string path);
Il metodo è un metodo setupNativeCrashesListener nativo che è necessario implementare in 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);
}
Dove dumpCallback viene usato per la risoluzione dei problemi:
/*
* 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;
}
Dopo aver configurato correttamente questi metodi, l'app invia automaticamente il minidump ad App Center al riavvio. Per risolvere i problemi, è possibile usare i log dettagliati per verificare se i minidump vengono inviati dopo il riavvio dell'app.
Nota
App Center usa il nome minidump.dmp riservato per gli allegati minidump. Assicurarsi di assegnare un nome diverso all'allegato, a meno che non si tratti di un file minidump in modo da poterlo gestire correttamente.
Avviso
C'è un bug noto nel breakpad che rende impossibile acquisire arresti anomali negli emulatori x86.
Simbolica
Per altre informazioni sull'elaborazione degli arresti anomali, vedere la documentazione di Diagnostica .