بدء استخدام Crashlytics على منصات Apple

اختيار النظام الأساسي: ‫iOS+ Android Android NDK Flutter Unity


يوضّح هذا الدليل كيفية بدء استخدام Firebase Crashlytics في تطبيقك على منصات Apple (مثل تطبيق iOS).

بعد إعداد حزمة تطوير البرامج (SDK) Firebase Crashlytics في تطبيقك، يمكنك الحصول على تقارير شاملة عن الأعطال في وحدة تحكّم Firebase. باستخدام Crashlytics لمنصات Apple، يمكنك الحصول على تقارير عن الأعطال والأخطاء غير الخطيرة.

للحصول على مساعدة من الذكاء الاصطناعي، انسخ الطلب أدناه إلى وكيل الترميز المستنِد إلى الذكاء الاصطناعي (مثل Antigravity وClaude Code وCodex وCursor). يمكنك تخصيص الطلب وتكراره مع الوكيل. يمكنك الانتقال إلى مهارات وكلاء Firebase للحصول على معلومات مفصّلة حول التثبيت. 

Help me use Firebase in my app.
1. Make sure that **Firebase agent skills** are installed and updated. For Claude Code, Codex, or Cursor agents, help me install the Firebase plugin. For other agents, run `npx skills add firebase/agent-skills`.  Always try to use **Firebase agent skills** for Firebase-related tasks.
2. Help me set up Firebase Crashlytics for my app.

قبل البدء

يتطلّب إعداد Crashlytics تنفيذ مهام في كلّ من وحدة تحكّم Firebase وبيئة التطوير المتكاملة (IDE) (مثل إضافة ملف إعداد Firebase وحزمة تطوير البرامج (SDK) الخاصة بـ Crashlytics). لإنهاء عملية الإعداد، عليك فرض حدوث عُطل تجريبي لإرسال تقرير العُطل الأول إلى Firebase.

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

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

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

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

    يُرجى العلم أنّ سجلّات مسار التنقل متوفّرة لجميع منصات Apple المتوافقة مع Crashlytics باستثناء watchOS.

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

استخدِم أداة Swift Package Manager لتثبيت الملحقات المطلوبة في Firebase وإدارتها.

  1. في Xcode، بعد فتح مشروع تطبيقك، انتقِل إلى ملف > إضافة حِزم (File > Add Packages).
  2. عندما يُطلب منك ذلك، أضِف مستودع حزمة تطوير البرامج (SDK) لمنصات Apple على Firebase:
    3.   https://github.com/firebase/firebase-ios-sdk.git
  3. اختَر مكتبة Crashlytics.
  4. للاستفادة من سجلّات مسار التنفيذ، أضِف أيضًا حزمة تطوير البرامج (SDK) الخاصة بـ Google Analytics إلى تطبيقك. تأكَّد من تفعيل "إحصاءات Google" في مشروعك على Firebase.
  5. أضِف العلامة -ObjC إلى قسم علامات الربط الأخرى (Other Linker Flags) في إعدادات الإنشاء الخاصة بالهدف.
  6. (نظام التشغيل macOS فقط) في Info.plist، أضِف المفتاح NSApplicationCrashOnExceptions واضبطه على YES.
  7. بعد الانتهاء، سيبدأ Xcode تلقائيًا في حلّ التبعيات وتنزيلها في الخلفية.

بعد ذلك، اضبط إعدادات وحدة Firebase كما يلي:

  1. استورِد وحدة Firebase في بنية App أو UIApplicationDelegate:

    Swift 

    import Firebase

    Objective-C 

    @import Firebase;

  2. اضبط FirebaseApp مثيلاً مشتركًا، عادةً في طريقة application(_:didFinishLaunchingWithOptions:) الخاصة بمندوب تطبيقك:

    Swift 

    // Use the Firebase library to configure APIs.
FirebaseApp.configure()

    Objective-C 

    // Use the Firebase library to configure APIs.
[FIRApp configure];

الخطوة 2: إعداد Xcode لتحميل ملفات dSYM تلقائيًا

لإنشاء تقارير أعطال قابلة للقراءة، يحتاج Crashlytics إلى ملفات رموز تصحيح الأخطاء (dSYM) الخاصة بمشروعك. توضّح الخطوات التالية كيفية ضبط Xcode لإنشاء ملفات dSYM ومعالجتها وتحميلها تلقائيًا عند إنشاء تطبيقك.

  1. افتح مساحة عمل Xcode الخاصة بمشروعك، ثم اختَر ملف المشروع في أداة التنقّل على اليمين.

  2. من قائمة الأهداف، اختَر هدف الإنشاء الرئيسي.

  3. انقر على علامة التبويب إعدادات الإصدار، ثم أكمل الخطوات التالية لكي ينتج Xcode ملفات dSYM لعمليات الإنشاء.

    1. انقر على الكل، ثم ابحث عن debug information format.

    2. اضبط تنسيق معلومات تصحيح الأخطاء على DWARF with dSYM File لجميع أنواع الإصدارات.

  4. انقر على علامة التبويب مراحل الإنشاء، ثم أكمِل الخطوات التالية ليتمكّن Xcode من معالجة ملفات dSYM وتحميلها.

    1. انقر على > مرحلة تنفيذ نص برمجي جديد.

      تأكَّد من أنّ مرحلة تنفيذ البرنامج النصي الجديدة هذه هي آخر مرحلة إنشاء في مشروعك، وإلا لن يتمكّن Crashlytics من معالجة ملفات dSYM بشكل سليم.

    2. وسِّع قسم تشغيل البرنامج النصي الجديد.

    3. في حقل النص البرمجي (الموجود ضمن التصنيف Shell)، أضِف النص البرمجي التالي.

      تعالج هذه السكربت ملفات dSYM الخاصة بمشروعك وتحمّلها إلى Crashlytics.

      "${BUILD_DIR%/Build/*}/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/run"

    4. في قسم ملفات الإدخال، أضِف مسارات المواقع الجغرافية للملفات التالية:

      ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}
       
      ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${PRODUCT_NAME}
       
      ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Info.plist
       
      $(TARGET_BUILD_DIR)/$(UNLOCALIZED_RESOURCES_FOLDER_PATH)/GoogleService-Info.plist
       
      $(TARGET_BUILD_DIR)/$(EXECUTABLE_PATH)
       إذا كان لديك ENABLE_USER_SCRIPT_SANDBOXING=YES وENABLE_DEBUG_DYLIB=YES في إعدادات إصدار مشروعك، فأدرِج ما يلي: 
      ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${PRODUCT_NAME}.debug.dylib

لمزيد من المعلومات التفصيلية حول ملفات dSYM وCrashlytics (بما في ذلك كيفية تحميل ملفات dSYM يدويًا)، يُرجى الانتقال إلى مقالة الحصول على تقارير الأعطال التي تمت إزالة التشويش عنها.

الخطوة 3: فرض حدوث عُطل تجريبي لإكمال عملية الإعداد

لإكمال عملية إعداد Crashlytics والاطّلاع على البيانات الأولية في لوحة بيانات Crashlytics ضمن وحدة تحكّم Firebase، عليك فرض حدوث عُطل تجريبي.

  1. أضِف رمزًا برمجيًا إلى تطبيقك يمكنك استخدامه لإيقاف التطبيق بشكل إجباري أثناء الاختبار.

    يمكنك استخدام الرمز التالي لإضافة زر إلى تطبيقك يؤدي إلى حدوث عُطل عند الضغط عليه. يُصنّف الزرّ على أنّه "اختبار تعطُّل".

    SwiftUI 

    Button("Crash") {
  fatalError("Crash was triggered")
}

    UIKit

    Swift 

    import UIKit

class ViewController: UIViewController {
  override func viewDidLoad() {
      super.viewDidLoad()

      // Do any additional setup after loading the view, typically from a nib.

      let button = UIButton(type: .roundedRect)
      button.frame = CGRect(x: 20, y: 50, width: 100, height: 30)
      button.setTitle("Test Crash", for: [])
      button.addTarget(self, action: #selector(self.crashButtonTapped(_:)), for: .touchUpInside)
      view.addSubview(button)
  }

  @IBAction func crashButtonTapped(_ sender: AnyObject) {
      let numbers = [0]
      let _ = numbers[1]
  }
}

    Objective-C 

    #import "ViewController.h"

@implementation ViewController
‐ (void)viewDidLoad {
    [super viewDidLoad];

    // Do any additional setup after loading the view, typically from a nib.

    UIButton* button = [UIButton buttonWithType:UIButtonTypeRoundedRect];
    button.frame = CGRectMake(20, 50, 100, 30);
    [button setTitle:@"Test Crash" forState:UIControlStateNormal];
    [button addTarget:self action:@selector(crashButtonTapped:)
        forControlEvents:UIControlEventTouchUpInside];
    [self.view addSubview:button];
}

‐ (IBAction)crashButtonTapped:(id)sender {
    @[][1];
}

@end

  2. أنشئ تطبيقك وشغِّله في Xcode مع إيقاف مصحّح أخطاء Xcode.

    1. انقر على إنشاء ثم تشغيل المخطط الحالي لإنشاء تطبيقك على جهاز اختبار أو محاكي.

    2. انتظِر إلى أن يتم تشغيل تطبيقك، ثم انقر على إيقاف تشغيل المخطط أو الإجراء لإغلاق النسخة الأولية من تطبيقك، لأنّ هذه النسخة الأولية تتضمّن أداة تصحيح الأخطاء التي تتداخل مع Crashlytics.

  3. فرض حدوث عطل في الاختبار لإرسال تقرير العطل الأول لتطبيقك:

    1. افتح تطبيقك من الشاشة الرئيسية لجهاز الاختبار أو المحاكي.

    2. في تطبيقك، اضغط على الزر "اختبار التعطُّل" الذي أضفته باستخدام الرمز أعلاه.

    3. بعد تعطُّل تطبيقك، شغِّله مرة أخرى من Xcode حتى يتمكّن تطبيقك من إرسال تقرير التعطُّل إلى Firebase.

  4. في Firebaseوحدة التحكّم، انتقِل إلى DevOps & Engagement > Crashlyticsلوحة البيانات للبحث عن تقرير تعطل الاختبار.

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


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

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