الحصول على تقارير أعطال 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: إضافة حزمة Crashlytics SDK لـ NDK إلى تطبيقك

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

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

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.0.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 BoM، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات 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.0")
    implementation("com.google.firebase:firebase-analytics:22.0.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.1" apply false
    
        // Add the dependency for the Crashlytics Gradle plugin
        id("com.google.firebase.crashlytics") version "3.0.0" 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.1' apply false
    
        // Add the dependency for the Crashlytics Gradle plugin
        id 'com.google.firebase.crashlytics' version '3.0.0' 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 for NDK (الإصدار 18.3.6 والإصدارات الأحدث أو الإصدار 31.3.0 أو الإصدارات الأحدث من Firebase BoM).

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

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

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

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



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

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

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

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

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

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

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

  • إذا كنت تستخدم عملية تصميم غير Gradle

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