Falhas no App Center (Android)

Importante

O Visual Studio App Center está programado para ser desativado em 31 de março de 2025. Embora você possa continuar a usar o Visual Studio App Center até que ele seja totalmente desativado, há várias alternativas recomendadas para as quais você pode considerar migrar.

Saiba mais sobre linhas do tempo e alternativas de suporte.

• Android
• iOS
• React Native
• MAUI/Xamarin
• UWP
• WPF/WinForms
• Unity
• macOS
• tvOS
• Cordova

As falhas do App Center gerarão automaticamente um log de falhas sempre que o aplicativo falhar. O log é gravado pela primeira vez no armazenamento do dispositivo e, quando o usuário iniciar o aplicativo novamente, o relatório de falha será enviado para o App Center. A coleta de falhas funciona para aplicativos beta e ao vivo, ou seja, aqueles enviados para o Google Play. Os logs de falhas contêm informações valiosas para ajudar a corrigir a falha.

Siga a seção Introdução se você ainda não configurou o SDK em seu aplicativo.

Gerar uma falha de teste

O App Center Crashes fornece uma API para gerar uma falha de teste para facilitar o teste do SDK. Essa API só pode ser usada em builds de depuração e não fará nada em builds de versão.

Crashes.generateTestCrash();

Crashes.generateTestCrash()

Obter mais informações sobre uma falha anterior

O App Center Crashes tem duas APIs que fornecem mais informações caso seu aplicativo falhe.

O aplicativo recebeu um aviso de memória insuficiente na sessão anterior?

A qualquer momento após iniciar o SDK, você poderá marcar se o aplicativo recebeu um aviso de memória na sessão anterior:

Crashes.hasReceivedMemoryWarningInLastSession();

Crashes.hasReceivedMemoryWarningInLastSession()

Essa API é assíncrona, você pode ler mais sobre isso em nosso guia de APIs assíncronas do App Center .

Observação

Esse método só deve ser usado depois Crashes de ter sido iniciado, ele sempre retornará false antes de iniciar.

Observação

Em alguns casos, um dispositivo com pouca memória não pode enviar eventos.

O aplicativo falhou na sessão anterior?

A qualquer momento após iniciar o SDK, você poderá marcar se o aplicativo falhou na inicialização anterior:

Crashes.hasCrashedInLastSession();

Crashes.hasCrashedInLastSession()

Essa API é assíncrona, você pode ler mais sobre isso em nosso guia de APIs assíncronas do App Center .

Isso é útil caso você deseje ajustar o comportamento ou a interface do usuário do seu aplicativo após a ocorrência de uma falha. Alguns desenvolvedores optaram por mostrar uma interface do usuário adicional para se desculpar com seus usuários ou querem uma maneira de entrar em contato após uma falha.

Observação

Esse método só deve ser usado depois Crashes de ter sido iniciado, ele sempre retornará false antes de iniciar.

Detalhes sobre a última falha

Se o aplicativo falhou anteriormente, você pode obter detalhes sobre a última falha.

Crashes.getLastSessionCrashReport();

Crashes.getLastSessionCrashReport()

Essa API é assíncrona, você pode ler mais sobre isso em nosso guia de APIs assíncronas do App Center .

Há vários casos de uso para essa API, o mais comum são as pessoas que chamam essa API e implementam seu CrashesListener personalizado.

Observação

Esse método só deve ser usado depois Crashes de ter sido iniciado, ele sempre retornará null antes de iniciar.

Personalizar o uso de falhas do App Center

O App Center Crashes fornece retornos de chamada para que os desenvolvedores executem ações adicionais antes e ao enviar logs de falha para o App Center.

Para lidar com os retornos de chamada, implemente todos os métodos na CrashesListener interface ou substitua a AbstractCrashesListener classe e escolha apenas os que você está interessado.

Usar seu próprio CrashesListener

Crie seu próprio CrashesListener e atribua-o da seguinte maneira:

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

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

Caso você esteja interessado apenas em personalizar alguns dos retornos de chamada, use o AbstractCrashesListener em vez disso:

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)

Observação

Defina o ouvinte antes de chamar AppCenter.start(), já que o App Center inicia o processamento falha imediatamente após o início.

A falha deve ser processada?

Implemente esse retorno de chamada se quiser decidir se uma falha específica precisa ser processada ou não. Por exemplo, pode haver uma falha no nível do sistema que você gostaria de ignorar e que não deseja enviar para o 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
}

Solicitar o consentimento do usuário para enviar um log de falhas

Se a privacidade do usuário for importante para você, talvez você queira obter a confirmação do usuário antes de enviar um relatório de falha para o App Center. O SDK expõe um retorno de chamada que informa a Falha do App Center para aguardar a confirmação do usuário antes de enviar relatórios de falha.

Se você optar por fazer isso, será responsável por obter a confirmação do usuário, por exemplo, por meio de um prompt de diálogo com uma das seguintes opções: Sempre Enviar, Enviar e Não enviar. Com base na entrada, você informará ao App Center falhas o que fazer e a falha será tratada adequadamente.

Observação

O SDK não exibe uma caixa de diálogo para isso, o aplicativo deve fornecer sua própria interface do usuário para solicitar o consentimento do usuário.

O seguinte retorno de chamada mostra como instruir o SDK a aguardar a confirmação do usuário antes de enviar falhas:

@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 você retornar true, seu aplicativo deverá obter (usando seu próprio código) a permissão do usuário e enviar uma mensagem ao SDK com o resultado usando a seguinte API:

// 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)

Como exemplo, você pode consultar nosso exemplo de caixa de diálogo personalizada.

Obter informações sobre o envio de status para um log de falhas

Às vezes, você deseja saber o status da falha do aplicativo. Um caso de uso comum é que talvez você queira mostrar a interface do usuário que informa aos usuários que seu aplicativo está enviando um relatório de falha ou, caso seu aplicativo esteja falhando rapidamente após a inicialização, você deseja ajustar o comportamento do aplicativo para garantir que os logs de falhas possam ser enviados. O App Center Crashes tem três retornos de chamada diferentes que você pode usar em seu aplicativo para ser notificado sobre o que está acontecendo:

O retorno de chamada a seguir será invocado antes que o SDK envie um log de falhas

@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.
}

Caso tenhamos problemas de rede ou uma interrupção no ponto de extremidade e você reinicie o aplicativo, onBeforeSending será disparado novamente após a reinicialização do processo.

O retorno de chamada a seguir será invocado depois que o SDK enviar um log de falhas com êxito

@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.
}

O retorno de chamada a seguir será invocado se o SDK não conseguir enviar um log de falhas

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

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

onSendingFailed Receber significa que ocorreu um erro não recuperável, como um código 4xx. Por exemplo, 401 significa que o appSecret está errado.

Esse retorno de chamada não será disparado se for um problema de rede. Nesse caso, o SDK continua tentando novamente (e também pausa novas tentativas enquanto a conexão de rede está inativa).

Adicionar anexos a um relatório de falha

Você pode adicionar anexos binários e de texto a um relatório de falha. O SDK os enviará junto com a falha para que você possa vê-los no portal do App Center. O retorno de chamada a seguir será invocado logo antes de enviar a falha armazenada de inicializações anteriores do aplicativo. Ele não será invocado quando a falha ocorrer. Verifique se o arquivo de anexo não está nomeado minidump.dmp , pois esse nome está reservado para arquivos de minidespejo. Aqui está um exemplo de como anexar texto e uma imagem a uma falha:

@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)
}

Observação

Atualmente, o limite de tamanho é de 7 MB. Tentar enviar um anexo maior disparará um erro.

Habilitar ou desabilitar falhas do App Center em runtime

Você pode habilitar e desabilitar falhas do App Center em runtime. Se você desabilitá-lo, o SDK não fará nenhum relatório de falha para o aplicativo.

Crashes.setEnabled(false);

Crashes.setEnabled(false)

Para habilitar falhas do App Center novamente, use a mesma API, mas passe true como um parâmetro.

Crashes.setEnabled(true);

Crashes.setEnabled(true)

O estado é persistido no armazenamento do dispositivo entre as inicializações do aplicativo.

Essa API é assíncrona, você pode ler mais sobre isso em nosso guia de APIs assíncronas do App Center .

Observação

Esse método só deve ser usado depois Crashes de ter sido iniciado.

Verificar se as falhas do App Center estão habilitadas

Você também pode marcar se falhas do App Center estiverem habilitadas ou não:

Crashes.isEnabled();

Crashes.isEnabled()

Essa API é assíncrona, você pode ler mais sobre isso em nosso guia de APIs assíncronas do App Center .

Observação

Esse método só deve ser usado depois Crashes de ter sido iniciado, ele sempre retornará false antes de iniciar.

Erros tratados

O App Center também permite que você rastreie erros usando exceções tratadas. Para fazer isso, use o trackError método :

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

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

Opcionalmente, um aplicativo pode anexar propriedades a um relatório de erro manipulado para fornecer mais contexto. Passe as propriedades como um mapa de pares chave/valor (somente cadeias de caracteres), conforme mostrado no exemplo abaixo.

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)
}

Opcionalmente, você também pode adicionar anexos binários e de texto a um relatório de erro manipulado. Passe os anexos como um Iterable conforme mostrado no exemplo abaixo.

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))
}

Relatórios de falhas do NDK

Relatando falhas

Para receber relatórios de falha adequados no App Center, primeiro verifique se você tem o SDK de Falhas do App Center configurado seguindo as instruções listadas acima.

Criando a biblioteca de breakpad

Em seguida, inclua e compile o Google Breakpad seguindo as instruções listadas no Google Breakpad oficial para Android README.

Observação

O SDK do App Center não agrupa o Google Breakpad por padrão.

Anexando o manipulador de exceção

Depois de incluir o Google Breakpad, anexe o Manipulador de Falhas do NDK após 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);
        }
    }
});

O método setupNativeCrashesListener é um método nativo que você deve implementar em 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);
}

Onde dumpCallback é usado para solução de problemas:

/*
 * 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;
}

Depois que esses métodos são configurados corretamente, o aplicativo envia o minidespejo para o App Center automaticamente após a reinicialização. Para solucionar problemas, você pode usar logs detalhados (AppCenter.setLogLevel(Log.VERBOSE) antes AppCenter.startde ) para marcar se os minidespejos forem enviados depois que o aplicativo for reiniciado.

Observação

O App Center usa o nome minidump.dmp reservado para anexos de minidespejo. Certifique-se de dar ao anexo um nome diferente, a menos que seja um arquivo de minidespejo para que possamos lidar com ele corretamente.

Observação

Há um bug conhecido no breakpad que torna impossível capturar falhas em emuladores x86.

Simbolização

Consulte a Documentação de diagnóstico para obter mais informações sobre o processamento de falhas.