Falhas e exceções: SDK do Android v2 (legado)

Este documento apresenta uma visão geral de alto nível da medição de falhas e exceções usando o SDK do Google Analytics para Android v2.

Visão geral

A medição de falhas e exceções permite avaliar o número e o tipo de falhas e exceções capturadas e não capturadas que ocorrem no seu app. Uma exceção no Google Analytics consiste em:

  • String (Opcional) Uma descrição da exceção (até 100 caracteres). Aceita null .
  • boolean isFatal: indica se a exceção foi fatal. true indica fatal.

Os dados de falhas e exceções estão disponíveis principalmente no Relatório de falhas e exceções.

Exceções identificadas

Exceções capturadas são erros no seu aplicativo para os quais você definiu código de processamento de exceções. Normalmente, esses são erros que você acredita que ocorreriam durante o uso normal do app e que você quer que o app possa recuperar, como o tempo limite normal de uma conexão de rede durante uma solicitação de dados.

Você pode medir as exceções capturadas adicionando sendException() ao bloco catch do código de gerenciamento de exceções.

No exemplo a seguir, um app tenta carregar uma lista de maiores pontuações da nuvem. Se a solicitação expirar, talvez devido a uma conexão de rede lenta, enviaremos a exceção ao Google Analytics antes de processá-la para o usuário:

try {
  ArrayList highScores = getHighScores();            // Get scores from the cloud.
} catch (IOException e) {
  Tracker myTracker = EasyTracker.getTracker();      // Get a reference to tracker.
  myTracker.sendException(e.getMessage(), false);    // false indicates non-fatal exception.

  ... // Display alert to user that high scores are currently unavailable.
}

Avaliação de exceções não identificadas

Exceções não capturadas representam instâncias em que seu app encontrou condições inesperadas durante a execução e geralmente são fatais, fazendo com que o app falhe como resultado. As exceções não identificadas podem ser enviadas automaticamente ao Google Analytics por meio do EasyTracker ou da classe ExceptionReporter.

Usando EasyTracker

Para enviar automaticamente todas as exceções não identificadas no seu app usando o EasyTracker, adicione esta linha ao arquivo analytics.xml:

<bool name="ga_reportUncaughtExceptions">true</bool>

Depois de enviar uma exceção usando a medição automática de exceções, o EasyTracker passará a exceção para o gerenciador de exceções padrão Thread.

Ao usar a medição automática de exceções, lembre-se do seguinte:

  • Todas as exceções enviadas por meio da avaliação automática de exceções são informadas como fatais no Google Analytics.
  • O campo de descrição é preenchido automaticamente usando o stack trace.

Como usar o ExceptionReporter

Use a classe ExceptionReporter para implementar a avaliação automática de exceções não capturadas se você não estiver usando o EasyTracker. Essa é a mesma classe que o EasyTracker implementa para processar o relatório automático de exceções.

A ExceptionReporter pode servir como o gerenciador de exceções padrão não capturada de uma linha de execução específica ou de todas as linhas de execução no seu app. Depois de enviar uma exceção ao Google Analytics, a classe ExceptionReporter pode transmitir a exceção para um gerenciador de exceções não capturado que você fornecer.

O código a seguir cria um novo objeto ExceptionReporter e o define como o novo gerenciador padrão de exceções não capturadas. Como resultado, todas as exceções não identificadas serão enviadas ao Google Analytics e, em seguida, transmitidas ao manipulador de exceções não capturadas anterior. Para a maioria dos aplicativos, o manipulador padrão registrará a exceção no registro e encerrará o aplicativo.

UncaughtExceptionHandler myHandler = new ExceptionReporter(
    myTracker,                                        // Currently used Tracker.
    GAServiceManager.getInstance(),                   // GAServiceManager singleton.
    Thread.getDefaultUncaughtExceptionHandler());     // Current default uncaught exception handler.

 // Make myHandler the new default uncaught exception handler.
Thread.setDefaultUncaughtExceptionHandler(myHandler);

Como usar o ExceptionParser

O SDK oferece uma interface ExceptionParser que pode ser implementada para receber as descrições mais relevantes dos traces de pilha ao enviar exceções não capturadas ao Google Analytics. A interface ExceptionParser tem um método: getDescription(String threadName, Throwable t).

Você pode definir seu Tracker para usar seu ExceptionParser ao enviar exceções não capturadas para o Google Analytics chamando setExceptionParser(ExceptionParser parser) como neste exemplo:

// Where myParser represents your implementation of ExceptionParser.
ExceptionParser parser = new myParser(context);

// Where myTracker is an instance of Tracker.
myTracker.setExceptionParser(parser);

O Tracker usará o método getDescription() do seu analisador para preencher o campo de descrição de todas as exceções não identificadas enviadas ao Google Analytics.