Bắt đầu sử dụng Crashlytics cho các nền tảng của Apple

Chọn nền tảng: iOS+ Android Android NDK Flutter Unity


Hướng dẫn này mô tả cách bắt đầu sử dụng Firebase Crashlytics trong ứng dụng trên nền tảng của Apple (ví dụ: ứng dụng iOS).

Sau khi thiết lập SDK Firebase Crashlytics trong ứng dụng, bạn có thể nhận báo cáo sự cố toàn diện trong bảng điều khiển Firebase. Với Crashlytics cho các nền tảng của Apple, bạn sẽ nhận được báo cáo về sự cố và lỗi không nghiêm trọng.

Để được trợ giúp AI, hãy sao chép câu lệnh bên dưới vào tác nhân lập trình AI (như Antigravity, Claude Code, Codex và Cursor). Bạn có thể tuỳ chỉnh câu lệnh và lặp lại với tác nhân. Truy cập vào bài viết Kỹ năng của tác nhân Firebase để biết thông tin chi tiết về cách cài đặt. 

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.

Trước khi bắt đầu

Để thiết lập Crashlytics, bạn cần thực hiện các nhiệm vụ trong cả bảng điều khiển Firebase và IDE (chẳng hạn như thêm tệp cấu hình Firebase và SDK Crashlytics). Để hoàn tất việc thiết lập, bạn cần xác định sự cố thử nghiệm để gửi báo cáo sự cố đầu tiên đến Firebase.

  1. Nếu bạn chưa thực hiện, hãy thêm Firebase vào dự án Apple. Nếu chưa có ứng dụng Apple, bạn có thể tải ứng dụng mẫu xuống.

  2. Nên dùng: Để tự động nhận nhật ký dấu vết nhằm tìm hiểu các hành động của người dùng dẫn đến sự cố hoặc sự kiện không nghiêm trọng, bạn cần bật Google Analytics trong dự án Firebase của mình.

    • Nếu bạn đang tạo dự án Firebase mới, hãy bật Google Analytics trong quy trình tạo dự án.

    • Nếu đang sử dụng một dự án Firebase hiện có chưa bật Google Analytics, bạn có thể bật tính năng này trong trang Cài đặt > Tích hợp của bảng điều khiển Firebase.

    Xin lưu ý rằng nhật ký dấu vết có sẵn cho tất cả các nền tảng của Apple được Crashlytics hỗ trợ, ngoại trừ watchOS.

Bước 1: Thêm SDK Crashlytics vào ứng dụng của bạn

Sử dụng Trình quản lý gói Swift để cài đặt và quản lý các phần phụ thuộc của Firebase.

  1. Trong Xcode, khi dự án ứng dụng của bạn đang mở, hãy chuyển đến File > Add Packages (Tệp > Thêm gói).
  2. Khi được nhắc, hãy thêm kho lưu trữ SDK Firebase cho nền tảng của Apple:
    3.   https://github.com/firebase/firebase-ios-sdk.git
  3. Chọn thư viện Crashlytics.
  4. Để tận dụng nhật ký dấu vết, hãy thêm Firebase SDK cho Google Analytics vào ứng dụng của bạn. Hãy đảm bảo rằng bạn đã bật Google Analytics trong dự án Firebase.
  5. Thêm cờ -ObjC vào phần Other Linker Flags (Cờ trình liên kết khác) trong chế độ cài đặt bản dựng của mục tiêu.
  6. (Chỉ dành cho macOS) Trong Info.plist, hãy thêm khoá NSApplicationCrashOnExceptions và đặt khoá đó thành YES.
  7. Khi hoàn tất, Xcode sẽ tự động bắt đầu phân giải và tải các phần phụ thuộc của bạn xuống ở chế độ nền.

Tiếp theo, hãy định cấu hình mô-đun Firebase:

  1. Nhập mô-đun Firebase vào cấu trúc App hoặc UIApplicationDelegate:

    Swift 

    import Firebase

    Objective-C 

    @import Firebase;

  2. Định cấu hình một thực thể dùng chung FirebaseApp, thường là trong phương thức application(_:didFinishLaunchingWithOptions:) của trình uỷ quyền ứng dụng:

    Swift 

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

    Objective-C 

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

Bước 2: Thiết lập Xcode để tự động tải các tệp dSYM lên

Để tạo báo cáo sự cố mà con người có thể đọc được, Crashlytics cần có các tệp ký hiệu gỡ lỗi (dSYM) của dự án. Các bước sau đây mô tả cách định cấu hình Xcode để tự động tạo dSYM, xử lý và tải tệp lên bất cứ khi nào bạn tạo ứng dụng.

  1. Mở không gian làm việc Xcode của dự án, sau đó chọn tệp dự án trong trình điều hướng bên trái.

  2. Trong danh sách TARGETS (MỤC TIÊU), hãy chọn mục tiêu bản dựng chính.

  3. Nhấp vào thẻ Build Settings (Cài đặt bản dựng), sau đó hoàn tất các bước sau để Xcode tạo dSYM cho bản dựng của bạn.

    1. Nhấp vào Tất cả, sau đó tìm debug information format.

    2. Đặt Debug Information Format (Định dạng thông tin gỡ lỗi) thành DWARF with dSYM File cho tất cả các loại bản dựng.

  4. Nhấp vào thẻ Build Phases (Giai đoạn xây dựng), sau đó hoàn tất các bước sau để Xcode có thể xử lý dSYM và tải tệp lên.

    1. Nhấp vào > New Run Script Phase (Giai đoạn chạy tập lệnh mới).

      Đảm bảo giai đoạn Run Script (Chạy tập lệnh) mới này là giai đoạn tạo bản dựng cuối cùng của dự án; nếu không, Crashlytics không thể xử lý dSYM đúng cách.

    2. Mở rộng mục Chạy tập lệnh mới.

    3. Trong trường tập lệnh (nằm dưới nhãn Shell), hãy thêm tập lệnh chạy sau đây.

      Tập lệnh này xử lý các tệp dSYM của dự án và tải các tệp đó lên Crashlytics.

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

    4. Trong phần Input Files (Tệp đầu vào), hãy thêm đường dẫn cho vị trí của các tệp sau:

      ${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)
       Nếu bạn có ENABLE_USER_SCRIPT_SANDBOXING=YES và ENABLE_DEBUG_DYLIB=YES trong chế độ cài đặt bản dựng của dự án, hãy thêm nội dung sau: 
      ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${PRODUCT_NAME}.debug.dylib

Để biết thêm thông tin chi tiết về tệp dSYM và Crashlytics (bao gồm cả cách tải tệp dSYM lên theo cách thủ công), hãy truy cập vào bài viết Nhận báo cáo sự cố đã gỡ rối mã nguồn.

Bước 3: Xác định sự cố thử nghiệm để hoàn tất việc thiết lập

Để hoàn tất việc thiết lập Crashlytics và xem dữ liệu ban đầu trên trang tổng quan Crashlytics trong bảng điều khiển của Firebase, bạn cần xác định sự cố thử nghiệm.

  1. Thêm mã vào ứng dụng để buộc xảy ra sự cố thử nghiệm.

    Bạn có thể sử dụng mã sau để thêm một nút vào ứng dụng của mình. Khi được nhấn, nút này sẽ gây ra sự cố. Nút này có nhãn "Test Crash" (Kiểm thử sự cố).

    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. Tạo và chạy ứng dụng trong Xcode khi trình gỡ lỗi Xcode đã ngắt kết nối.

    1. Nhấp vào Build and then run the current scheme (Tạo bản dựng rồi chạy lược đồ hiện tại) để tạo bản dựng ứng dụng trên thiết bị thử nghiệm hoặc trình mô phỏng.

    2. Chờ cho đến khi ứng dụng của bạn chạy, sau đó nhấp vào Stop running the scheme or action (Dừng chạy lược đồ hoặc hành động) để đóng phiên bản ban đầu của ứng dụng. Phiên bản ban đầu này bao gồm trình gỡ lỗi can thiệp vào Crashlytics.

  3. Buộc xảy ra sự cố thử nghiệm để gửi báo cáo sự cố đầu tiên của ứng dụng:

    1. Mở ứng dụng trên màn hình chính của thiết bị kiểm thử hoặc trình mô phỏng.

    2. Trong ứng dụng, hãy nhấn vào nút "Test Crash" (Kiểm thử sự cố) mà bạn đã thêm bằng mã ở trên.

    3. Sau khi ứng dụng gặp sự cố, hãy chạy lại ứng dụng từ Xcode để ứng dụng có thể gửi báo cáo sự cố đến Firebase.

  4. Trong bảng điều khiển Firebase, hãy chuyển đến trang tổng quan DevOps & Engagement (DevOps và mức độ tương tác) > Crashlytics để kiểm tra báo cáo sự cố thử nghiệm.

    Nếu bạn đã làm mới bảng điều khiển và vẫn không thấy sự cố kiểm thử sau 5 phút, hãy bật tính năng ghi nhật ký gỡ lỗi để xem ứng dụng của bạn có đang gửi báo cáo sự cố hay không.


Chỉ vậy thôi! Crashlytics hiện đang theo dõi ứng dụng của bạn để phát hiện sự cố. Truy cập vào trang tổng quan Crashlytics để xem và tìm hiểu tất cả báo cáo và số liệu thống kê của bạn.

Các bước tiếp theo