بدء استخدام 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 من المكوّن الإضافي Gradle لخدمات Google

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

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

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

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

الخطوة 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.5.0" apply false
   
       // Add the dependency for the Crashlytics Gradle plugin
       id("com.google.firebase.crashlytics") version "3.0.8" 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.5.0' apply false
   
       // Add the dependency for the Crashlytics Gradle plugin
       id 'com.google.firebase.crashlytics' version '3.0.8' 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. تعتمد كل من حزمة تطوير البرامج (SDK) لـ Crashlytics في NDK والمكوّن الإضافي Gradle لـ Crashlytics على توفّر رقم تعريف إصدار 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، انتقِل إلى عمليات التطوير والتفاعل > لوحة بيانات Crashlytics للتحقّق من تقرير الأعطال التجريبي.

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

هذا كل ما في الأمر. يراقب Crashlytics الآن تطبيقك بحثًا عن الأعطال، ويمكنك عرض تقارير الأعطال وإحصاءاتها والتحقيق فيها في لوحة بيانات Crashlytics.

الخطوات التالية

• (إجراء يُنصح به) يمكنك الحصول على المساعدة في تصحيح أخطاء الأعطال الناتجة عن أخطاء الذاكرة الأصلية من خلال جمع تقارير GWP-ASan. يمكن أن ترتبط هذه الأخطاء المتعلّقة بالذاكرة بتلف الذاكرة داخل تطبيقك، وهو السبب الرئيسي للثغرات الأمنية في التطبيق. للاستفادة من ميزة تصحيح الأخطاء هذه، تأكَّد من أنّ تطبيقك يستخدم ميزة GWP-ASan بشكل صريح ويستخدم أحدث إصدار من حزمة تطوير البرامج (SDK) لـ Crashlytics في 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