الأعطال والاستثناءات - حزمة تطوير البرامج (SDK) لنظام التشغيل Android

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

نظرة عامة

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

اسم الحقل حقل أداة التتبُّع النوع مطلوبة الوصف
الوصف Fields.EX_DESCRIPTION String لا وصف للاستثناء (ما يصل إلى 100 حرف). تقبل null .
isFatal Fields.EX_FATAL boolean نعم تشير هذه السمة إلى ما إذا كان الاستثناء خطيرًا. تشير السمة true إلى أنّها بالغة الوفاة.

تتوفر بيانات الأعطال والاستثناءات بشكل أساسي في تقرير الأعطال والاستثناءات.

الاستثناءات التي تم رصدها

الاستثناءات التي تم رصدها هي الأخطاء في تطبيقك التي حدَّدت رمز معالجة الاستثناءات لها، مثل انقضاء المهلة من حين لآخر للاتصال بالشبكة أثناء طلب الحصول على بيانات.

يمكنك قياس استثناء تم رصده عن طريق ضبط قيم حقل الاستثناء على أداة التتبُّع وإرسال النتيجة، كما في هذا المثال:

/*
 * 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.
}

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

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

استخدام EasyTracker

لإرسال جميع الاستثناءات غير المرصودة في تطبيقك تلقائيًا باستخدام EasyTracker، أضِف هذا السطر إلى ملف analytics.xml: 

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

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

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

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

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

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

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

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

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

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

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

// 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.
}

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