إذا كان تطبيقك على Android يحتوي على مكتبات أصلية، يمكنك تفعيل عمليات تتبُّع تسلسل استدعاء الدوال البرمجية الكاملة وتقارير الأعطال التفصيلية للرمز البرمجي الأصلي من Firebase Crashlytics من خلال إجراء بضعة تحديثات صغيرة على تهيئة إصدار تطبيقك.
يوضّح هذا الدليل طريقة إعداد تقارير الأعطال باستخدام حزمة تطوير البرامج (SDK) لمنصة Firebase Crashlytics من أجل NDK.
إذا كنت تبحث عن طريقة لبدء استخدام Crashlytics في مشاريع Unity، يمكنك الاطّلاع على دليل البدء في Unity.
قبل البدء
أضِف Firebase إلى مشروع Android إذا لم يسبق لك إجراء ذلك. إذا لم يكن لديك تطبيق Android، يمكنك تنزيل نموذج تطبيق.
إجراء مقترَح: للحصول تلقائيًا على سجلّات شريط التنقّل لفهم إجراءات المستخدم التي تؤدي إلى تعطُّل أو حدث غير خطير أو خطأ ANR، يجب تفعيل "إحصاءات Google" في مشروعك على Firebase.
في حال عدم تفعيل "إحصاءات Google" على مشروعك الحالي في Firebase، يمكنك تفعيل "إحصاءات Google" من علامة تبويب عمليات الدمج ضمن
في وحدة تحكُّم Firebase. > إعدادات المشروع إذا كنت بصدد إنشاء مشروع جديد على Firebase، فعِّل "إحصاءات Google" أثناء سير عمل إنشاء المشروع.
تأكَّد من أنّ تطبيقك يتضمّن الحد الأدنى من الإصدارات المطلوبة التالية:
- معيار Gradle 8.0
- الإصدار 8.1.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android
- الإصدار 4.4.1 من المكوّن الإضافي لنظام Gradle لخدمات Google
الخطوة 1: إضافة حزمة تطوير البرامج (SDK) في Crashlytics لـ NDK إلى تطبيقك
في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً<project>/<app-module>/build.gradle.kts
أو
<project>/<app-module>/build.gradle
)، أضِف التبعية لمكتبة Crashlytics NDK لنظام التشغيل Android. ننصح باستخدام
بنود سياسة Android في Firebase
للتحكّم في نُسَخ المكتبة.
للحصول على أفضل تجربة في استخدام Crashlytics، ننصحك بتفعيل "إحصاءات Google" في مشروعك على Firebase وإضافة حزمة تطوير البرامج (SDK) لمنصّة Firebase الخاصة بخدمة "إحصاءات Google" إلى تطبيقك.
dependencies { // Import the BoM for the Firebase platform implementation(platform("com.google.firebase:firebase-bom:33.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") }
باستخدام أداة إدارة قوائم التشغيل Android في Firebase، سيستخدم تطبيقك دائمًا الإصدارات المتوافقة من مكتبات 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.1") implementation("com.google.firebase:firebase-analytics:22.0.1") }
الخطوة 2: إضافة المكوّن الإضافي Crashlytics Gradle إلى تطبيقك
في ملف 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.2" apply false // Add the dependency for the Crashlytics Gradle plugin id("com.google.firebase.crashlytics") version "3.0.1" 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.2' apply false // Add the dependency for the Crashlytics Gradle plugin id 'com.google.firebase.crashlytics' version '3.0.1' apply false }
في ملف 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
لبرمجة هذه العملية.
لتتمكن من الوصول إلى مَهمة التحميل التلقائي للرموز، احرص على ضبط
nativeSymbolUploadEnabled
علىtrue
في ملف Gradle للوحدة (على مستوى التطبيق).لكي تظهر أسماء الطرق في عمليات تتبُّع تسلسل استدعاء الدوال البرمجية، يجب استدعاء المهمة
uploadCrashlyticsSymbolFileBUILD_VARIANT
بشكل صريح بعد كل إصدار من مكتبة NDK. على سبيل المثال:>./gradlew app:assembleBUILD_VARIANT\ app:uploadCrashlyticsSymbolFileBUILD_VARIANT
يعتمد كل من حزمة تطوير البرامج (SDK) في Crashlytics لـ NDK والمكون الإضافي Crashlytics Gradle على وجود رقم تعريف إصدار GNU داخل الكائنات المشتركة الأصلية.
يمكنك التأكّد من توفّر هذا المعرّف من خلال تنفيذ
في كل برنامج ثنائي. في حال عدم توفّر رقم تعريف الإصدار، أضِفreadelf -n
إلى علامات نظام التصميم لحلّ المشكلة.-Wl,--build-id
الخطوة 5: فرض عطل تجريبي لإنهاء الإعداد
لإنهاء إعداد Crashlytics والاطّلاع على البيانات الأولية في لوحة بيانات Crashlytics بوحدة تحكم Firebase، ستحتاج إلى فرض "إيقاف تشغيل" تجريبيًا.
أضِف رمزًا إلى تطبيقك يمكنك استخدامه لفرض حدوث عطل تجريبي.
يمكنك استخدام الرمز التالي في
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));
أنشئ تطبيقك وشغِّله.
يمكنك فرض العطل التجريبي لإرسال تقرير الأعطال الأول لتطبيقك:
افتح تطبيقك من جهاز الاختبار أو المحاكي.
في تطبيقك، اضغط على الزر "اختبار العطل" الذي أضفته باستخدام الرمز أعلاه.
بعد تعطُّل تطبيقك، أعِد تشغيله حتى يتمكّن من إرسال تقرير الأعطال إلى Firebase.
انتقِل إلى لوحة بيانات Crashlytics في وحدة تحكُّم Firebase للاطّلاع على العُطل التجريبي.
إذا حدّثت وحدة التحكم ولكن لم يظهر عطل الاختبار بعد خمس دقائق، يمكنك تفعيل تسجيل تصحيح الأخطاء لمعرفة ما إذا كان التطبيق يرسل تقارير الأعطال.
هذا كل ما في الأمر. يراقب تطبيق Crashlytics الآن تطبيقك بحثًا عن الأعطال، ويمكنك الاطّلاع على تقارير الأعطال والإحصاءات والتحقيق فيها من خلال لوحة بيانات Crashlytics.
الخطوات اللاحقة
(إجراء ننصح به) يمكنك الحصول على مساعدة في تصحيح الأعطال الناتجة عن أخطاء الذاكرة الأصلية من خلال جمع تقارير GWP-ASan. يمكن أن ترتبط هذه الأخطاء المتعلقة بالذاكرة بتلف الذاكرة داخل تطبيقك، وهو السبب الرئيسي للثغرات الأمنية في التطبيق. للاستفادة من ميزة تصحيح الأخطاء هذه، تأكَّد من تفعيل GWP-ASan صراحةً في تطبيقك، وأنّه يستخدم أحدث إصدار من حزمة تطوير البرامج Crashlytics لـ NDK (الإصدار 18.3.6 أو الأحدث أو Firebase BoM الإصدار 31.3.0 أو الإصدارات الأحدث).
خصِّص إعداد تقرير الأعطال من خلال إضافة خيار تفعيل إعداد التقارير والسجلات والمفاتيح وتتبُّع الأخطاء غير الفادحة.
الدمج مع Google Play لتتمكن من فلترة تقارير أعطال تطبيق Android حسب قناة الإصدار في Google Play مباشرةً في لوحة بيانات Crashlytics. ويتيح لك ذلك تركيز لوحة البيانات بشكل أفضل على إصدارات معيّنة.
تحديد المشاكل وحلّها
إذا ظهرت عمليات تتبُّع مختلفة لتسلسل استدعاء الدوال البرمجية في "وحدة تحكُّم Firebase" وفي سجلّ Logcat، يُرجى الرجوع إلى دليل تحديد المشاكل وحلّها.
خيارات بديلة لتحميل الرموز
ينطبق سير العمل الرئيسي في هذه الصفحة أعلاه على إصدارات Gradle القياسية. ومع ذلك، تستخدم بعض التطبيقات تهيئة أو أدوات مختلفة (على سبيل المثال، عملية إنشاء غير Gradle). في هذه الحالات، قد تكون الخيارات التالية مفيدة لتحميل الرموز بنجاح.
الخيار: تحميل رموز لوحدات المكتبة والتبعيات الخارجية
يمكن أن يكون هذا الخيار مفيدًا في الحالات التالية:
- إذا كنت تستخدم عملية إنشاء NDK مخصصة داخل Gradle
- إذا كانت المكتبات المجمّعة من رموز برمجية أصلية يتم إنشاؤها في وحدة مكتبة أو وحدة ميزات أو توفّرها جهة خارجية
- إذا فشلت مهمة التحميل التلقائي للرموز أو تظهر لك أعطال غير مرمزة في لوحة البيانات
الخيار: تحميل رموز للإصدارات التي لا تستخدم Gradle أو للمكتبات الأصلية التي لم تتم إزالتها والتي لا يمكن الوصول إليها
يمكن أن يكون هذا الخيار مفيدًا في الحالات التالية:
في حال استخدام عملية تصميم غير Gradle
إذا تم توفير المكتبات الأصلية التي لم تتم إزالتها لك بطريقة ما لا يمكن الوصول إليها أثناء إصدارات Gradle