شروع به کار با Crashlytics برای پلاتفرم‌های Apple

انتخاب پلاتفرم: iOS+ Android Android NDK Flutter Unity


این راهنما نحوه شروع به کار با Firebase Crashlytics را در برنامه پلاتفرم‌های Apple (برای مثال، برنامه iOS) شرح می‌دهد.

پس‌از راه‌اندازی کیت توسعه نرم‌افزار 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 و کیت توسعه نرم‌افزار Crashlytics). برای تکمیل راه‌اندازی، باید خرابی آزمایشی را اجباری کنید تا اولین گزارش خرابی به Firebase ارسال شود.

  1. اگر قبلاً این کار را نکرده‌اید، Firebase را به پروژه Apple خود اضافه کنید. اگر برنامه Apple ندارید، می‌توانید برنامه نمونه بارگیری کنید.

  2. توصیه‌شده: برای دریافت خودکار گزارش‌های ردپای رخدادها برای درک کنش‌های کاربر که منجر به خرابی یا رویداد غیرکشنده می‌شود باید Google Analytics را در پروژه Firebase خود فعال کنید.

    • اگر پروژه Firebase جدیدی ایجاد می‌کنید، Google Analytics را درطول گردش کار ایجاد پروژه فعال کنید.

    • اگر از پروژه Firebase موجودی استفاده می‌کنید که Google Analytics در آن فعال نیست، می‌توانید آن را در تنظیمات > صفحه ادغام‌ها کنسول Firebase فعال کنید.

    توجه داشته باشید که گزارش‌های ردپای رخدادها برای همه پلاتفرم‌های Apple که توسط Crashlytics پشتیبانی می‌شوند، به‌جز watchOS، دردسترس هستند.

مرحله ۱: کیت توسعه نرم‌افزار Crashlytics را به برنامه‌تان اضافه کنید

از Swift Package Manager برای نصب و مدیریت وابستگی‌های Firebase استفاده کنید.

  1. در Xcode، درحالی‌که پروژه برنامه‌تان باز است، به File (فایل) > Add Packages (افزودن بسته‌ها) بروید.
  2. وقتی خواسته شد، مخزن کیت توسعه نرم‌افزار Firebase برای پلاتفرم‌های Apple را اضافه کنید:
    3.   https://github.com/firebase/firebase-ios-sdk.git
  3. کتابخانه Crashlytics را انتخاب کنید.
  4. برای بهره‌مندی از گزارش‌های ردپای رخدادها، «کیت توسعه نرم‌افزار Firebase» برای Google Analytics را نیز به برنامه‌تان اضافه کنید. مطمئن شوید Google Analytics در پروژه 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];

مرحله ۲: Xcode را برای بارگذاری خودکار فایل‌های dSYM راه‌اندازی کنید

برای تولید گزارش‌های خرابی قابل‌خواندن برای انسان، Crashlytics به فایل‌های نماد اشکال‌زدایی (dSYM) پروژه شما نیاز دارد. مراحل زیر نحوه پیکربندی Xcode را برای تولید خودکار dSYM، پردازش آن‌ها، و بارگذاری فایل‌ها در هر زمان که برنامه‌تان را می‌سازید شرح می‌دهد.

  1. فضای کاری Xcode پروژه را باز کنید، سپس فایل پروژه آن را در ناوبر سمت راست انتخاب کنید.

  2. از فهرست TARGETS، هدف ساخت اصلی‌تان را انتخاب کنید.

  3. روی برگه تنظیمات ساخت کلیک کنید، سپس مراحل زیر را تکمیل کنید تا Xcode برای ساخت‌های شما dSYM تولید کند.

    1. روی همه کلیک کنید، سپس debug information format را جستجو کنید.

    2. قالب اطلاعات اشکال‌زدایی را برای همه انواع ساخت روی DWARF with dSYM File تنظیم کنید.

  4. روی برگه Build Phases کلیک کنید، سپس مراحل زیر را تکمیل کنید تا Xcode بتواند dSYM شما را پردازش کند و فایل‌ها را بارگذاری کند.

    1. روی > New Run Script Phase (فاز جدید اجرای متن) کلیک کنید.

      مطمئن شوید این فاز جدید اجرای اسکریپت آخرین فاز ساخت پروژه شما باشد؛ درغیراین‌صورت، 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)، به دریافت گزارش‌های خرابی ابهام‌زدایی‌شده مراجعه کنید.

مرحله ۳: برای تکمیل راه‌اندازی، خرابی آزمایشی را اجباری کنید

برای تکمیل راه‌اندازی 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 و تعامل > Crashlytics بروید تا گزارش خرابی آزمایشی را بررسی کنید.

    اگر کنسول را بازآوری کرده‌اید و هنوز خرابی آزمایشی را پس‌از پنج دقیقه نمی‌بینید، ثبت اشکال‌زدایی را فعال کنید تا ببینید آیا برنامه‌تان گزارش‌های خرابی را ارسال می‌کند یا نه.


همین! Crashlytics اکنون برنامه‌تان را ازنظر خرابی پایش می‌کند. برای مشاهده و بررسی همه گزارش‌ها و آمار، به داشبورد Crashlytics بروید.

مراحل بعدی