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

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


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

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

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

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

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

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

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

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

از «مدیر بسته Swift» برای نصب و مدیریت وابستگی‌های 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 را به بخش پرچم‌های پیونددهنده دیگر در تنظیمات ساخت هدف اضافه کنید.
  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. از فهرست هدف‌ها، هدف ساخت اصلی‌تان را انتخاب کنید.

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

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

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

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

    1. روی > مرحله جدید اجرای متن کلیک کنید.

      مطمئن شوید که این مرحله جدید اجرای دستورگان آخرین مرحله ساخت پروژه شما است؛ درغیراین‌صورت، Crashlytics نمی‌تواند dSYM را به‌درستی پردازش کند.

    2. بخش جدید اجرای دستورگان را ازهم باز کنید.

    3. در فیلد فیلم‌نامه (واقع در زیر برچسب پوسته)، فیلم‌نامه اجرایی زیر را اضافه کنید.

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

مراحل بعدی