الحصول على تقارير أعطال Android NDK

إذا كان تطبيق Android يحتوي على مكتبات أصلية، يمكنك تفعيل عمليات تتبُّع تسلسل استدعاء الدوال البرمجية بالكامل وتقارير الأعطال التفصيلية للرمز البرمجي الأصلي. من "Firebase Crashlytics" مع بعض التعديلات الصغيرة على إصدار تطبيقك التكوين.

يوضِّح هذا الدليل طريقة ضبط تقارير الأعطال باستخدام حزمة تطوير برامج (SDK) واحدة (Firebase Crashlytics) خاصة بحزمة NDK

للاطّلاع على كيفية بدء استخدام "Crashlytics" في Unity المشروعات، فتحقق من دليل البدء في Unity

قبل البدء

  1. أضِف Firebase إلى جهاز Android إذا لم يسبق لك إجراء ذلك. مشروعك. إذا لم يكن لديك تطبيق Android، يمكنك تنزيله نموذج تطبيق.

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

    • إذا لم يكن مشروعك الحالي في Firebase يحتوي على Google Analytics مُفعَّل، يمكنك تفعيل "Google Analytics" من في علامة التبويب عمليات الدمج على إعدادات المشروع في وحدة التحكم Firebase.

    • إذا كنت بصدد إنشاء مشروع جديد على Firebase، فعِّل Google Analytics أثناء سير عمل إنشاء المشروع.

  3. تأكَّد من أنّ تطبيقك يتضمّن الحد الأدنى من الإصدارات المطلوبة التالية:

    • ‫Gradle 8.0
    • الإصدار 8.1.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android
    • الإصدار 4.4.1 من المكوّن الإضافي لنظام Gradle لخدمات Google

الخطوة 1: إضافة حزمة تطوير البرامج (SDK) لنظام التشغيل Crashlytics لنظام NDK إلى تطبيقك

في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle)، أضِف الاعتمادية لمكتبة Crashlytics NDK لنظام التشغيل Android. ننصح باستخدام Firebase Android BoM للتحكم في إصدارات المكتبة.

للحصول على تجربة مثالية مع Crashlytics، ننصحك بتفعيل Google Analytics في مشروعك على Firebase وإضافة حزمة تطوير البرامج (SDK) لمنصّة Firebase في "إحصاءات Google" إلى تطبيقك. 

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.3.0"))

    // Add the dependencies for the Crashlytics NDK and Analytics libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-crashlytics-ndk")
    implementation("com.google.firebase:firebase-analytics")
}

باستخدام Firebase Android BoM، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات Firebase لنظام التشغيل Android.

(بديل) إضافة اعتماديات مكتبة Firebase بدون استخدام BoM

إذا اخترت عدم استخدام Firebase BoM، يجب تحديد كل إصدار من مكتبة Firebase في سطر التبعية الخاص به.

يُرجى العلم أنّه في حال استخدام مكتبات Firebase متعدّدة في تطبيقك، ننصحك بشدة باستخدام BoM لإدارة إصدارات المكتبة، ما يضمن توافق جميع الإصدارات. 

dependencies {
    // Add the dependencies for the Crashlytics NDK and Analytics libraries
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-crashlytics-ndk:19.1.0")
    implementation("com.google.firebase:firebase-analytics:22.1.0")
}
هل تبحث عن وحدة مكتبة خاصة بلغة Kotlin؟ ستبدأ بعد تشرين الأول (أكتوبر) 2023 (Firebase BoM 32.5.0)، بإمكان مطوّري البرامج بلغة Kotlin وJava. تعتمد على وحدة المكتبة الرئيسية (لمزيد من التفاصيل، راجع الأسئلة الشائعة حول هذه المبادرة).

الخطوة 2: إضافة المكوّن الإضافي Crashlytics Gradle إلى تطبيقك

  1. في ملف Gradle على مستوى الجذر (على مستوى المشروع) (<project>/build.gradle.kts أو <project>/build.gradle)، أضِف السمة Crashlytics المكوّن الإضافي لنظام Gradle المتوافق مع كتلة plugins:

    Kotlin 

    plugins {
    // Make sure that you have the AGP plugin 8.1+ dependency
    id("com.android.application") version "8.1.4" apply false
    // ...

    // Make sure that you have the Google services Gradle plugin 4.4.1+ dependency
    id("com.google.gms.google-services") version "4.4.2" apply false

    // Add the dependency for the Crashlytics Gradle plugin
    id("com.google.firebase.crashlytics") version "3.0.2" apply false
}

    Groovy 

    plugins {
    // Make sure that you have the AGP plugin 8.1+ dependency
    id 'com.android.application' version '8.1.4' apply false
    // ...

    // Make sure that you have the Google services Gradle plugin 4.4.1+ dependency
    id 'com.google.gms.google-services' version '4.4.2' apply false

    // Add the dependency for the Crashlytics Gradle plugin
    id 'com.google.firebase.crashlytics' version '3.0.2' apply false
}

  2. في ملف Gradle الخاص بالوحدة (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle)، أضِف المكوّن الإضافي Crashlytics Gradle:

    Kotlin 

    plugins {
  id("com.android.application")
  // ...

  // Make sure that you have the Google services Gradle plugin
  id("com.google.gms.google-services")

  // Add the Crashlytics Gradle plugin
  id("com.google.firebase.crashlytics")
}

    Groovy 

    plugins {
  id 'com.android.application'
  // ...

  // Make sure that you have the Google services Gradle plugin
  id 'com.google.gms.google-services'

  // Add the Crashlytics Gradle plugin
  id 'com.google.firebase.crashlytics'
}

الخطوة 3: تثبيت إضافة Crashlytics إلى تصميمك

في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle)، اضبط إضافة Crashlytics.

Kotlin 

import com.google.firebase.crashlytics.buildtools.gradle.CrashlyticsExtension

// ...

android {
  // ...
  buildTypes {
      getByName("release") {
          // Add this extension
          configure<CrashlyticsExtension> {
              // Enable processing and uploading of native symbols to Firebase servers.
              // By default, this is disabled to improve build speeds.
              // This flag must be enabled to see properly-symbolicated native
              // stack traces in the Crashlytics dashboard.
              nativeSymbolUploadEnabled = true
          }
      }
  }
}

Groovy 

// ...

android {
  // ...
  buildTypes {
      release {
          // Add this extension
          firebaseCrashlytics {
              // Enable processing and uploading of native symbols to Firebase servers.
              // By default, this is disabled to improve build speeds.
              // This flag must be enabled to see properly-symbolicated native
              // stack traces in the Crashlytics dashboard.
              nativeSymbolUploadEnabled true
          }
      }
  }
}

الخطوة 4: إعداد التحميل التلقائي للرموز الأصلية

لإنشاء عمليات تتبُّع تسلسُل استدعاء الدوال البرمجية القابلة للقراءة من أعطال NDK، يحتاج Crashlytics إلى معرفة حول الرموز في قيمك الثنائية الأصلية. المكوّن الإضافي "Crashlytics" لنظام Gradle تشمل uploadCrashlyticsSymbolFileBUILD_VARIANT لأتمتة هذه العملية.

  1. وحتى تتمكن من الوصول إلى مهمة التحميل التلقائي للرموز، تأكد من تم ضبط nativeSymbolUploadEnabled على true في الوحدة (على مستوى التطبيق) Gradle.

  2. ولكي تظهر أسماء الطرق في عمليات تتبُّع تسلسل استدعاء الدوال البرمجية، عليك الاستدعاء صراحةً uploadCrashlyticsSymbolFileBUILD_VARIANT بعد كل إصدار من مكتبة NDK. على سبيل المثال:

    >./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT

  3. حزمة تطوير البرامج (SDK) "Crashlytics" الخاصة بـ NDK والمكوّن الإضافي "Crashlytics" لنظام Gradle على وجود معرّف إصدار GNU داخل الكائنات المشتركة الأصلية.

    يمكنك التأكّد من توفّر هذا المعرّف عن طريق تنفيذ readelf -n على كل برنامج ثنائي. إذا كان رقم تعريف الإصدار غير موجود، أضِف -Wl,--build-id إلى حساب نظام التصميم لحلّ المشكلة.

الخطوة 5: فرض عطل تجريبي لإنهاء الإعداد

لإكمال عملية إعداد Crashlytics والاطّلاع على البيانات الأولية في لوحة بيانات Crashlytics في وحدة تحكّم Firebase، عليك فرض تعطُّل اختباري.

  1. أضِف رمزًا إلى تطبيقك يمكنك استخدامه لفرض حدوث عطل تجريبي.

    يمكنك استخدام الرمز التالي في MainActivity لتطبيقك لإضافة زر إلى تطبيقك يؤدي إلى تعطُّله عند الضغط عليه. تمت تسمية الزر "اختبار العطل"

    Kotlin+KTX 

    val crashButton = Button(this)
crashButton.text = "Test Crash"
crashButton.setOnClickListener {
   throw RuntimeException("Test Crash") // Force a crash
}

addContentView(crashButton, ViewGroup.LayoutParams(
       ViewGroup.LayoutParams.MATCH_PARENT,
       ViewGroup.LayoutParams.WRAP_CONTENT))

    Java 

    Button crashButton = new Button(this);
crashButton.setText("Test Crash");
crashButton.setOnClickListener(new View.OnClickListener() {
   public void onClick(View view) {
       throw new RuntimeException("Test Crash"); // Force a crash
   }
});

addContentView(crashButton, new ViewGroup.LayoutParams(
       ViewGroup.LayoutParams.MATCH_PARENT,
       ViewGroup.LayoutParams.WRAP_CONTENT));

  2. أنشئ تطبيقك وشغِّله.

  3. يمكنك فرض حدوث عطل في الاختبار لإرسال أول تقرير عن عطل في تطبيقك:

    1. افتح تطبيقك من جهاز الاختبار أو المحاكي.

    2. اضغط على "اختبار التعطّل" في تطبيقك الذي أضفته باستخدام الرمز أعلاه.

    3. بعد تعطُّل تطبيقك، أعِد تشغيله حتى يرسل العُطل. إرسال تقرير إلى Firebase.

  4. انتقِل إلى لوحة بيانات Crashlytics في وحدة تحكّم Firebase للاطّلاع على الأعطال في الاختبار.

    إذا أعدنا تحميل وحدة التحكّم ولم يظهر لنا تعذُّر تشغيل الاختبار بعد مرور خمس دقائق،فعِّل تسجيل تصحيح الأخطاء للاطّلاع على ما إذا كان تطبيقك يُرسِل تقارير الأعطال.


هذا كل ما في الأمر. تتتبّع أداة Crashlytics الآن تطبيقك بحثًا عن الأعطال، ويمكنك الاطّلاع على تقارير الأعطال والإحصاءات وفحصها في لوحة بيانات Crashlytics.

الخطوات التالية

  • (موصى به) يمكنك الحصول على مساعدة لتصحيح الأعطال الناتجة عن أخطاء الذاكرة الأصلية عن طريق جمع تقارير GWP-ASan يمكن أن ترتبط هذه الأخطاء المتعلقة بالذاكرة بتلف الذاكرة داخل تطبيقك، وهو السبب الرئيسي للثغرات الأمنية في التطبيق. للاستفادة من ميزة تصحيح الأخطاء هذه، عليك التأكّد من أنّ تطبيقك يتضمّن تم تفعيل GWP-ASan صراحةً وتستخدم أحدث حزمة تطوير برامج (SDK) من Crashlytics لمنصة NDK (الإصدار 18.3.6 أو الإصدارات الأحدث أو Firebase BoM الإصدار 31.3.0 أو الإصدارات الأحدث).

  • تخصيص إعدادات تقارير الأعطال من خلال إضافة إعدادات تفعيل التقارير والسجلات والمفاتيح وتتبُّع الأخطاء غير المميتة

  • الدمج مع Google Play كي تتمكّن من فلترة تقارير أعطال تطبيق Android حسب Google Play المسار مباشرةً في لوحة بيانات Crashlytics يتيح لك ذلك التركيز بشكل أفضل على لوحة البيانات في عمليات الإنشاء المحدّدة.

تحديد المشاكل وحلّها

إذا ظهرت لك قوائم تتبُّع تسلسل استدعاء الدوال البرمجية مختلفة في وحدة تحكُّم Firebase وفي logcat، يُرجى الرجوع إلى دليل تحديد المشاكل وحلّها.


خيارات بديلة لتحميل الرموز

ينطبق سير العمل الرئيسي في هذه الصفحة أعلاه على إصدارات Gradle القياسية. ومع ذلك، تستخدم بعض التطبيقات إعدادات أو أدوات مختلفة (على سبيل المثال، عملية معالجة ملف APK غير Gradle). في هذه الحالات، قد تكون الخيارات التالية مفيدة لتحميل الرموز بنجاح.

الخيار: تحميل رموز لوحدات المكتبة والتبعيات الخارجية

يمكن أن يكون هذا الخيار مفيدًا في الحالات التالية:

  • إذا كنت تستخدم عملية إنشاء NDK مخصصة داخل Gradle
  • إذا كانت المكتبات الأصلية مضمّنة في مكتبة/وحدة ميزة أو تقدّمها جهة خارجية
  • إذا تعذّر إكمال مهمة تحميل الرموز التلقائية أو إذا ظهرت لك أعطال لم يتم ترميزها في لوحة البيانات

الخيار: تحميل رموز للإصدارات التي لا تستخدم Gradle أو للمكتبات الأصلية التي لم تتم إزالتها والتي لا يمكن الوصول إليها

يمكن أن يكون هذا الخيار مفيدًا في الحالات التالية:

  • في حال استخدام عملية إنشاء غير Gradle

  • إذا تم توفير المكتبات الأصلية التي لم تتم إزالتها بأي طريقة لا يمكن الوصول إليها أثناء إصدارات Gradle