Falhas do App Center (Unity)
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 a migração.
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 Simbolização. Para habilitar a simbólica, consulte a documentação diagnóstico do App Center, que explica como fornecer símbolos para seu aplicativo.
Importante
O SDK de Falhas para Unity não dá suporte à UWP. As instruções nesta página abrangem apenas Android e iOS.
Observação
O SDK não encaminhará nenhum log de falha se você tiver anexado o depurador. Verifique se o depurador não está anexado quando você interromper o aplicativo.
Observação
Se você tiver Enable CrashReport API habilitado no PlayerSettings, o SDK não coletará logs de falha.
Gerar uma falha de teste
As falhas do App Center fornecem uma API para gerar uma falha de teste para facilitar 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();
Observação
Esse método só funcionará com a configuração de Build de Desenvolvimento ativada.
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 memória baixa 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:
bool hadLowMemoryWarning = Crashes.HasReceivedMemoryWarningInLastSessionAsync().Result;
Observação
Esse método não funcionará em Awake().
Observação
Em alguns casos, um dispositivo com memória baixa 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:
bool didAppCrash = await Crashes.HasCrashedInLastSessionAsync();
Chamar HasCrashedInLastSessionAsync será útil se você quiser ajustar o comportamento ou a interface do usuário do aplicativo após uma falha. Alguns desenvolvedores mostram interface do usuário adicional para pedir desculpas aos usuários ou querem entrar em contato após uma falha.
Detalhes sobre a última falha
Se o aplicativo falhou anteriormente, você poderá 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 representante ou ouvinte personalizado de Falhas.
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 quando enviam logs de falha para o App Center.
Observação
Defina o retorno de chamada antes do início do App Center, por exemplo, no Awake método , uma vez que o App Center inicia o processamento falha imediatamente após o início.
A falha deve ser processada?
Defina o retorno de chamada a seguir 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 informa que o App Center falha para aguardar a confirmação do usuário antes de enviar relatórios de falha.
Se o código usar 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 caixa 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 retorno de chamada a seguir mostra como informar o SDK para aguardar a confirmação do usuário antes de enviar falhas:
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 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 é exibir uma interface do usuário que informa ao usuário que o aplicativo está enviando um relatório de falha. 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. As falhas do App Center fornecem 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 enviar 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 enviado um log de falhas
Crashes.FailedToSendErrorReport += (errorReport, exception) =>
{
// Your code goes here.
};
FailedToSendErrorReport 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 ou de exceção sem tratamento
Opcionalmente, você também pode adicionar anexos binários e de texto a um relatório de falha ou 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 logo 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 falhas e false caso contrário.
Observação
O limite de tamanho é para anexos atualmente de 7 MB. Tentar enviar um anexo maior disparará um erro.
Observação
GetErrorAttachmentsé invocado no thread main e não divide o trabalho por quadros. Para evitar bloquear o loop de jogo, não execute tarefas de execução prolongada neste retorno de chamada.
Habilitar ou desabilitar falhas do App Center no runtime
Você pode habilitar e desabilitar falhas do App Center em runtime. Se você desabilitá-lo, o SDK não executará nenhum relatório de falha para o aplicativo.
Crashes.SetEnabledAsync(false);
Para habilitar falhas do App Center novamente, use a mesma API, mas passe true como um parâmetro.
Crashes.SetEnabledAsync(true);
Você não precisa aguardar essa chamada para tornar outras chamadas à API (como IsEnabledAsync) consistentes.
O estado é persistente no armazenamento do dispositivo entre as inicializações de aplicativos.
Verificar se as falhas do App Center estão habilitadas
Você também pode marcar se as falhas do App Center estão habilitadas:
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 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 sem tratamento no Unity
Relatar exceções sem tratamento
Por padrão, o SDK do App Center não relata exceções sem tratamento lançadas em seu aplicativo que não causam 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 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 o parâmetro .
Crashes.ReportUnhandledExceptions(false);
Observação
Algumas exceções sem tratamento detectadas pelo SDK do App Center aparecerão como erros na interface do usuário do App Center. Isso ocorre porque o Unity captura exceções sem tratamento por padrão, o que significa que o aplicativo não sai e não é considerado uma falha.
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);
Em seguida, opcionalmente, você pode adicionar anexos a um relatório de exceção sem tratamento implementando o retorno de chamada GetErrorAttachments .
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, 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.
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:
/* 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 marcar se os minidumps forem enviados após a reinicialização do aplicativo.
Observação
O App Center usa o nome minidump.dmp reservado para anexos de minidump. Certifique-se de dar um nome diferente ao anexo, a menos que ele seja um arquivo de minidump para que possamos lidar com ele corretamente.
Aviso
Há um bug conhecido no breakpad que torna impossível capturar falhas em emuladores x86.
Simbolização
Consulte a documentação diagnóstico para obter mais informações sobre o processamento de falhas.