الأعطال والاستثناءات

يقدِّم هذا المستند نظرة عامة عالية المستوى حول قياس الأعطال والاستثناءات باستخدام الإصدار 4 من حزمة تطوير البرامج (SDK) من "إحصاءات Google" لنظام التشغيل Android.

نظرة عامة

يتيح لك قياس الأعطال والاستثناءات قياس عدد الأعطال والاستثناءات التي تم رصدها وغير المرتبطة بها التي تحدث في تطبيقك ونوعها. يتضمّن الاستثناءات الحقول التالية:

اسم الحقل	النوع	مطلوبة	الوصف
الوصف	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" مطلقًا لأنها قد تحتوي على معلومات تحديد الهوية الشخصية.

قياس الاستثناءات غير المستفادة

تمثّل الاستثناءات غير المعقّدة الحالات التي واجه فيها تطبيقك حالات غير متوقعة في وقت التشغيل وغالبًا ما تكون مميتة، ما يؤدي إلى تعطُّل التطبيق. يمكن إرسال الاستثناءات غير المكتشفة إلى "إحصاءات Google" تلقائيًا من خلال ضبط قيمة الإعداد ga_reportUncaughtExceptions أو باستخدام الفئة ExceptionReporter.

الضبط التلقائي

لإرسال جميع الاستثناءات غير المرصودة في تطبيقك تلقائيًا إلى "إحصاءات Google"، أضِف هذا السطر إلى ملف إعداد XML:

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

بعد إرسال استثناء باستخدام قياس الاستثناءات التلقائي، سيتم تمرير الاستثناء إلى معالج الاستثناء التلقائي في Thread.

ملاحظة: يمكن ضبط هذه القيمة على true فقط في جهاز تتبُّع واحد. وفي حال تحديدها لعدة أجهزة تتبُّع، سيتم استخدام آخر جهاز تتبُّع تم إعداده.

استخدام عملية تنفيذ متقدّمة

استخدِم الفئة ExceptionReporter لتنفيذ قياس تلقائي غير مرصود للاستثناء إذا كنت تستخدم عملية تنفيذ متقدّمة ولا تستخدم قيمة الإعداد ga_reportUncaughtExceptions.

يمكن استخدام ExceptionReporter كمعالج استثناء غير مرصود تلقائيًا لسلسلة محادثات معيّنة أو لجميع سلاسل المحادثات في تطبيقك. بعد إرسال استثناء إلى "إحصاءات Google"، يمكن للفئة ExceptionReporter ضبط الاستثناء اختياريًا إلى معالج استثناء غير مرصود تقدّمه.

ينشئ الرمز التالي كائن ExceptionReporter جديدًا ويضبطه كمعالج الاستثناء التلقائي الجديد غير المرصود. ونتيجةً لذلك، سيتم إرسال كل استثناء غير مرصود إلى "إحصاءات Google" ثم تمريره إلى معالج الاستثناء السابق غير المرصود. بالنسبة إلى معظم التطبيقات، سيسجل المعالج الافتراضي الاستثناء في السجل وينهي التطبيق.

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

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

عند استخدام قياس الاستثناءات التلقائي، يجب مراعاة ما يلي:

• يتم الإبلاغ عن جميع الاستثناءات التي تم إرسالها باستخدام قياس الاستثناءات التلقائي على أنّها خطيرة في "إحصاءات Google".
• يتم ضبط حقل الوصف تلقائيًا باستخدام نوع الاستثناء واسم الفئة واسم الطريقة واسم سلسلة المحادثات.

تحليل أوصاف الاستثناء

توفّر حزمة تطوير البرامج (SDK) StandardExceptionParser لتبسيط عملية الحصول على أوصاف الاستثناءات وإرسالها إلى "إحصاءات Google":

// 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 واستدعاء طريقة setDescription عند إرسال استثناء إلى "إحصاءات Google".