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

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

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

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

قبل ان تبدأ

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

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

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

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

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

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

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

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.4.3")
    implementation("com.google.firebase:firebase-analytics-ktx:21.3.0")
}

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

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.4.3")
    implementation("com.google.firebase:firebase-analytics:21.3.0")
}

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

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

   Kotlin

   plugins {
       id("com.android.application") version "7.2.0" apply false
       // ...
   
       // Make sure that you have the Google services Gradle plugin dependency
       id("com.google.gms.google-services") version "4.3.15" 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.2.0' apply false
       // ...
   
       // Make sure that you have the Google services Gradle plugin dependency
       id 'com.google.gms.google-services' version '4.3.15' 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.

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
          }
      }
  }
}

// ...

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