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

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

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

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

قبل البدء

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

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

    • في حال عدم تفعيل "إحصاءات Google" على مشروعك الحالي في Firebase، يمكنك تفعيل "إحصاءات Google" من علامة تبويب عمليات الدمج ضمن > إعدادات المشروع في وحدة تحكُّم Firebase.

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

  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. ننصح باستخدام بنود سياسة Android في Firebase للتحكّم في نُسَخ المكتبة.

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

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.1.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")
}

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

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

إذا اخترت عدم استخدام قائمة العناصر في Firebase، يجب تحديد كل إصدار من مكتبة 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.0.1")
    implementation("com.google.firebase:firebase-analytics:22.0.1")
}
هل تبحث عن وحدة مكتبة خاصة بلغة Kotlin؟ اعتبارًا من تشرين الأول (أكتوبر) 2023 (الإصدار 32.5.0 من Firebase)، أصبح بإمكان مطوّري لغة 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.1" 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.1' 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 صراحةً في تطبيقك، وأنّه يستخدم أحدث إصدار من حزمة تطوير البرامج Crashlytics لـ NDK (الإصدار 18.3.6 أو الأحدث أو Firebase BoM الإصدار 31.3.0 أو الإصدارات الأحدث).

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

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

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

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


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

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

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

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

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

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

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

  • في حال استخدام عملية تصميم غير Gradle

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