بدء استخدام Crashlytics لنظام Android NDK

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

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

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

قبل البدء

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

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

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

   • إذا كنت تستخدم مشروعًا حاليًا على Firebase لم يتم تفعيل Google Analytics فيه، يمكنك تفعيله في صفحة settings الإعدادات > عمليات الدمج في وحدة تحكّم Firebase.

3. تأكَّد من أنّ تطبيقك يتضمّن الحدّ الأدنى المطلوب من الإصدارات التالية:

   • ‫Gradle 8.0
   • الإصدار 8.1.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android
   • الإصدار 4.4.1 من المكوّن الإضافي في خدمات Google لنظام Gradle

الخطوة 1: إضافة حزمة تطوير البرامج (SDK) Crashlytics لـ NDK إلى تطبيقك

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

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

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

الخطوة 2: إضافة Crashlytics Gradle plugin إلى تطبيقك

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.4" apply false
   
       // Add the dependency for the Crashlytics Gradle plugin
       id("com.google.firebase.crashlytics") version "3.0.7" 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.4' apply false
   
       // Add the dependency for the Crashlytics Gradle plugin
       id 'com.google.firebase.crashlytics' version '3.0.7' 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 مهمة uploadCrashlyticsSymbolFileBUILD_VARIANT لأتمتة هذه العملية.

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

2. لكي تظهر أسماء الطرق في عمليات تتبُّع تسلسل استدعاء الدوال البرمجية، عليك استدعاء مهمة uploadCrashlyticsSymbolFileBUILD_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

   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. في وحدة تحكّم Firebase، انتقِل إلى عمليات DevOps ومعدّل الاهتمام بالتطبيق > لوحة بيانات Crashlytics للبحث عن تقرير الأعطال الخاص بالاختبار.

   إذا أعَدت تحميل وحدة التحكّم ولم يظهر لك تعطُّل الاختبار بعد خمس دقائق، يمكنك تفعيل تسجيل تصحيح الأخطاء لمعرفة ما إذا كان تطبيقك يرسل تقارير الأعطال.

هذا كل ما في الأمر. يراقب 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 العادية. ومع ذلك، تستخدم بعض التطبيقات إعدادات أو أدوات مختلفة (مثل عملية إنشاء غير Gradle). في هذه الحالات، قد تكون الخيارات التالية مفيدة لتحميل الرموز بنجاح.

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

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

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

الخيار: تحميل الرموز البرمجية للإصدارات غير المستندة إلى Gradle أو المكتبات المجمّعة من رموز برمجية أصلية غير المضغوطة التي يتعذّر الوصول إليها

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

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

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