Centro de Aplicações falhas (Unity)

O App Center Crashes gera automaticamente um registo de falhas sempre que a sua aplicação falha, gravando-o na armazenamento do dispositivo. Quando um usuário inicia o aplicativo novamente, o SDK envia o relatório de falhas para o App Center. A coleta de falhas funciona tanto para aplicativos beta quanto para aplicativos ao vivo, ou seja, falhas enviadas ao Google Play. Os registos de falhas contêm informações valiosas para ajudar a corrigir a falha.

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

Os registos de falhas no iOS requerem Simbolização. Para habilitar a simbologia, consulte a documentação do 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 gerar uma falha de teste para facilitar o teste do SDK. Esta API verifica se há configurações de depuração vs versão. Portanto, você só pode usá-lo durante a depuração, pois 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 seu aplicativo tenha falhado.

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

A qualquer momento depois de 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 travou na sessão anterior?

A qualquer momento depois de 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 após a ocorrência de uma falha. Alguns desenvolvedores mostram uma interface do usuário adicional para pedir desculpas aos usuários ou querem entrar em contato após a ocorrência de uma falha.

Detalhes sobre o último acidente

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

ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();

O caso de uso mais comum para essa API é quando um usuário está implementando seu delegado ou ouvinte personalizado de Falhas.

Personalize o uso do App Center Crashes

O App Center Crashes fornece callbacks para que os desenvolvedores tomem ações adicionais antes de e quando enviarem logs de falhas para o App Center.

O acidente deve ser processado?

Defina o seguinte callback 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ê 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;
};

Peça o consentimento do utilizador para enviar um registo de falhas

Se a privacidade do usuário for importante para você, convém obter a confirmação do usuário antes de enviar um relatório de falhas para o App Center. O SDK expõe um callback que indica ao App Center Crashes para aguardar a confirmação do utilizador antes de enviar qualquer relatório de falhas.

Se o teu código usar este callback, serás responsável por obter a confirmação do utilizador. Uma opção é através 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 Crashes o que fazer e a falha será tratada de acordo.

O seguinte callback mostra como instruir o SDK a esperar pela 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 permissão de 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(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 estado de envio de um registo de falhas

Às vezes, você quer saber o status da falha do seu aplicativo. Um caso de uso comum é a exibição de uma interface do usuário que informa ao usuário que o aplicativo está enviando um relatório de falhas. Outro cenário é quando você deseja ajustar o comportamento do aplicativo para garantir que os logs de falhas possam ser enviados logo após a reinicialização. O App Center Crashes fornece três retornos de chamada diferentes que você pode fazer para ser notificado do que aconteceu:

O seguinte callback será invocado antes que o SDK envie um registo de falhas

Crashes.SendingErrorReport += (errorReport) =>
{
    // Your code, e.g. to present a custom UI.
};

No caso de termos problemas de rede ou uma interrupção no ponto de extremidade, e você reiniciar o aplicativo, SendingErrorReport é acionado novamente após a reinicialização do processo.

A função de retorno seguinte será invocada depois do SDK enviar com sucesso um relatório de falhas.

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

O seguinte callback irá ser invocado se o SDK não tiver conseguido enviar um registo de falhas.

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

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

Esse retorno de chamada não é acionado 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 de sistema ou a um relatório de exceção não tratada

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 irá enviá-los junto com o relatório para que você possa vê-los no portal do App Center. A função de retorno a seguir será invocada mesmo antes de enviar o relatório armazenado. Na ocorrência de falhas, isto acontece na próxima vez que a aplicação é iniciada. Para exceções não tratadas, você deve optar por enviar anexos. Certifique-se de que o arquivo anexo não é nomeado minidump.dmp , pois esse nome está reservado para arquivos 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")
    };
};

As falhas são diferenciadas de exceções não tratadas em relatórios com a IsCrash propriedade. A propriedade será verdadeira para erros e falsa caso contrário.

Ativar ou desativar falhas do App Center em tempo de execução

Você pode habilitar e desabilitar a funcionalidade Crashes do App Center em tempo de execução. Se você desativá-lo, o SDK não executará nenhum relatório de falhas para o aplicativo.

Crashes.SetEnabledAsync(false);

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

Crashes.SetEnabledAsync(true);

Você não precisa esperar essa chamada para tornar outras chamadas de API (como IsEnabledAsync) consistentes.

O estado é persistido no armazenamento do dispositivo em todas as inicializações de aplicativos.

Verifique se o App Center Crashes está ativado

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

bool isEnabled = await Crashes.IsEnabledAsync();

Exceções tratadas no Unity

O App Center também permite que você rastreie erros usando exceções manipuladas 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 erro 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

Comunicar exceções não tratadas

Por padrão, o SDK do App Center não reporta exceções não tratadas que ocorram na sua aplicação e que não causem uma falha fatal. 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 não tratadas como Problemas no portal do App Center, semelhante às exceções tratadas mencionadas anteriormente. Para desativar esta funcionalidade, chame a mesma API passando false como parâmetro.

Crashes.ReportUnhandledExceptions(false);

Adicionar anexos a um relatório de exceções sem tratamento

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

Crashes.ReportUnhandledExceptions(true, true);

Em seguida, pode adicionar, opcionalmente, anexos a um relatório de exceção não tratada ao implementar a função de retorno de chamada GetErrorAttachments.

Relatando falhas de NDK

Comunicar falhas

Para receber relatórios de falhas adequados no App Center, primeiro certifique-se de ter o SDK de falhas do App Center configurado seguindo as instruções listadas acima.

Construção da biblioteca 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 em seu aplicativo.

Anexando o manipulador de exceção

Depois de incluir o Google Breakpad, anexe o NDK Crash Handler:

/* 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 estiverem 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 minidumps são enviados depois que o aplicativo é reiniciado.

Simbologia

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