إذا كان تطبيق Android الخاص بك يحتوي على مكتبات أصلية ، فيمكنك تمكين تتبعات المكدس الكاملة وتقارير الأعطال التفصيلية للتعليمات البرمجية الأصلية الخاصة بك من Firebase Crashlytics مع بعض التحديثات الصغيرة لتكوين إنشاء تطبيقك.
يصف هذا الدليل كيفية تكوين تقارير الأعطال باستخدام Firebase Crashlytics SDK لـ NDK.
إذا كنت تبحث عن كيفية البدء باستخدام Crashlytics في مشاريع Unity الخاصة بك، فاطلع على دليل بدء استخدام Unity .
قبل ان تبدأ
إذا لم تكن قد قمت بذلك بالفعل، فأضف Firebase إلى مشروع Android الخاص بك. إذا لم يكن لديك تطبيق Android، فيمكنك تنزيل تطبيق نموذجي .
موصى به : للحصول على ميزات مثل المستخدمين الخاليين من الأعطال، وسجلات مسارات التنقل، وتنبيهات السرعة، تحتاج إلى تمكين Google Analytics في مشروع Firebase الخاص بك.
إذا لم يتم تمكين Google Analytics في مشروعك الحالي في Firebase، فيمكنك تمكين Google Analytics من علامة التبويب عمليات التكامل في جهازك.
إذا كنت تقوم بإنشاء مشروع 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.6.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.0") implementation("com.google.firebase:firebase-analytics:21.5.0") }
الخطوة 2 : أضف المكوّن الإضافي Crashlytics Gradle إلى تطبيقك
في ملف 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.0" 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.0' apply false // Add the dependency for the Crashlytics Gradle plugin id 'com.google.firebase.crashlytics' version '2.9.9' 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 مهمة uploadCrashlyticsSymbolFile BUILD_VARIANT
لأتمتة هذه العملية.
حتى تتمكن من الوصول إلى مهمة تحميل الرموز تلقائيًا، تأكد من تعيين
nativeSymbolUploadEnabled
على القيمةtrue
في ملف Gradle الخاص بالوحدة النمطية (على مستوى التطبيق).لكي تظهر أسماء الطرق في تتبعات المكدس، يجب عليك استدعاء مهمة
uploadCrashlyticsSymbolFile BUILD_VARIANT
بشكل صريح بعد كل إنشاء لمكتبة NDK الخاصة بك. على سبيل المثال:>./gradlew app:assembleBUILD_VARIANT\ app:uploadCrashlyticsSymbolFileBUILD_VARIANT
يعتمد كل من Crashlytics SDK لـ 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 SDK لـ NDK (الإصدار 18.3.6+ أو Firebase BoM v31.3.0+).
قم بتخصيص إعداد تقرير الأعطال الخاص بك عن طريق إضافة تقارير الاشتراك والسجلات والمفاتيح وتتبع الأخطاء غير المميتة.
قم بالتكامل مع Google Play حتى تتمكن من تصفية تقارير الأعطال الخاصة بتطبيق Android الخاص بك من خلال تتبع Google Play مباشرة في لوحة معلومات Crashlytics. يتيح لك ذلك تركيز لوحة المعلومات بشكل أفضل على تصميمات محددة.
استكشاف الأخطاء وإصلاحها
إذا كنت ترى تتبعات مكدس مختلفة في وحدة تحكم Firebase وفي logcat، فارجع إلى دليل استكشاف الأخطاء وإصلاحها .
خيارات بديلة لتحميل الرموز
ينطبق سير العمل الرئيسي في هذه الصفحة أعلاه على إصدارات Gradle القياسية. ومع ذلك، تستخدم بعض التطبيقات تكوينًا أو أدوات مختلفة (على سبيل المثال، عملية إنشاء بخلاف Gradle). في هذه المواقف، قد تكون الخيارات التالية مفيدة لتحميل الرموز بنجاح.
الخيار : تحميل الرموز لوحدات المكتبة والتبعيات الخارجية
يمكن أن يكون هذا الخيار مفيدًا في المواقف التالية:
- إذا كنت تستخدم عملية إنشاء NDK مخصصة داخل Gradle
- إذا كانت مكتباتك الأصلية مبنية في وحدة مكتبة/ميزات أو مقدمة من جهة خارجية
- إذا فشلت مهمة التحميل التلقائي للرموز أو كنت ترى أعطالاً غير رمزية في لوحة المعلومات
تفترض مهمة تحميل رمز Crashlytics القياسية أنك تقوم ببناء مكتباتك الأصلية كجزء من بناء Gradle لوحدة التطبيق الخاصة بك، باستخدام أدوات إنشاء NDK القياسية مثل CMake.
ومع ذلك، إذا كنت تستخدم عملية إنشاء NDK مخصصة داخل Gradle، أو إذا كانت مكتباتك الأصلية مبنية في وحدة مكتبة/ميزات أو مقدمة من جهة خارجية، فقد تحتاج إلى تحديد المسار إلى مكتباتك غير المقطوعة بشكل صريح. لتحقيق ذلك، يمكنك إضافة خاصية unstrippedNativeLibsDir
ضمن ملحق Crashlytics في ملف بناء Gradle الخاص بك.
تأكد من إكمال المهام الأولية التالية من سير العمل الرئيسي في وقت سابق من هذه الصفحة:
لكي تتمكن مهمة تحميل الرمز التلقائي من العثور على معلومات الرمز الخاص بك، أضف ما يلي إلى ملف Gradle الخاص بالوحدة النمطية (على مستوى التطبيق) (عادةً
<project>/<app-module>/build.gradle.kts
أو<project>/<app-module>/build.gradle
):Kotlin
import com.google.firebase.crashlytics.buildtools.gradle.CrashlyticsExtension // ... android { // ... buildTypes { release { configure
{ nativeSymbolUploadEnabled = true unstrippedNativeLibsDir = file("PATH/TO/UNSTRIPPED/DIRECTORY") } } } } Groovy
// ... android { // ... buildTypes { release { firebaseCrashlytics { nativeSymbolUploadEnabled true unstrippedNativeLibsDir file("PATH/TO/UNSTRIPPED/DIRECTORY") } } } }
سيقوم البرنامج الإضافي Crashlytics بالبحث بشكل متكرر في الدليل المحدد عن المكتبات الأصلية ذات الامتداد
.so
. تقوم Crashlytics بعد ذلك باستخراج رموز تصحيح الأخطاء من جميع هذه المكتبات وتحميلها إلى خوادم Firebase.إليك ما يمكنك تحديده في خاصية
unstrippedNativeLibsDir
:أي وسيطة مسموح بها لـ
org.gradle.api.Project#files(Object...)
، بما في ذلك:java.lang.String
،java.io.File
أوorg.gradle.api.file.FileCollection
أدلة متعددة لنكهة بناء واحدة من خلال توفير قائمة أو مثيل
FileCollection
أخيرًا، فرض اختبار التعطل لإنهاء إعداد Crashlytics ورؤية البيانات الأولية في لوحة معلومات Crashlytics بوحدة تحكم Firebase.
الخيار : تحميل الرموز للإصدارات غير التابعة لـ Gradle أو المكتبات الأصلية غير المقيدة التي لا يمكن الوصول إليها
يمكن أن يكون هذا الخيار مفيدًا في المواقف التالية:
إذا كنت تستخدم عملية إنشاء أخرى غير Gradle
إذا تم توفير مكتباتك الأصلية غير المقيدة لك بطريقة لا يمكن الوصول إليها أثناء إنشاءات Gradle
يتطلب هذا الخيار تشغيل أمر Firebase CLI عند إنشاء إصدار إصدار أو أي إصدار تريد رؤية آثار المكدس المرمزة له في وحدة تحكم Firebase.
تأكد من إكمال المهام الأولية التالية من سير العمل الرئيسي في وقت سابق من هذه الصفحة:
لاحظ أنه باستخدام هذا الخيار، لن تحتاج إلى إضافة ملحق
firebaseCrashlytics
أو إعداد التحميل التلقائي للرموز لأنك ستستخدم بدلاً من ذلك Firebase CLI (الخطوات التالية أدناه) لإنشاء ملفات الرموز وتحميلها.قم بإعداد بيئتك ومشروعك لتحميل الرمز:
اتبع الإرشادات لتثبيت Firebase CLI .
إذا قمت بالفعل بتثبيت واجهة سطر الأوامر (CLI)، فتأكد من التحديث إلى الإصدار الأحدث .
(فقط للتطبيقات التي تستخدم Android API المستوى 30+) قم بتحديث قالب
AndroidManifest.xml
الخاص بتطبيقك لتعطيل وضع علامات على المؤشر:حدد المربع لإعدادات Android Player > إعدادات النشر > الإصدار > البيان الرئيسي المخصص .
افتح قالب البيان الموجود في
Assets/Plugins/Android/AndroidManifest.xml
.أضف السمة التالية إلى علامة التطبيق:
<application android:allowNativeHeapPointerTagging="false" ... />
قم ببناء مشروعك.
قم بتحميل معلومات الرموز الخاصة بك.
بمجرد الانتهاء من البناء، قم بإنشاء ملف رمز متوافق مع Crashlytics وتحميله إلى خوادم Firebase عن طريق تشغيل أمر Firebase CLI التالي:
firebase crashlytics:symbols:upload --app=FIREBASE_APP_ID PATH/TO/SYMBOLS
FIREBASE_APP_ID : معرف تطبيق Firebase Android الخاص بك (وليس اسم الحزمة الخاصة بك)
مثال لمعرف تطبيق Firebase Android:1:567383003300:android:17104a2ced0c9b9b
فيما يلي طريقتان للعثور على معرف تطبيق Firebase الخاص بك:
في ملف
google-services.json
، يكون معرف التطبيق الخاص بك هو قيمةmobilesdk_app_id
؛ أوفي وحدة تحكم Firebase، انتقل إلى إعدادات المشروع . قم بالتمرير لأسفل إلى بطاقة تطبيقاتك ، ثم انقر فوق تطبيق Firebase المطلوب للعثور على معرف التطبيق الخاص به.
PATH/TO/SYMBOLS : المسار إلى ملف الرمز الذي تم إنشاؤه بواسطة CLI
تم تصديره إلى مشروع Android Studio - يمكن أن يكون PATH/TO/SYMBOLS أي دليل. سوف يقوم Firebase CLI بالبحث بشكل متكرر في الدليل المحدد عن المكتبات الأصلية ذات الامتداد
.so
.إنشاء ملف APK مباشرةً من داخل Unity — PATH/TO/SYMBOLS هو مسار ملف الرمز المضغوط الذي تم إنشاؤه في الدليل الجذر للمشروع عند انتهاء البناء (على سبيل المثال:
myproject/myapp-1.0-v100.symbols.zip
).
عرض الخيارات المتقدمة لاستخدام أمر Firebase CLI لإنشاء ملف الرموز وتحميله
علَم وصف --generator=csym
يستخدم منشئ ملف رمز cSYM القديم بدلاً من منشئ Breakpad الافتراضي
لا ينصح للاستخدام. نوصي باستخدام منشئ ملف رمز Breakpad الافتراضي.
--generator=breakpad
يستخدم منشئ ملف رمز Breakpad
لاحظ أن الإعداد الافتراضي لإنشاء ملف الرمز هو Breakpad. استخدم هذه العلامة فقط إذا قمت بإضافتها
symbolGenerator { csym() }
في تكوين الإصدار الخاص بك وتريد تجاوزه لاستخدام Breakpad بدلاً من ذلك.--dry-run
يقوم بإنشاء ملفات الرموز ولكن لا يقوم بتحميلها
تعتبر هذه العلامة مفيدة إذا كنت تريد فحص محتوى الملفات المرسلة.
--debug
يوفر معلومات تصحيح إضافية أخيرًا، فرض اختبار التعطل لإنهاء إعداد Crashlytics ورؤية البيانات الأولية في لوحة معلومات Crashlytics بوحدة تحكم Firebase.
بعد إنشاء تطبيقك كجزء من فرض التعطل، تأكد من تشغيل أمر Firebase CLI
crashlytics:symbols:upload
لتحميل ملف الرمز الخاص بك.