This guide contains instructions for upgrading to the latest version of the Firebase Crashlytics SDK from the legacy Fabric SDK.
Trang này được dịch bởi Cloud Translation API.
Switch to English

Nâng cấp lên SDK Firebase Crashlytics

Giờ đây, bạn có thể thiết lập Crashlytics trong ứng dụng của mình bằng cách sử dụng SDK Firebase Crashlytics chính thức mới, cung cấp các API cải tiến phù hợp hơn với các sản phẩm Firebase khác và sử dụng trực quan hơn. Hướng dẫn này mô tả cách nâng cấp lên SDK mới từ SDK Fabric Crashlytics. Nó mô tả những thay đổi đi kèm với các API mới, lý do thay đổi và cách cập nhật mã của bạn, nếu được yêu cầu.

Nếu gần đây bạn đã di chuyển ứng dụng của mình từ Fabric, hãy xem lại việc nâng cấp lên Firebase Crashlytics SDK ảnh hưởng như thế nào đến dữ liệu phân tích sự cố của bạn.

Bước 1 : Thêm tệp cấu hình Firebase

  1. Mở Cài đặt dự án của bạn . Trong thẻ Ứng dụng của bạn , chọn ID gói của ứng dụng mà bạn cần tệp cấu hình.
  2. Nhấp vào Tải xuống GoogleService-Info.plist để tải tệp cấu hình Firebase iOS của bạn ( GoogleService-Info.plist ).

    • Bạn có thể tải xuống lại tệp cấu hình Firebase iOS của mình bất kỳ lúc nào.

    • Đảm bảo rằng tên tệp cấu hình không được nối với các ký tự bổ sung, như (2) .

  3. Di chuyển tệp cấu hình của bạn vào thư mục gốc của dự án Xcode của bạn. Nếu được nhắc, hãy chọn thêm tệp cấu hình vào tất cả các mục tiêu.

Nếu bạn có nhiều ID gói trong dự án của mình, bạn phải liên kết từng ID gói với một ứng dụng đã đăng ký trong bảng điều khiển Firebase để mỗi ứng dụng có thể có tệp GoogleService-Info.plist của riêng mình.

Bước 2 : Thêm SDK Firebase Crashlytics

  1. Trong Cocoapods, thay thế các nhóm FabricCrashlytics bằng một nhóm Firebase/Crashlytics ở tất cả các mục tiêu. Đảm bảo bạn thêm Phiên bản 4.0.0 trở lên (điều này là bắt buộc để báo cáo sự cố của bạn xuất hiện trong bảng điều khiển Firebase).

    # Add the pod for Firebase Crashlytics
    pod 'Firebase/Crashlytics'
    # Recommended: Add the Firebase pod for Google Analytics pod 'Firebase/Analytics'
  2. Trực tiếp gỡ cài đặt hoặc xóa các phần phụ thuộc của bên thứ ba khỏi Fabric, chẳng hạn như các phần phụ thuộc từ Fabric Answers và các bộ công cụ của bên thứ ba.

  3. Cài đặt và cập nhật các nhóm, sau đó mở tệp .xcworkspace của bạn để xem dự án trong Xcode:

    pod install
    open your-project.xcworkspace

Bước 3 : Cập nhật mã của bạn

  1. Trong Xcode, hãy xây dựng lại ứng dụng của bạn, sau đó mở lại tệp .xcworkspace.

  2. Xem lại các thay đổi SDK sau đây và thực hiện các cập nhật thích hợp cho mã của bạn:


Crashlytics hiện xoay các ID dựa trên ID cài đặt Firebase.

Crashlytics sử dụng UUID cài đặt Crashlytics để xác định các phiên bản ứng dụng của bạn và liên kết dữ liệu của người dùng với thiết bị của họ. Trước đây, Crashlytics đã xoay vòng UUID cài đặt của người dùng khi ID quảng cáo trên thiết bị của họ thay đổi. Bây giờ, Crashlytics xoay UUID cài đặt dựa trên ID cài đặt Firebase (FID) của người dùng. Để biết thêm thông tin, hãy truy cập Quản lý ID cài đặt Firebase .

Lý do cho sự thay đổi

Sử dụng FID nhất quán với các SDK Firebase khác.


Các tập lệnh chạy và ký hiệu tải lên hiện có trong FirebaseCrashlytics.

Giờ đây, bạn có thể truy cập các tập lệnh runupload-symbols từ thư viện FirebaseCrashlytics mới. Lưu ý rằng bạn vẫn có thể gọi upload-symbols từ bất kỳ đâu trong quy trình xây dựng của mình để tải lên các dSYM của bạn theo cách thủ công.

Ngoài ra, API_KEYBUILD_SECRET không còn được đưa vào SDK mới. Thay vào đó, Crashlytics hiện sử dụng GoogleService-info.plist của ứng dụng để liên kết ứng dụng của bạn với dự án Firebase và giữ lại dữ liệu sự cố lịch sử của bạn.

SDK vải

${PODS_ROOT}/Fabric/run API_KEY BUILD_SECRET
/path/to/pods/directory/Fabric/upload-symbols

SDK Firebase Crashlytics

${PODS_ROOT}/FirebaseCrashlytics/run
/path/to/pods/directory/FirebaseCrashlytics/upload-symbols

Lý do cho sự thay đổi

Crashlytics không còn sử dụng Fabric SDK làm phụ thuộc nữa nên chúng tôi đang chuyển các công cụ CLI của mình sang một thư viện mới.


Thư viện Crashlytics hiện được gọi là FirebaseCrashlytics.

Trong ứng dụng của bạn, hãy cập nhật các đường dẫn nhập của bạn:

SDK vải

Nhanh

import Crashlytics

Objective-C

@import Crashlytics

SDK Firebase Crashlytics

Nhanh

import FirebaseCrashlytics

Objective-C

@import FirebaseCrashlytics

Lý do cho sự thay đổi

Cập nhật tên của thư viện Crashlytics giúp nó nhất quán với các thư viện Firebase khác (ví dụ: FirebaseFirestoreFirebaseAuth ).


FirebaseCrashlytics không còn hoạt động với SDK vải.

Giờ đây, FirebaseCrashlytics chỉ có thể được khởi chạy bằng SDK Firebase Crashlytics. Bạn có thể khởi động một phiên bản của FirebaseCrashlytics bằng cách gọi FirebaseApp.configure trong Swift hoặc [FIRApp configure] trong Objective-C.

Trong application:didFinishLaunchingWithOptions của bạn application:didFinishLaunchingWithOptions , thay thế các lệnh gọi tới Fabric.withstartWithAPIKey bằng một lệnh gọi tới FirebaseApp :

SDK vải

Nhanh

Fabric.with([Crashlytics.self])

Objective-C

[Fabric with:@[[Crashlytics class]]];
+ startWithAPIKey:
+ startWithAPIKey:delegate:

SDK Firebase Crashlytics

Nhanh

FirebaseApp.configure()

Objective-C

[FIRApp configure];

Lý do cho sự thay đổi

Việc sử dụng các phương pháp mới để khởi chạy Crashlytics phù hợp hơn với cách khởi tạo các dịch vụ Firebase khác.


Các phương thức crash và throwException bị loại bỏ.

SDK mới không còn bao gồm các phương thức crash hoặc throwException . Thay vào đó, hãy sử dụng fatalError trong Swift hoặc một mảng trống trong Objective-C để tạo ra sự cố.

SDK Firebase Crashlytics

Nhanh

// Force a test crash
fatalError()

Objective-C

// Force a test crash
@[][1];

Lý do cho sự thay đổi

Các loại sự cố khác nhau có thể xảy ra vì nhiều lý do và các phương pháp này không chỉ rõ liệu các sự cố dẫn đến xảy ra trong thời gian chạy hay trong SDK gốc của ứng dụng của bạn.


Phương thức sharedInstance hiện được đặt tên là crashlytics.

SDK mới không còn bao gồm phương thức sharedInstance . Để khởi tạo Crashlytics, hãy sử dụng crashlytics thay thế (đọc tài liệu tham khảo về Swift hoặc Objective-C để biết thêm thông tin). Trong ủy quyền của ứng dụng, hãy cập nhật tập lệnh khởi tạo của bạn:

SDK vải

Nhanh

Crashlytics.sharedInstance()

Objective-C

[Crashlytics sharedInstance];

SDK Firebase Crashlytics

Nhanh

Crashlytics.crashlytics()

Objective-C

[FIRCrashlytics crashlytics];

Lý do cho sự thay đổi

Chúng tôi đã đổi tên phương thức getter phiên bản để phù hợp với các SDK Firebase khác.


setUserIdentifier hiện là setUserID. setUserName và setUserEmail bị xóa.

Trước đây, bạn có thể đặt tên hoặc email liên quan đến sự cố bằng setUserNamesetUserEmail , nhưng các phương pháp này sẽ không còn được xác định nữa. Phương pháp ưu tiên mới để đặt ID cho người dùng của bạn là sử dụng setUserID .

SDK vải

Nhanh

Crashlytics.sharedInstance().setUserIdentifier("user_id")

Crashlytics.sharedInstance().setUserEmail("user_email")

Crashlytics.sharedInstance().setUserName("user_name")

Objective-C

[[Crashlytics sharedInstance] setUserIdentifier:@"user_id"];

[[Crashlytics sharedInstance] setUserEmail:@"user_email"];

[[Crashlytics sharedInstance] setUserName:@"user_name"];

SDK Firebase Crashlytics

Nhanh

Crashlytics.crashlytics().setUserID("user_id")

Objective-C

[[FIRCrashlytics crashlytics] setUserID:@"user_id"];

Lý do cho sự thay đổi

Chúng tôi đã sử dụng tên phương thức setUserID để nhất quán với các API Firebase khác và loại bỏ setUserNamesetUserEmail để không khuyến khích ghi PII thông qua Crashlytics.


CLSLogv và CLSNSLogv được thay thế bằng các chức năng ghi nhật ký.

SDK mới không còn chứa CLSLogv hoặc CLSNSLogv chức năng. Để thêm thông báo nhật ký tùy chỉnh , hãy sử dụng các phương pháp ghi nhật ký mới trong thư viện Crashlytics . Lưu ý rằng các phương thức mới không còn in ra stdout hoặc NSLog (chúng tôi khuyên bạn nên viết một trình bao bọc nếu bạn muốn giữ nguyên hành vi này).

SDK vải

Nhanh

CLSLogv("%@, %@", getVaList([first_arg, second_arg]))

CLSNSLogv("%@, %@", getVaList([first_arg, second_arg]))

Objective-C

CLSLog(@"%@, %@", first_arg, second_arg);
CLSNSLog(@"%@, %@", first_arg, second_arg);

CLSLogv(@"%@, %@", args_va_list);
CLSNSLogv(@"%@, %@", args_va_list);

CLS_LOG(@"%@, %@", first_arg, second_arg);

SDK Firebase Crashlytics

Nhanh

Crashlytics.crashlytics().log("\(first_arg), \(second_arg)")

Crashlytics.crashlytics().log(format: "%@, %@", arguments: getVaList([first_arg, second_arg]))

Objective-C

[[FIRCrashlytics crashlytics] log:@"first_arg, second_arg"];

[[FIRCrashlytics crashlytics] logWithFormat:@"%@, %@", first_arg, second_arg];

Nếu bạn đã sử dụng CLS_LOG , hãy thêm phần sau vào tệp tiêu đề để tiếp tục nhận tên tệp và số dòng trong câu lệnh nhật ký:

#define CLS_LOG(__FORMAT__, ...) [[FIRCrashlytics crashlytics] logWithFormat:@"%s line %d $ " __FORMAT__, __PRETTY_FUNCTION__, __LINE__, ##__VA_ARGS__]

Lý do cho sự thay đổi

Các phương pháp mới yêu cầu các phiên bản, điều này giúp việc kiểm tra mã dễ dàng hơn.


setCustomValue sẽ thay thế setObjectValue, setIntValue, setFloatValue và setBoolValue.

Các phương thức setter tùy chỉnh không còn được đưa vào SDK mới. Trước đây, bạn có thể sử dụng các phương pháp để đặt các cặp khóa / giá trị để gửi cùng với báo cáo sự cố của mình. Bây giờ, bạn có thể sử dụng setCustomValue:forKey để đặt các cặp khóa / giá trị cho tất cả các kiểu dữ liệu.

SDK vải

Nhanh

Crashlytics.sharedInstance().setObjectValue("value", forKey: "object_key")

Crashlytics.sharedInstance().setIntValue(100, forKey: "int_key")

Crashlytics.sharedInstance().setFloatValue(99.9, forKey: "float_key")

Crashlytics.sharedInstance().setBoolValue(true, forKey: "bool_key")

Objective-C

[[Crashlytics sharedInstance] setObjectValue:@"key" forKey:@"object_key"];

[[Crashlytics sharedInstance] setIntValue:100 forKey:@"int_key"];

[[Crashlytics sharedInstance] setFloatValue:99.9 forKey:@"float_key"];

[[Crashlytics sharedInstance] setBoolValue:YES forKey:@"bool_key"];

SDK Firebase Crashlytics

Nhanh

Crashlytics.crashlytics().setCustomValue("value", forKey: "object_key")

Crashlytics.crashlytics().setCustomValue(100, forKey: "int_key")

Crashlytics.crashlytics().setCustomValue(99.9, forKey: "float_key")

Crashlytics.crashlytics().setCustomValue(true, forKey: "bool_key")

Objective-C

[[FIRCrashlytics crashlytics] setCustomValue:@"value" forKey:@"object_key"];

[[FIRCrashlytics crashlytics] setCustomValue:@(100) forKey:@"int_key"];

[[FIRCrashlytics crashlytics] setCustomValue:@(99.9) forKey:@"float_key"];

[[FIRCrashlytics crashlytics] setCustomValue:@YES forKey:@"bool_key"];

Lý do cho sự thay đổi

Tên phương thức mới là duy nhất cho Crashlytics và nói rõ rằng Crashlytics không tuân thủ khóa-giá trị.


recordCustomExceptionName: reason: frameArray: được thay thế bằng API mô hình ngoại lệ.

Nếu ứng dụng của bạn chạy trong môi trường không phải gốc (ví dụ: JavaScript hoặc Unity), bạn có thể sử dụng API mô hình ngoại lệ để báo cáo siêu dữ liệu sự cố ở định dạng ngoại lệ gốc của ứng dụng.

SDK vải

Nhanh

let topFrame = CLSStackFrame () topFrame.symbol = "doSomethingBad" topFrame.fileName = "bad.cc" topFrame.lineNumber = 23

let middleFrame = CLSStackFrame()
middleFrame.symbol = "doOtherStuff"
middleFrame.fileName = "stuff.cc"
middleFrame.lineNumber = 23;

let bottomFrame = CLSStackFrame()
bottomFrame.symbol = "main"
bottomFrame.fileName = "main.cc"
bottomFrame.lineNumber = 123

Crashlytics.sharedInstance().recordCustomExceptionName("FooException",
                                                       reason: "There was a foo.",
                                                       frameArray: [topFrame, middleFrame, bottomFrame])

Objective-C

CLSStackFrame *topFrame = [[CLSStackFrame alloc] init];
topFrame.symbol = @"doSomethingBad";
topFrame.fileName = @"bad.cc";
topFrame.lineNumber = 23;

CLSStackFrame *middleFrame = [[CLSStackFrame alloc] init];
middleFrame.symbol = @"doOtherStuff";
middleFrame.fileName = @"stuff.cc";
middleFrame.lineNumber = 23;

CLSStackFrame *bottomFrame = [[CLSStackFrame alloc] init];
bottomFrame.symbol = @"main";
bottomFrame.fileName = @"main.cc";
bottomFrame.lineNumber = 123;

[[Crashlytics sharedInstance] recordCustomExceptionName:@"FooException"
                                                 reason:@"There was a foo."
                                             frameArray:@[topFrame, middleFrame, bottomFrame]];

SDK Firebase Crashlytics

Nhanh

var  ex = ExceptionModel.init(name:"FooException", reason:"There was a foo.")
ex.stackTrace = [
  StackFrame.init(symbol:"makeError" fileName:"handler.js" lineNumber:495),
  StackFrame.init(symbol:"then" fileName:"routes.js" lineNumber:102),
  StackFrame.init(symbol:"main" fileName:"app.js" lineNumber:12),
]

crashlytics.record(exceptionModel:ex)

Objective-C

model.stackTrace = @[
  [FIRStackFrame stackFrameWithSymbol:@"makeError" fileName:@"handler.js" lineNumber:495],
  [FIRStackFrame stackFrameWithSymbol:@"then" fileName:@"routes.js" lineNumber:102],
  [FIRStackFrame stackFrameWithSymbol:@"main" fileName:@"app.js" lineNumber:12],
];

Lý do cho sự thay đổi

Tính năng này đã được yêu cầu từ lâu và cho phép bạn mở rộng Crashlytics trên các nền tảng khác như Unity, Flutter hoặc React Native.



CrashlyticsDelegate được thay thế bằng các phương pháp riêng biệt để xử lý các báo cáo sự cố.

Giờ đây, bạn có thể sử dụng một nhóm phương pháp mới để xử lý báo cáo sự cố:

  • didFinishLaunchingWithOptions hiện được thay thế bằng trình xử lý checkForUnsentReportsWithCompletion .

  • crashlyticsDidDetectReportForLastExecution hiện được thay thế bằng didCrashDuringPreviousExecution . didCrashDuringPreviousExecution cho phép bạn phát hiện các lỗi xảy ra trong lần chạy cuối cùng của ứng dụng một cách thuận tiện.

  • crashlyticsCanUseBackgroundSessions hiện được đặt vĩnh viễn thành true.

  • Chúng tôi không còn hỗ trợ kiểm tra đối tượng CLSReport trong đại biểu.

Theo mặc định, Crashlytics tự động tải lên báo cáo sự cố khi khởi động và trước đây bạn có thể gọi didFinishLaunchingWithOptions để cho phép người dùng của bạn chọn tham gia báo cáo sự cố. Bây giờ, khi bạn gọi setCrashlyticsCollectionEnabled=false để tắt báo cáo sự cố tự động, Crashlytics sẽ gọi checkForUnsentReportsWithCompletion , cho phép người dùng của bạn chọn có gửi báo cáo sự cố khi ứng dụng của bạn gặp sự cố hay không. Sau đó, bạn có thể gọi sendUnsentReports nếu người dùng chọn tham gia hoặc deleteUnsentReports nếu người dùng chọn không tham gia.

Lưu ý rằng bạn cũng có thể gọi sendUnsentReportsdeleteUnsentReports bên ngoài checkForUnsentReportsWithCompletion . Ví dụ: bạn có thể muốn thiết lập vĩnh viễn hoặc vô hiệu hóa báo cáo sự cố nếu người dùng của bạn đã cho phép bạn chấp thuận hoặc không chấp thuận gửi báo cáo sự cố. Hãy nhớ rằng bạn có thể không bao giờ nhận được báo cáo sự cố nếu ứng dụng của bạn gặp sự cố sớm trong vòng đời của nó.

SDK vải

Nhanh

class YourClassName: CrashlyticsDelegate {

  func application(_ application: UIApplication, didFinishLaunchingWithOptions

    ...
    Crashlytics.sharedInstance().delegate = self
    ...

    return true
  }

  func crashlyticsDidDetectReport(forLastExecution report: CLSReport, completionHandler: @escaping (Bool) -> Void) {
    /* ... handle unsent reports */
  }

  func crashlyticsCanUseBackgroundSessions(_ crashlytics: Crashlytics) -> Bool {
    return true
  }
}

Objective-C

@interface YourClassName <CrashlyticsDelegate> ()
@end

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

  ...
  [[Crashlytics sharedInstance] setDelegate:self];
  ...

  return YES;
}

-(void)crashlyticsDidDetectReportForLastExecution:(CLSReport *)report completionHandler:(void (^)(BOOL submit))completionHandler {
  // ... handle unsent reports
}

-(BOOL)crashlyticsCanUseBackgroundSessions:(Crashlytics *)crashlytics {
  return YES;
}

@end

SDK Firebase Crashlytics

Nhanh

/* You must set setCrashlyticsCollectionEnabled to false in order to use
checkForUnsentReportsWithCompletion. */

Crashlytics.crashlytics().setCrashlyticsCollectionEnabled(false)

Crashlytics.crashlytics().checkForUnsentReports { hasUnsentReport in
  let hasUserConsent = false
  // ...get user consent.

  if hasUserConsent && hasUnsentReport {
    Crashlytics.crashlytics().sendUnsentReports()
  } else {
    Crashlytics.crashlytics().deleteUnsentReports()
  }
}

// Detect when a crash happens during your app's last run.
if Crashlytics.crashlytics().didCrashDuringPreviousExecution() {
  // ...notify the user.
}

Objective-C

/* You must set setCrashlyticsCollectionEnabled to false in order to use
checkForUnsentReportsWithCompletion. */

[[FIRCrashlytics crashlytics] setCrashlyticsCollectionEnabled:false];

[[FIRCrashlytics crashlytics] checkForUnsentReportsWithCompletion:^(BOOL hasUnsentReports) {
  BOOL hasConsent = false;
  // ...get consent from user.

  if (hasConsent && hasUnsentReports) {
    [[FIRCrashlytics crashlytics] sendUnsentReports];
  } else {
    [[FIRCrashlytics crashlytics] deleteUnsentReports];
  }
}];

// Detect when a crash happens during your app's last run.
if ([[FIRCrashlytics crashlytics] didCrashDuringPreviousExecution]) {
  // ...notify the user.
}

Lý do cho sự thay đổi

Bộ phương pháp mới giúp bạn kiểm soát nhiều hơn hành vi báo cáo sự cố của ứng dụng. Ngoài ra, bạn không cần thiết lập CrashlyticsDelegate trước khi khởi chạy Crashlytics nữa.


firebase_crashlytics_collection_enabled được thay thế bằng FirebaseCrashlyticsCollectionEnabled.

Khi bạn đặt FirebaseCrashlyticsCollectionEnabled thành false trong Info.plist của mình, Crashlytics sẽ ngừng tự động gửi báo cáo sự cố khi khởi động. Sau lần chạy đầu tiên của ứng dụng, bạn cũng có thể tắt báo cáo sự cố bằng cách đặt setCrashlyticsCollectionEnabled thành false trong Crashlytics.h , nhưng lưu ý rằng setCrashlyticsCollectionEnabled ghi đè cờ này.

Tắt tính năng thu thập tự động bằng cách thay thế khóa firebase_crashlytics_collection_enabled trong Info.plist của bạn:

  • Chìa khóa: FirebaseCrashlyticsCollectionEnabled

  • Giá trị: false

After the first run of your app, you can also turn off automatic collection by adding the following to your Crashlytics.h :

Firebase Crashlytics SDK

Swift

// setCrashlyticsCollectionEnabled is set to true by default.
Crashlytics.crashlytics().setCrashlyticsCollectionEnabled(false)

Objective-C

// setCrashlyticsCollectionEnabled is set to true by default.
[[FIRCrashlytics crashlytics] setCrashlyticsCollectionEnabled:false];

Reason for change

Now you have more control over how Crashlytics handles unsent crash reports when you disable automatic crash reporting. After you set FirebaseCrashlyticsCollectionEnabled to false, you can call checkForUnsentReportsWithCompletion from anywhere in your app and either send or delete unsent reports, depending on what your user chooses.


Now, Crashlytics always uses background sessions.

Previously, you could turn off background sessions if you didn't want to support it in your app by setting crashlyticsCanUseBackgroundSessions to false. Now, crashlyticsCanUseBackgroundSessions is always set to true.

Reason for change

We no longer support iOS versions below 7.0 or macOS versions below OS X 10.9, which do not support background sessions.


Crashlytics can only use data collected by Google Analytics.

You can no longer collect data with Fabric Answers after upgrading to the Firebase Crashlytics SDK. To get metrics for crash-free users and breadcrumbs, switch over to using Google Analytics instead. Note that your historical Answers data cannot migrate to Firebase.

Visit Start using Google Analytics to learn how to add Google Analytics to your app. If you previously used Fabric Answers, find out how to convert your Answers events to Analytics events .

Reason for change

We now offer Google Analytics to help you get more insight into your crash data. With Analytics, you can continue gathering stats for your app in the Firebase console.

Next steps