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

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

يصف هذا الدليل كيفية تكوين تقارير الأعطال باستخدام Firebase Crashlytics SDK لـ NDK.

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

قبل ان تبدأ

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

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

    • إذا لم يتم تمكين Google Analytics في مشروعك الحالي في Firebase، فيمكنك تمكين Google Analytics من علامة التبويب عمليات التكامل في جهازك. > إعدادات المشروع في وحدة تحكم Firebase.

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

الخطوة 1 : أضف Crashlytics SDK لـ NDK إلى تطبيقك

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

للحصول على تجربة مثالية مع Crashlytics، نوصي بتمكين Google Analytics في مشروع Firebase الخاص بك وإضافة Firebase SDK لـ Google Analytics إلى تطبيقك.

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:32.8.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:18.6.3")
    implementation("com.google.firebase:firebase-analytics:21.6.1")
}
هل تبحث عن وحدة مكتبة خاصة بـ 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 {
    id("com.android.application") version "7.3.0" apply false
    // ...

    // Make sure that you have the Google services Gradle plugin 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 "2.9.9" apply false
}

    Groovy

    plugins {
    id 'com.android.application' version '7.3.0' apply false
    // ...

    // Make sure that you have the Google services Gradle plugin 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 '2.9.9' 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 مهمة uploadCrashlyticsSymbolFile BUILD_VARIANT لأتمتة هذه العملية.

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

  2. لكي تظهر أسماء الطرق في تتبعات المكدس، يجب عليك استدعاء مهمة uploadCrashlyticsSymbolFile BUILD_VARIANT بشكل صريح بعد كل إنشاء لمكتبة NDK الخاصة بك. على سبيل المثال:

    >./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT

  3. يعتمد كل من Crashlytics SDK لـ 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 v31.3.0+).

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

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

استكشاف الأخطاء وإصلاحها

إذا كنت ترى تتبعات مكدس مختلفة في وحدة تحكم Firebase وفي logcat، فارجع إلى دليل استكشاف الأخطاء وإصلاحها .


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

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

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

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

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

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

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

  • إذا كنت تستخدم عملية إنشاء أخرى غير Gradle

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