Falhas e exceções – SDK do Android

Este documento contém uma visão geral de nível superior da avaliação de falhas e exceções por meio do SDK do Google Analytics para Android v3.

Visão geral

A avaliação de falhas e exceções permite que você analise o número e o tipo de falhas e exceções capturadas e não detectadas que ocorrem no seu app. Uma exceção tem estes campos:

Nome do campo Campo do rastreador Tipo Obrigatório Descrição
Descrição Fields.EX_DESCRIPTION String Não Descrição da exceção (até 100 caracteres). Aceita null .
isFatal Fields.EX_FATAL boolean Sim Indica se a exceção foi fatal. true indica que foi 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 identificadas são erros no seu aplicativo para os quais você definiu o código de tratamento de exceções, como o tempo limite ocasional de uma conexão de rede durante uma solicitação de dados.

Avalie uma exceção identificada definindo os valores dos campos de exceção no rastreador e enviando o hit, como neste exemplo:

/*
 * An app tries to load a list of high scores from the cloud. If the request
 * times out, an exception is sent to Google Analytics
 */
try {

  // Request some scores from the network.
  ArrayList highScores = getHighScoresFromCloud();

} catch (IOException e) {

  // May return null if EasyTracker has not yet been initialized with a
  // property ID.
  EasyTracker easyTracker = EasyTracker.getInstance(this);

  // StandardExceptionParser is provided to help get meaningful Exception descriptions.
 	easyTracker.send(MapBuilder
      .createException(new StandardExceptionParser(this, null)              // Context and optional collection of package names
                                                                            // to be used in reporting the exception.
                       .getDescription(Thread.currentThread().getName(),    // The name of the thread on which the exception occurred.
                                       e),                                  // The exception.
                       false)                                               // False indicates a nonfatal exception
      .build()
  );


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

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

Exceções não identificadas representam instâncias em que seu aplicativo encontrou condições inesperadas na execução. Geralmente elas são fatais e causam falha no aplicativo. Exceções não identificadas podem ser enviadas automaticamente ao Google Analytics usando o EasyTracker ou a classe ExceptionReporter.

Como usar o 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 avaliação automática de exceções, o EasyTracker vai transmitir a exceção ao gerenciador de exceções padrão do Thread.

Uso de uma implementação avançada

Use a classe ExceptionReporter para implementar a avaliação automática de exceções não identificadas se você estiver usando uma implementação avançada e não o EasyTracker.

ExceptionReporter pode servir como o gerenciador padrão de exceções não identificadas para uma linha de execução específica ou 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 a um gerenciador de exceções não identificadas 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(
    GoogleAnalytics.getInstance(this).getDefaultTracker(), // Tracker, may return null if not yet initialized.
    GAServiceManager.getInstance(),                        // GAServiceManager singleton.
    Thread.getDefaultUncaughtExceptionHandler());          // Current default uncaught exception handler.

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

Ao usar a avaliação automática de exceções, tenha em mente que:

  • Todas as exceções enviadas por meio da avaliação automática de exceções são informadas como fatais no Google Analytics.
  • Por padrão, o campo de descrição é definido automaticamente usando o tipo de exceção, o nome da classe, o nome do método e o nome da sequência.

Análise de descrições de exceções

O SDK fornece um StandardExceptionParser para simplificar o processo de receber e enviar descrições de exceções ao Google Analytics: 

// Using StandardExceptionParser to get an Exception description.
try {

  // Request some scores from the network.
  ArrayList highScores = getHighScoresFromCloud();

} catch (IOException e) {

  // May return null if EasyTracker has not yet been initialized with a
  // property ID.
  EasyTracker easyTracker = EasyTracker.getInstance(this);

 	easyTracker.send(MapBuilder
      .createException(new StandardExceptionParser(this, null)              // Context and optional collection of package names
                                                                            // to be used in reporting the exception.
                       .getDescription(Thread.currentThread().getName(),    // The name of the thread on which the exception occurred.
                                       e),                                  // The exception.
	                     false)                                               // False indicates a fatal exception
      .build()
  );

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

Também é possível implementar seu próprio analisador implementando a interface ExceptionParser e chamando o método setDescription dela ao enviar uma exceção ao Google Analytics.