Falhas no App Center (Unity)

As falhas do App Center geram automaticamente um log de falhas sempre que o aplicativo falha, com um log no armazenamento do dispositivo. Quando um usuário inicia o aplicativo novamente, o SDK envia o relatório de falha para o App Center. A coleta de falhas funciona para aplicativos beta e ao vivo, ou seja, falhas enviadas ao Google Play. Os logs de falha contêm informações valiosas para ajudar a corrigir a falha.

Siga as instruções na seção Introdução do Unity se você ainda não configurou o SDK em seu aplicativo.

Os logs de falha no iOS exigem a Simbolização. Para habilitar a simbolização, consulte a documentação de Diagnóstico do App Center, que explica como fornecer símbolos para 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. Essa API verifica se há configurações de depuração versus versão. Portanto, você só pode usá-lo ao depurar, pois ele não funcionará para aplicativos de lançamento.

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:

bool hadLowMemoryWarning = Crashes.HasReceivedMemoryWarningInLastSessionAsync().Result;

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:

bool didAppCrash = await Crashes.HasCrashedInLastSessionAsync();

A chamada HasCrashedInLastSessionAsync é útil se você quiser ajustar o comportamento ou a interface do usuário do seu aplicativo depois que ocorreu uma falha. Alguns desenvolvedores mostram elementos adicionais na interface do usuário para pedir desculpas aos usuários ou desejam entrar em contato após uma falha.

Detalhes sobre a última falha

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

ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();

A maneira mais comum de utilizar essa API é quando um usuário está implementando seu delegado ou ouvinte personalizado de falhas.

Personalize o uso do recurso de falhas do App Center

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

A falha deve ser processada?

Defina o seguinte 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 não enviar para o App Center.

Crashes.ShouldProcessErrorReport = (ErrorReport report) =>
{
     // Check the report in here and return true or false depending on the ErrorReport.
    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 o seu código utilizar esse retorno de chamada, você será responsável por obter a confirmação do usuário. Uma opção é por meio de um prompt de diálogo com uma das seguintes opções: Sempre Enviar, Enviar e Não Enviar. Baseado na entrada, você informará à Central de Aplicativos 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.

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 o retorno de chamada retornar true, você deverá obter a permissão do usuário e enviar uma mensagem ao SDK com o resultado usando a API a seguir:

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

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 é exibir uma interface que informa ao usuário que o aplicativo está enviando um relatório de erro. Outro cenário é quando você deseja ajustar o comportamento do aplicativo para garantir que os logs de falha possam ser enviados logo após o relançamento. O App Center Crashes fornece três retornos de chamada diferentes que você pode fazer para ser notificado sobre o que ocorreu:

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

Crashes.SendingErrorReport += (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, SendingErrorReport 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

Crashes.SentErrorReport += (errorReport) =>
{
    // Your code, e.g. to hide the custom UI.
};

O retorno de chamada a seguir será invocado se o SDK não tiver conseguido enviar um relatório de falhas

Crashes.FailedToSendErrorReport += (errorReport, exception) =>
{
    // Your code goes here.
};

O recebimento FailedToSendErrorReport 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 uma falha ou a um relatório de exceção não tratado

Opcionalmente, você também pode adicionar anexos binários e de texto a uma falha ou a um relatório de exceção sem tratamento . O SDK os enviará junto com o relatório para que você possa vê-los no portal do App Center. O retorno de chamada a seguir será invocado antes de enviar o relatório armazenado. Para falhas, isso acontece na próxima inicialização do aplicativo. Para exceções sem tratamento, você deve aceitar o envio de anexos. 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 relatório:

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

Falhas são diferenciadas de exceções sem tratamento em relatórios com a IsCrash propriedade. A propriedade será verdadeira para erros e falsa nos casos contrários.

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 executará nenhum relatório de falha para o aplicativo.

Crashes.SetEnabledAsync(false);

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

Crashes.SetEnabledAsync(true);

Você não precisa aguardar essa chamada para fazer outras chamadas à API (como IsEnabledAsync) consistentes.

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

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

Você também pode verificar se o App Center Crashes está habilitado:

bool isEnabled = await Crashes.IsEnabledAsync();

Exceções tratadas no Unity

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

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

Para obter mais contexto sobre seu erro, você também pode anexar propriedades a ele. Passe as propriedades como um dicionário de cadeias de caracteres. Esta etapa é opcional.

try {
    // your code goes here.
} catch (Exception exception) {
    var properties = new Dictionary<string, string>
    {
        { "Category", "Music" },
        { "Wifi", "On" }
    };
    Crashes.TrackError(exception, properties);
}

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

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

Exceções não tratadas no Unity

Relatar exceções sem tratamento

Por padrão, o SDK do App Center não reporta exceções sem tratamento lançadas em seu aplicativo que não causam um erro crítico. Para habilitar essa funcionalidade, chame o seguinte método:

Crashes.ReportUnhandledExceptions(true);

Depois de chamar essa API, o App Center registra todas as exceções sem tratamento como problemas no portal do App Center, semelhante às exceções tratadas mencionadas anteriormente. Para desabilitar essa funcionalidade, chame a mesma API passando false como parâmetro.

Crashes.ReportUnhandledExceptions(false);

Adicionar anexos a um relatório de exceção sem tratamento

Por padrão, o SDK do App Center não habilita anexos em exceções sem tratamento. Para habilitar essa funcionalidade, defina o enableAttachmentsCallback parâmetro booliano do ReportUnhandledExceptions método como true:

Crashes.ReportUnhandledExceptions(true, true);

Opcionalmente, você pode adicionar anexos a um relatório de exceção sem tratamento implementando o retorno de chamada GetErrorAttachments .

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, você deve incluir e compilar o Google Breakpad seguindo as instruções listadas no Google Breakpad oficial para Android README. Para usá-lo no Unity, inclua o binário com seu aplicativo.

Anexando o manipulador de exceção

Depois de incluir o Google Breakpad, conecte o Crash Handler do NDK.

/* Attach NDK Crash Handler. */
var minidumpDir = Crashes.GetMinidumpDirectoryAsync();
setupNativeCrashesListener(minidumpDir.Result);

...

[DllImport("YourLib")]
private static extern void setupNativeCrashesListener(string path);

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

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

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

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 para verificar se os minidumps são enviados após a reinicialização do aplicativo.

Simbolização

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