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

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

يوضِّح هذا الدليل كيفية ضبط إعدادات ميزة الإبلاغ عن الأعطال باستخدام IDE IDE Firebase Crashlytics SDK لـ NDK.

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

قبل البدء

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

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

    • إذا لم يكن Google Analytics مفعّلاً في مشروعك الحالي على Firebase، يمكنك تفعيله من علامة التبويب عمليات الدمج ضمن > إعدادات المشروع في وحدة تحكُّم 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.5.1"))

    // 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.2.1")
    implementation("com.google.firebase:firebase-analytics:22.1.2")
}
هل تبحث عن وحدة مكتبة خاصة بلغة 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 مفعَّل صراحةً ويستخدم أحدث إصدار من حزمة Crashlytics SDK لـ 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