Condividi tramite

Crash di App Center (Android)

Importante

Visual Studio App Center è stato ritirato il 31 marzo 2025, ad eccezione delle funzionalità di Analisi e diagnostica, che continueranno a essere supportate fino al 30 giugno 2026. Ulteriori informazioni.

Il componente Crashes di App Center genererà automaticamente un log ogni volta che l'app si arresta in modo anomalo. Il log viene prima scritto nella memoria del dispositivo e quando l'utente avvia nuovamente l'app, il report degli errori verrà inviato ad App Center. La raccolta di arresti anomali funziona sia per le app beta che per quelle attive, ad esempio quelle inviate a Google Play. I log degli arresti anomali contengono informazioni utili per risolvere l'arresto anomalo del sistema.

Se non è ancora stato configurato l'SDK nell'applicazione, seguire la sezione Introduzione .

Generare un crash di test

Crashes di App Center offre un'API per generare un crash di prova per facilitare il test dell'SDK. Questa API può essere usata solo nelle build di debug e non esegue alcuna operazione nelle build di versione.

Crashes.generateTestCrash();

Crashes.generateTestCrash()

Trova ulteriori informazioni su un arresto anomalo precedente.

App Center Crashes ha due API che forniscono ulteriori informazioni nel caso in cui l'app vada in crash.

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:

Crashes.hasReceivedMemoryWarningInLastSession();

Crashes.hasReceivedMemoryWarningInLastSession()

Questa API è asincrona. Per altre informazioni, vedere la guida alle API asincrone di App Center .

Annotazioni

Questo metodo deve essere usato solo dopo che Crashes è stato avviato; restituirà sempre false prima dell'avvio.

Annotazioni

In alcuni casi, un dispositivo con memoria insufficiente non può inviare eventi.

L'arresto anomalo dell'app nella sessione precedente?

In qualsiasi momento dopo l'avvio dell'SDK, è possibile verificare se l'app si è arrestata in modo anomalo nell'avvio precedente:

Crashes.hasCrashedInLastSession();

Crashes.hasCrashedInLastSession()

Questa API è asincrona. Per altre informazioni, vedere la guida alle API asincrone di App Center .

Questo è utile nel caso in cui vuoi modificare il comportamento o l'interfaccia utente della tua app dopo un arresto anomalo. Alcuni sviluppatori hanno scelto di mostrare un'interfaccia utente aggiuntiva per scusarsi con gli utenti o vogliono trovare un modo per entrare in contatto dopo che si è verificato un crash.

Annotazioni

Questo metodo deve essere usato solo dopo che Crashes è stato avviato; restituirà sempre false prima dell'avvio.

Dettagli sull'ultimo arresto anomalo

Se l'app è andata in crash in precedenza, è possibile ricevere dettagli sull'ultimo crash.

Crashes.getLastSessionCrashReport();

Crashes.getLastSessionCrashReport()

Questa API è asincrona. Per altre informazioni, vedere la guida alle API asincrone di App Center .

Esistono numerosi casi d'uso per questa API, quello più comune è costituito dalle persone che chiamano questa API e implementano i relativi crashesListener personalizzati.

Annotazioni

Questo metodo deve essere usato solo dopo che Crashes è stato avviato; restituirà sempre null prima dell'avvio.

Personalizzare l'utilizzo dei crash di App Center

Il componente App Center Crashes fornisce callback agli sviluppatori per eseguire azioni aggiuntive prima di inviare i registri di errore ad App Center.

Per gestire i callback, implementare tutti i metodi nell'interfaccia CrashesListener o eseguire l'override della classe AbstractCrashesListener e selezionare solo quelli a cui si è interessati.

Usa il proprio CrashesListener

Crea il CrashesListener e assegnalo come segue:

CrashesListener customListener = new CrashesListener() {
    // Implement all callbacks here.
};
Crashes.setListener(customListener);

val customListener = object : CrashesListener {
    // Implement all callbacks here.
}
Crashes.setListener(customListener)

Se si è interessati solo alla personalizzazione di alcuni callback, usare invece AbstractCrashesListener :

AbstractCrashesListener customListener = new AbstractCrashesListener() {
    // Implement any callback here as required.
};
Crashes.setListener(customListener);

val customListener = object : AbstractCrashesListener() {
    // Implement any callback here as required.
}
Crashes.setListener(customListener)

Annotazioni

Impostare il listener prima di chiamare AppCenter.start(), poiché App Center avvia l'elaborazione dei crash immediatamente dopo l'avvio.

Deve essere elaborato l'incidente?

Implementare questo callback se si vuole decidere se è necessario elaborare o meno un determinato arresto anomalo. Ad esempio, potrebbe verificarsi un arresto anomalo a livello di sistema che si vuole ignorare e che non si vuole inviare ad App Center.

@Override
public boolean shouldProcess(ErrorReport report) {
    return true; // return true if the crash report should be processed, otherwise false.
}

override fun shouldProcess(report: ErrorReport?): Boolean {
    return true
}

Se la privacy degli utenti è importante per te, potresti voler ottenere conferma dagli utenti prima di inviare un report di errore ad App Center. L'SDK espone un callback che chiede ad App Center Crashes di attendere la conferma dell'utente prima di inviare report di arresto anomalo.

Se si sceglie di farlo, si è responsabili di ottenere la conferma dell'utente, ad esempio tramite una finestra di dialogo con una delle opzioni seguenti: Invia sempre, Invia e Non inviare. In base all'input, si indicherà ad App Center Crashes cosa fare e gestirà l'arresto anomalo di conseguenza.

Annotazioni

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 seguente callback illustra come configurare l'SDK affinché attenda la conferma dell'utente prima di inviare le segnalazioni di errori.

@Override
public boolean 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;
}

override fun shouldAwaitUserConfirmation(): Boolean {
    return true
}

Se si restituisce true, l'app deve ottenere (usando il proprio codice) l'autorizzazione dell'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(Crashes.DONT_SEND);
Crashes.notifyUserConfirmation(Crashes.SEND);
Crashes.notifyUserConfirmation(Crashes.ALWAYS_SEND);

Crashes.notifyUserConfirmation(Crashes.DONT_SEND)
Crashes.notifyUserConfirmation(Crashes.SEND)
Crashes.notifyUserConfirmation(Crashes.ALWAYS_SEND)

Ad esempio, è possibile fare riferimento all'esempio di dialogo personalizzato.

Ricevi informazioni sullo stato di invio di un log di arresto anomalo

A volte, vuoi conoscere lo stato del crash dell'app. Un caso d'uso comune è che puoi mostrare un'interfaccia utente che informa gli utenti che l'app sta inviando un report di arresto anomalo oppure, nel caso in cui l'app si arresti in modo anomalo rapidamente dopo l'avvio, puoi modificare il comportamento dell'app per assicurarti che i log degli arresti anomali vengano inviati. La funzionalità Crashes di App Center ha tre callback diversi che puoi usare nella tua app per ricevere notifiche su cosa sta succedendo:

Il callback seguente verrà richiamato prima che l'SDK invii un log di arresto anomalo del sistema

@Override
public void onBeforeSending(ErrorReport errorReport) {
    // Your code, e.g. to present a custom UI.
}

override fun onBeforeSending(report: ErrorReport?) {
    // Your code, e.g. to present a custom UI.
}

In caso di problemi di rete o un'interruzione dell'endpoint, e se riavvii l'app, onBeforeSending viene attivato di nuovo dopo il riavvio del processo.

Dopo che l'SDK avrà inviato correttamente un rapporto di errore, verrà attivato il callback seguente.

@Override
public void onSendingSucceeded(ErrorReport report) {
    // Your code, e.g. to hide the custom UI.
}

override fun onSendingSucceeded(report: 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 del sistema

@Override
public void onSendingFailed(ErrorReport report, Exception e) {
    // Your code goes here.
}

override fun onSendingFailed(report: ErrorReport?, e: Exception?) {
    // Your code goes here.
}

La ricezione onSendingFailed indica che si è verificato un errore non recuperabile, ad esempio un codice 4xx . Ad esempio, 401 indica che l'errore appSecret è sbagliato.

Questo callback non viene attivato se si tratta di un problema di rete. In questo caso, l'SDK continua a riprovare (e sospende anche i tentativi mentre la connessione di rete è inattiva).

Aggiungere allegati a un report di arresto anomalo

È possibile aggiungere allegati binari e di testo a un report di arresto anomalo del sistema. L'SDK li invierà insieme all'arresto anomalo in modo che sia possibile visualizzarli nel portale di App Center. Il callback seguente verrà richiamato immediatamente prima di inviare l'arresto anomalo archiviato dall'avvio precedente dell'applicazione. Non verrà richiamato quando si verifica il crash. Assicurarsi che il file allegato non sia denominato minidump.dmp come tale nome è riservato per i file minidump. Ecco un esempio di come allegare testo e un'immagine a un arresto anomalo:

@Override
public Iterable<ErrorAttachmentLog> getErrorAttachments(ErrorReport report) {

    // Attach some text.
    ErrorAttachmentLog textLog = ErrorAttachmentLog.attachmentWithText("This is a text attachment.", "text.txt");

    // Attach binary data.
    byte[] binaryData = getYourBinary();
    ErrorAttachmentLog binaryLog = ErrorAttachmentLog.attachmentWithBinary(binaryData, "your_filename.jpeg", "image/jpeg");

    // Return attachments as list.
    return Arrays.asList(textLog, binaryLog);
}

override fun getErrorAttachments(report: ErrorReport?): MutableIterable<ErrorAttachmentLog> {

    // Attach some text.
    val textLog = ErrorAttachmentLog.attachmentWithText("This is a text attachment.", "text.txt")

    // Attach binary data.
    val binaryData = getYourBinary()
    val binaryLog = ErrorAttachmentLog.attachmentWithBinary(binaryData, "your_filename.jpeg", "image/jpeg")

    // Return attachments as list.
    return listOf(textLog, binaryLog)
}

Annotazioni

Il limite di dimensioni è attualmente di 7 MB. Il tentativo di inviare un allegato più grande attiverà un errore.

Abilitare o disabilitare i crash di App Center durante l'esecuzione

È possibile abilitare e disabilitare i crash di App Center in fase di esecuzione. Se lo disabiliti, l'SDK non effettuerà segnalazioni di arresti anomali per l'app.

Crashes.setEnabled(false);

Crashes.setEnabled(false)

Per abilitare di nuovo App Center Crashes, usare la stessa API ma passare true come parametro.

Crashes.setEnabled(true);

Crashes.setEnabled(true)

Lo stato viene salvato in modo permanente nella risorsa di archiviazione del dispositivo all'avvio dell'applicazione.

Questa API è asincrona. Per altre informazioni, vedere la guida alle API asincrone di App Center .

Annotazioni

Questo metodo deve essere utilizzato solo dopo l'avvio di Crashes.

Verifica se Crashes di App Center è abilitato

È inoltre possibile verificare se i crash di App Center sono abilitati o meno:

Crashes.isEnabled();

Crashes.isEnabled()

Questa API è asincrona. Per altre informazioni, vedere la guida alle API asincrone di App Center .

Annotazioni

Questo metodo deve essere usato solo dopo che Crashes è stato avviato; restituirà sempre false prima dell'avvio.

Errori gestiti

App Center consente anche di tenere traccia degli errori usando le eccezioni gestite. A tale scopo, usare il trackError metodo :

try {
    // your code goes here.
} catch (Exception exception) {
    Crashes.trackError(exception);
}

try {
    // your code goes here.
} catch (exception: Exception) {
    Crashes.trackError(exception)
}

Un'app può facoltativamente allegare proprietà a un report degli errori gestito per fornire ulteriore contesto. Passare le proprietà come mappa di coppie chiave/valore (solo stringhe) come illustrato nell'esempio seguente.

try {
    // your code goes here.
} catch (Exception exception) {
    Map<String, String> properties = new HashMap<String, String>() {{
        put("Category", "Music");
        put("Wifi", "On");
    }};
    Crashes.trackError(exception, properties, null);
}

try {
    // your code goes here.
} catch (exception: Exception) {
    val properties = mapOf("Category" to "Music", "Wifi" to "On")
    Crashes.trackError(exception, properties, null)
}

Facoltativamente, è anche possibile aggiungere allegati binari e di testo a un report degli errori gestito. Passare gli allegati come Iterable come mostrato nell'esempio seguente.

try {
    // your code goes here.
} catch (Exception exception) {

    // Attach some text.
    ErrorAttachmentLog textLog = ErrorAttachmentLog.attachmentWithText("This is a text attachment.", "text.txt");

    // Attach binary data.
    byte[] binaryData = getYourBinary();
    ErrorAttachmentLog binaryLog = ErrorAttachmentLog.attachmentWithBinary(binaryData, "your_filename.jpeg", "image/jpeg");

    // Track an exception with attachments.
    Crashes.trackError(exception, null, Arrays.asList(textLog, binaryLog));
}

try {
    // your code goes here.
} catch (exception: Exception) {

    // Attach some text.
    val textLog = ErrorAttachmentLog.attachmentWithText("This is a text attachment.", "text.txt")

    // Attach binary data.
    val binaryData = getYourBinary()
    val binaryLog = ErrorAttachmentLog.attachmentWithBinary(binaryData, "your_filename.jpeg", "image/jpeg")

    // Track an exception with attachments.
    Crashes.trackError(exception, null, listOf(textLog, binaryLog))
}

Segnalazione di arresti anomali di NDK

Segnalazione di crash

Per ricevere report di crash adeguati in App Center, verifica di aver configurato App Center Crashes SDK seguendo le istruzioni elencate in precedenza.

Compilazione della libreria del breakpad

Successivamente, includere e compilare Google Breakpad seguendo le istruzioni elencate nel readME ufficiale di Google Breakpad per Android.

Annotazioni

App Center SDK non aggrega Google Breakpad per impostazione predefinita.

Collegare il gestore delle eccezioni

Dopo aver incluso Google Breakpad, e allegare il gestore degli arresti anomali NDK dopo AppCenter.start:

// Attach NDK Crash Handler after SDK is initialized.
Crashes.getMinidumpDirectory().thenAccept(new AppCenterConsumer<String>() {
    @Override
    public void accept(String path) {

        // Path is null when Crashes is disabled.
        if (path != null) {
            setupNativeCrashesListener(path);
        }
    }
});

Il metodo è un metodo setupNativeCrashesListener nativo che è necessario implementare in C/C++:

#include "google-breakpad/src/client/linux/handler/exception_handler.h"
#include "google-breakpad/src/client/linux/handler/minidump_descriptor.h"

void Java_com_microsoft_your_package_YourActivity_setupNativeCrashesListener(
        JNIEnv *env, jobject, jstring path) {
    const char *dumpPath = (char *) env->GetStringUTFChars(path, NULL);
    google_breakpad::MinidumpDescriptor descriptor(dumpPath);
    new google_breakpad::ExceptionHandler(descriptor, NULL, dumpCallback, NULL, true, -1);
    env->ReleaseStringUTFChars(path, dumpPath);
}

Dove dumpCallback viene usato per la risoluzione dei problemi:

/*
 * Triggered automatically after an attempt to write a minidump file to the breakpad folder.
 */
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 (prima di AppCenter.setLogLevel(Log.VERBOSE)AppCenter.start) per verificare se i minidump vengono inviati dopo il riavvio dell'app.

Annotazioni

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.

Annotazioni

Esiste un bug noto in Breakpad che rende impossibile acquisire i crash negli emulatori x86.

Simbolica

Per ulteriori informazioni sull'elaborazione dei crash, vedere la documentazione diagnostica.