Falhas e exceções

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

Visão geral

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

Nome do campo	Tipo	Obrigatório	Descrição
Descrição	String	Não	Descrição da exceção (até 100 caracteres). Aceita null.
isFatal	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, como o tempo limite ocasional de uma conexão de rede durante uma solicitação de dados, são erros no seu aplicativo para os quais você definiu o código de tratamento de exceções.

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

// Get tracker.
Tracker t =
    ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(TrackerName.APP_TRACKER);

// Build and send exception.
t.send(new HitBuilders.ExceptionBuilder()
    .setDescription(getExceptionMethod() + ":" + getExceptionLocation())
    .setFatal(getExceptionFatal())
    .build());

Consulte Configuração avançada para detalhes sobre o método getTracker.

Veja um snippet de código do aplicativo de exemplo

O snippet a seguir mostra um exemplo de Fragment que envia uma exceção:

package com.google.android.apps.mobileplayground;

import android.os.Bundle;
import android.support.v4.app.Fragment;
import android.view.LayoutInflater;
import android.view.View;
import android.view.View.OnClickListener;
import android.view.ViewGroup;
import android.widget.Button;
import android.widget.CheckBox;
import android.widget.EditText;
import com.google.android.apps.mobileplayground.AnalyticsSampleApp.TrackerName;
import com.google.android.gms.analytics.GoogleAnalytics;
import com.google.android.gms.analytics.HitBuilders;
import com.google.android.gms.analytics.Tracker;

/**
 * Class to exercise Exception hits.
 */
public class ExceptionFragment extends Fragment {

  @Override
  public View onCreateView(LayoutInflater inflater, ViewGroup container,
      Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    View view = inflater.inflate(R.layout.exception, container, false);

    final Button dispatchBtn = (Button) view.findViewById(R.id.btnDispatch);
    dispatchBtn.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        dispatch();
      }
    });

    final Button trackBtn = (Button) view.findViewById(R.id.trackBtn);
    trackBtn.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        track();
      }
    });
    return view;
  }

  private void dispatch() {
    GoogleAnalytics.getInstance(getActivity().getApplicationContext()).dispatchLocalHits();
  }

  private void track() {
    // Get tracker.
    Tracker t =
        ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(TrackerName.APP_TRACKER);

    // Build and send exception.
    t.send(new HitBuilders.ExceptionBuilder()
        .setDescription(getExceptionMethod() + ":" + getExceptionLocation())
        .setFatal(getExceptionFatal())
        .build());
  }

  private boolean getExceptionFatal() {
    return ((CheckBox) getView().findViewById(R.id.isFatalChk)).isChecked();
  }

  private String getExceptionLocation() {
    return ((EditText) getView().findViewById(R.id.exceptionLocationEdit)).getText().toString();
  }

  private String getExceptionMethod() {
    return ((EditText) getView().findViewById(R.id.exceptionMethodEdit)).getText().toString();
  }
}

Aviso : nunca envie a mensagem de exceção (por exemplo, e.getMessage()) ao Google Analytics, porque ela pode conter informações de identificação pessoal.

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. As exceções não identificadas podem ser enviadas automaticamente ao Google Analytics definindo o valor de configuração ga_reportUncaughtExceptions ou usando a classe ExceptionReporter.

Configuração automática

Para enviar automaticamente todas as exceções não identificadas no seu app ao Google Analytics, adicione esta linha ao arquivo de configuração XML:

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

Depois de enviar uma exceção usando a avaliação automática de exceções, ela será transmitida ao gerenciador de exceções padrão de Thread.

Observação: esse valor só pode ser definido como true para um único rastreador. Se ele for especificado para vários rastreadores, o último a ser inicializado será usado.

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 valor de configuração ga_reportUncaughtExceptions.

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.

Thread.UncaughtExceptionHandler myHandler = new ExceptionReporter(
    myTracker,
    Thread.getDefaultUncaughtExceptionHandler(),
    context);

// 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:

// Get tracker.
Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);

// Using StandardExceptionParser to get an Exception description.
try {
    // Request some scores from the network.
    ArrayList<Integer> highScores = getHighScoresFromCloud();
} catch (IOException e) {
    t.send(new HitBuilders.ExceptionBuilder()
        .setDescription(new StandardExceptionParser(this, null)
            .getDescription(Thread.currentThread().getName(), e))
        .setFatal(false)
        .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.