Falhas no App Center (Android)

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 inicia 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 falha 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 simular um crash de teste, facilitando o teste do SDK. Esta API só pode ser usada em compilações de depuração e não fará nada em compilações de release.

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 o aplicativo tenha falhado.

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

A qualquer momento após iniciar o SDK, você pode verificar 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 .

O aplicativo falhou na sessão anterior?

A qualquer momento após iniciar o SDK, você pode verificar 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 depois que ocorreu uma falha. Alguns desenvolvedores optam por mostrar uma interface do usuário adicional para pedir desculpas aos usuários ou querem encontrar um meio de entrar em contato depois que ocorre uma falha.

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.

Personalize o uso do recurso de falhas do App Center

O App Center Crashes fornece retornos de chamada para os desenvolvedores executarem ações adicionais antes de enviar e ao enviar relatórios de falhas para o App Center.

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

Usar seu próprio CrashesListener

Crie seu próprio CrashesListener e atribua-o assim:

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)

A falha deve ser processada?

Implemente este callback se você 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ê deseja 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 indica ao App Center Crashes para aguardar a confirmação do usuário antes de enviar quaisquer relatórios de falhas.

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ê indicará ao App Center Crashes o que fazer, e a falha será tratada adequadamente.

O seguinte callback mostra como instruir o SDK a aguardar a confirmação do usuário antes de enviar crashes.

@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 diálogo personalizado.

Obter informações sobre o status de envio de um relatório de erro

À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 falha 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 enviou 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 tiver enviado um crash log

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

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

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

Esse retorno de chamada não será ativado 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 enviará essas informações junto com a falha, para que você possa vê-las no portal do App Center. O callback a seguir será invocado logo antes de enviar o crash armazenado dos lançamentos anteriores do aplicativo. Ele não será invocado quando o acidente acontecer. Verifique se o arquivo de anexo não está nomeado minidump.dmp , pois esse nome está reservado para arquivos de minidump. Aqui está um exemplo de como anexar texto e uma imagem a um crash:

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

Habilitar ou desabilitar falhas do App Center no tempo de execução

Você pode habilitar e desabilitar o Crashes no App Center durante o tempo de execução. 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 o App Center Crashes novamente, use a mesma API, mas passe true como um parâmetro.

Crashes.setEnabled(true);

Crashes.setEnabled(true)

O estado é mantido 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 .

Verificar se o recurso de 'Crashes' do App Center está habilitado

Você também pode verificar se o recurso App Center Crashes está habilitado 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 .

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

Relatando falhas de NDK

Relatório de 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.

Compilando a biblioteca do breakpad

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

Anexando o manipulador de exceção

Depois de incluir o Google Breakpad, anexe o Gerenciador de Falhas do NDK depois de 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 minidump para o App Center automaticamente após a reinicialização. Para solucionar problemas, você pode usar logs detalhados (AppCenter.setLogLevel(Log.VERBOSE) antes do AppCenter.start) para verificar se os minidumps são enviados após reiniciar o aplicativo.

Simbolização

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