當機和例外狀況

本文件概要說明使用 Android 適用的 Google Analytics (分析) SDK v4 評估的當機和例外狀況。

總覽

您可以透過當機和例外狀況評估功能，評估應用程式中偵測到的當機和未偵測到的當機和例外狀況數量與類型。例外狀況有下列欄位：

欄位名稱	類型	必要	說明
說明	String	否	例外狀況的說明 (最多 100 個半形字元)。接受 null。
isFatal	boolean	可	指出例外狀況是否為嚴重例外狀況。true 表示嚴重。

系統主要會在「當機和例外狀況」報表中提供當機和例外狀況資料。

偵測到例外狀況

系統會捕捉到例外狀況 (例如要求提供資料要求期間偶爾發生網路連線逾時)，而您已實作程式碼來處理的程式碼。

透過在追蹤程式上設定例外狀況欄位值並傳送命中，以評估偵測到的例外狀況，如以下範例所示：

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

如要進一步瞭解 getTracker 方法，請參閱「 進階設定」。

查看範例應用程式中的程式碼片段

下列程式碼片段是傳送例外狀況的 Fragment 範例：

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

警告： 請勿將例外狀況訊息 (例如 e.getMessage()) 傳送至 Google Analytics (分析)，因為其中可能包含個人識別資訊。

未偵測到例外狀況評估

未偵測到的例外狀況代表應用程式在執行階段遇到意外狀況，且經常嚴重導致應用程式異常終止的情況。只要設定 ga_reportUncaughtExceptions 設定值或使用 ExceptionReporter 類別，即可將未擷取的例外狀況自動傳送至 Google Analytics (分析)。

自動設定

如要自動將應用程式中所有未偵測到的例外狀況傳送至 Google Analytics (分析)，請在 XML 設定檔中加入下列程式碼：

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

使用自動例外狀況評估功能傳送例外狀況後，例外狀況會傳遞至 Thread 的預設例外狀況處理常式。

注意：這個值只能設為單一追蹤程式的 true。如果指定多個追蹤器，將會使用最後一個要初始化的追蹤器。

使用進階導入

如果您是使用進階實作，且未使用 ga_reportUncaughtExceptions 設定值，請使用 ExceptionReporter 類別實作自動擷取的例外狀況評估。

ExceptionReporter 可做為特定執行緒或應用程式中所有執行緒的預設未偵測到的例外狀況處理常式。將例外狀況傳送至 Google Analytics (分析) 後，ExceptionReporter 類別可選擇將例外狀況傳遞給您提供的未偵測到的例外狀況處理常式。

下列程式碼會建立新的 ExceptionReporter 物件，並將其設為新的預設未偵測到的例外狀況處理常式。因此，每個未偵測到的例外狀況都會傳送至 Google Analytics (分析)，然後再傳送至先前未偵測到的例外狀況處理常式。對於大多數應用程式，預設處理常式會將例外狀況記錄至記錄並終止應用程式。

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

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

使用自動例外狀況評估時，請注意下列事項：

• 凡是使用自動例外狀況評估功能傳送的例外狀況，Google Analytics (分析) 都會將其回報為嚴重錯誤。
• 根據預設，系統會透過例外狀況類型、類別名稱、方法名稱和執行緒名稱自動設定說明欄位。

剖析例外狀況說明

SDK 提供 StandardExceptionParser，可簡化取得例外狀況說明並傳送至 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.
}

您也可以導入 ExceptionParser 介面，並在傳送例外狀況給 Google Analytics (分析) 時呼叫其 setDescription 方法來導入自己的剖析器。