Arresti anomali ed eccezioni

Questo documento fornisce una panoramica generale della misurazione di arresti anomali ed eccezioni utilizzando l'SDK Google Analytics v4 per Android.

Panoramica

La misurazione degli arresti anomali e delle eccezioni consente di misurare il numero e il tipo di eccezioni e arresti anomali rilevati e non rilevati che si verificano nella tua app. Un'eccezione include i seguenti campi:

Nome campo	Tipo	Obbligatorio	Descrizione
Descrizione	String	No	Una descrizione dell'eccezione (fino a 100 caratteri). Accetta null.
isFatal	boolean	Sì	Indica se l'eccezione è stata irreversibile. true indica che è irreversibile.

I dati su arresti anomali ed eccezioni sono disponibili principalmente nel report Arresti anomali ed eccezioni.

Eccezioni rilevate

Le eccezioni rilevate, come il timeout occasionale di una connessione di rete durante una richiesta di dati, sono errori nell'app per cui hai implementato il codice.

Misura un'eccezione rilevata impostando i valori del campo dell'eccezione sul tracker e inviando l'hit, come in questo esempio:

// 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());

Per maggiori dettagli sul metodo getTracker, consulta Configurazione avanzata.

Visualizza uno snippet di codice dall'applicazione di esempio

Lo snippet seguente mostra un esempio Fragment che invia un'eccezione:

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();
  }
}

Avviso: non inviare mai il messaggio di eccezione (ad esempio e.getMessage()) a Google Analytics, in quanto potrebbe contenere informazioni che consentono l'identificazione personale.

Misurazione eccezioni non rilevate

Le eccezioni non rilevate rappresentano i casi in cui la tua app ha riscontrato condizioni impreviste in fase di runtime e spesso sono irreversibili, causando l'arresto anomalo dell'app. Le eccezioni non rilevate possono essere inviate automaticamente a Google Analytics impostando il valore di configurazione ga_reportUncaughtExceptions o utilizzando la classe ExceptionReporter.

Configurazione automatica

Per inviare automaticamente a Google Analytics tutte le eccezioni non rilevate nella tua app, aggiungi questa riga al file di configurazione XML:

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

Dopo aver inviato un'eccezione utilizzando la misurazione automatica delle eccezioni, questa verrà trasmessa al gestore delle eccezioni predefinito di Thread.

Nota: questo valore può essere impostato solo su true per un singolo tracker. Se specificato per più tracker, verrà utilizzato l'ultimo da inizializzare.

Utilizzo di un'implementazione avanzata

Utilizza la classe ExceptionReporter per implementare la misurazione automatica delle eccezioni non rilevate se utilizzi un'implementazione avanzata e non il valore di configurazione ga_reportUncaughtExceptions.

ExceptionReporter può fungere da gestore di eccezioni predefinito non rilevato per un thread specifico o per tutti i thread nella tua app. Dopo aver inviato un'eccezione a Google Analytics, la classe ExceptionReporter può facoltativamente passare l'eccezione a un gestore delle eccezioni non rilevato da te fornito.

Il seguente codice crea un nuovo oggetto ExceptionReporter e lo imposta come nuovo gestore delle eccezioni predefinito non rilevato. Di conseguenza, ogni eccezione non rilevata viene inviata a Google Analytics e poi trasmessa al gestore delle eccezioni non rilevato precedente. Per la maggior parte delle applicazioni, il gestore predefinito registra l'eccezione nel log e termina l'applicazione.

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

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

Quando utilizzi la misurazione delle eccezioni automatica, tieni presente quanto segue:

• Tutte le eccezioni inviate utilizzando la misurazione delle eccezioni automatica vengono registrate come irreversibili in Google Analytics.
• Per impostazione predefinita, il campo della descrizione viene impostato automaticamente utilizzando il tipo di eccezione, il nome della classe, il nome del metodo e il nome del thread.

Descrizioni delle eccezioni di analisi

L'SDK fornisce un StandardExceptionParser per semplificare la procedura di ricezione e invio delle descrizioni delle eccezioni a 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.
}

Puoi anche implementare il tuo parser implementando l'interfaccia ExceptionParser e chiamando il relativo metodo setDescription quando invii un'eccezione a Google Analytics.