بدء استخدام 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: إضافة حزمة تطوير البرامج (SDK) لـ "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. للاستفادة من سجلّات خطوات المستخدم، أضِف أيضًا حزمة Firebase 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. من قائمة TARGETS (الأهداف)، اختَر هدف الإصدار الرئيسي.

  3. انقر على علامة التبويب إعدادات الإصدار (Build Settings)، ثم أكمِل الخطوات التالية لكي ينشئ Xcode ملفات dSYM لإصداراتك.

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

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

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

    1. انقر على > New Run Script Phase (مرحلة تشغيل نص برمجي جديدة).

      تأكَّد من أنّ مرحلة Run Script الجديدة هي آخر مرحلة إنشاء في مشروعك، وإلا لن يتمكّن 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، انتقِل إلى عمليات التطوير والتفاعل > لوحة بيانات Crashlytics للتحقّق من تقرير الأعطال التجريبي.

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


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

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