You can now set up Crashlytics in your app by using the new official Firebase Crashlytics SDK, which offers improved APIs that are more consistent with other Firebase products and more intuitive to use. This guide describes how to upgrade to the new SDK from the legacy Fabric SDK. It describes the changes that come with the new APIs, the reason for the changes, and how to update your code, if required.
Step 1: Add a Firebase configuration file
- Open your Project Settings. In the Your apps card, select the bundle ID of the app for which you need a config file.
Click Download GoogleService-Info.plist to obtain your Firebase iOS config file (
GoogleService-Info.plist
).You can download your Firebase iOS config file again at any time.
Make sure the config filename is not appended with additional characters, like
(2)
.
Move your config file into the root of your Xcode project. If prompted, select to add the config file to all targets.
If you have multiple bundle IDs in your project, you must associate each bundle
ID with a registered app in the Firebase console so that each app can have
its own GoogleService-Info.plist
file.
Step 2: Add the Firebase Crashlytics SDK
In Cocoapods, replace the
Fabric
andCrashlytics
pods with aFirebase/Crashlytics
pod in all targets. Make sure you add Version 4.0.0 or later (this is required for your crash reports to appear in the Firebase console).# Add the pod for Firebase Crashlytics pod 'Firebase/Crashlytics'
# Recommended: Add the Firebase pod for Google Analytics pod 'Firebase/Analytics'Directly uninstall or remove third party dependencies from Fabric, such as dependencies from Fabric Answers and third party kits.
Install and update the pods, then open your .xcworkspace file to see the project in Xcode:
pod install
open your-project.xcworkspace
Step 3: Update your code
In Xcode, rebuild your app, then re-open your .xcworkspace file again.
Review the following SDK changes and make the appropriate updates to your code:
Crashlytics now rotates IDs based on Firebase installation IDs.
Crashlytics uses the Crashlytics Installation UUID to identify instances of your app and to associate your users' data with their devices. Previously, Crashlytics rotated your user's Installation UUID when the advertising ID of their device changed. Now, Crashlytics rotates the Installation UUID based on the user's Firebase installation ID (FID). For more information, visit Manage Firebase installation IDs.
Reason for change
Using FIDs is consistent with other Firebase SDKs.
The run and upload-symbols scripts are now in FirebaseCrashlytics.
You can now access the run
and upload-symbols
scripts from the new
FirebaseCrashlytics
library. Note that you can still call upload-symbols
from anywhere in your build process to manually upload your dSYMs.
In addition, Fabric’s API_KEY and
BUILD_SECRET are no longer included in the new SDK. Instead,
Crashlytics now uses your app’s GoogleService-info.plist
to
associate your app with your Firebase project and retain your historic crash
data.
Fabric SDK
${PODS_ROOT}/Fabric/run API_KEY BUILD_SECRET /path/to/pods/directory/Fabric/upload-symbols
Firebase Crashlytics SDK
${PODS_ROOT}/FirebaseCrashlytics/run /path/to/pods/directory/FirebaseCrashlytics/upload-symbols
Reason for change
Crashlytics no longer uses the Fabric SDK as a dependency so we're moving our CLI tools to a new library.
The Crashlytics library is now called FirebaseCrashlytics.
In your app, update your import paths:
Fabric SDK
Swift
import Crashlytics
Objective-C
@import Crashlytics
Firebase Crashlytics SDK
Swift
import FirebaseCrashlytics
Objective-C
@import FirebaseCrashlytics
Reason for change
Updating the name of the Crashlytics
library makes it consistent
with other Firebase libraries (e.g., FirebaseFirestore
and
FirebaseAuth
).
FirebaseCrashlytics no longer works with the Fabric SDK.
Now, FirebaseCrashlytics
can only be initialized with the
Firebase Crashlytics SDK. You can start up an instance of
FirebaseCrashlytics
by calling
FirebaseApp.configure
in Swift or [FIRApp configure]
in Objective-C.
Within your application:didFinishLaunchingWithOptions
, replace calls to
Fabric.with
and startWithAPIKey
with a call to FirebaseApp
:
Fabric SDK
Swift
Fabric.with([Crashlytics.self])
Objective-C
[Fabric with:@[[Crashlytics class]]];
+ startWithAPIKey:
+ startWithAPIKey:delegate:
Firebase Crashlytics SDK
Swift
FirebaseApp.configure()
Objective-C
[FIRApp configure];
Reason for change
Using the new methods to initialize Crashlytics is more consistent with how other Firebase services are initialized.
The crash and throwException methods are removed.
The new SDK no longer includes the crash
or
throwException
methods. Instead, use fatalError
in Swift or an empty array
in Objective-C to force a crash.
Firebase Crashlytics SDK
Swift
// Force a test crash
fatalError()
Objective-C
// Force a test crash
@[][1];
Reason for change
Different kinds of crashes can occur for a variety of reasons, and these methods did not clearly specify whether the resulting crashes occurred during runtime or in your app's native SDK.
The sharedInstance method is now named crashlytics.
The new SDK no longer includes the sharedInstance
method.
To initialize Crashlytics, use crashlytics
instead
(read the reference documentation for
Swift
or Objective-C
for more information). In your app’s delegate, update your initialization
script:
Fabric SDK
Swift
Crashlytics.sharedInstance()
Objective-C
[Crashlytics sharedInstance];
Firebase Crashlytics SDK
Swift
Crashlytics.crashlytics()
Objective-C
[FIRCrashlytics crashlytics];
Reason for change
We named renamed the instance getter method to be consistent with other Firebase SDKs.
setUserIdentifier is now setUserID. setUserName and setUserEmail are removed.
Previously, you could set a name or email associated with a
crash using setUserName
and setUserEmail
,
but these methods will no longer be defined.
The new preferred method to
set IDs for your users
is to use setUserID
.
Fabric SDK
Swift
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"];
Firebase Crashlytics SDK
Swift
Crashlytics.crashlytics().setUserID("user_id")
Objective-C
[[FIRCrashlytics crashlytics] setUserID:@"user_id"];
Reason for change
We adopted the method name setUserID
to be consistent with other Firebase APIs
and removed setUserName
and setUserEmail
to discourage logging
PII through Crashlytics.
CLSLogv and CLSNSLogv are replaced by logging functions.
The new SDK no longer includes the CLSLogv
or
CLSNSLogv
functions. To add custom log messages,
use the new logging methods in the Crashlytics
library.
Note that the new methods no longer print to stdout
or
NSLog
(we recommend writing a wrapper if you want to
keep this behavior).
Fabric SDK
Swift
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);
Firebase Crashlytics SDK
Swift
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];
If you used CLS_LOG
, add the following to a header file to continue getting
file names and line numbers in log statements:
#define CLS_LOG(__FORMAT__, ...) [[FIRCrashlytics crashlytics] logWithFormat:@"%s line %d $ " __FORMAT__, __PRETTY_FUNCTION__, __LINE__, ##__VA_ARGS__]
Reason for change
The new methods require instances, which makes it easier to test code.
setCustomValue is replacing setObjectValue, setIntValue, setFloatValue, and setBoolValue.
The custom setter methods are no longer included in the new SDK.
Previously, you could use the methods to
set key/value pairs
to send along with your crash report. Now, you can use setCustomValue:forKey
to set key/value pairs for all data types.
Fabric SDK
Swift
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"];
Firebase Crashlytics SDK
Swift
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"];
Reason for change
The new method name is unique to Crashlytics and makes it clear that Crashlytics is not key-value compliant.
recordCustomExceptionName:reason:frameArray: is replaced by the Exception Model API.
If your app runs in a non-native environment (e.g., JavaScript or Unity), you can use the Exception Model API to report crash metadata in your app's native exception format.
Fabric SDK
Swift
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]];
Firebase Crashlytics SDK
Swift
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],
];
Reason for change
This feature has been long requested and allows you to extend Crashlytics onto other platforms like Unity, Flutter, or React Native.
The CrashlyticsDelegate is replaced by separate methods for handling crash reports.
You can now use a new set of methods for handling crash reports:
didFinishLaunchingWithOptions
is now replaced by the new handlercheckForUnsentReportsWithCompletion
.crashlyticsDidDetectReportForLastExecution
is now replaced bydidCrashDuringPreviousExecution
.didCrashDuringPreviousExecution
allows you to conveniently detect crashes that occur during the last run of your app.crashlyticsCanUseBackgroundSessions
is now permanently set to true.We no longer support inspecting the
CLSReport
object in the delegate.
By default, Crashlytics
automatically uploads crash reports at startup, and you could previously call
didFinishLaunchingWithOptions
to let your users
opt-in to crash reporting.
Now, when you call setCrashlyticsCollectionEnabled=false
to turn off automatic crash reporting, Crashlytics calls
checkForUnsentReportsWithCompletion
, which lets your users choose whether or not
to send crash reports when your app crashes. You can then call
sendUnsentReports
if the user opts in or deleteUnsentReports
if the user opts out.
Note that you can also call sendUnsentReports
and
deleteUnsentReports
outside of
checkForUnsentReportsWithCompletion
. For example, you may
want to permanently set up or disable crash reporting if your users have
given you blanket approval or disapproval to send crash reports. Keep in
mind that you may never receive crash reports if your app crashes early
on in its lifecycle.
Fabric SDK
Swift
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
Firebase Crashlytics SDK
Swift
/* 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.
}
Reason for change
The new set of methods give you more control over your app's crash reporting behavior. Also, you no longer need to set up the CrashlyticsDelegate before initializing Crashlytics.
firebase_crashlytics_collection_enabled is replaced by FirebaseCrashlyticsCollectionEnabled.
When you set FirebaseCrashlyticsCollectionEnabled
to false in your
Info.plist
, Crashlytics stops automatically sending crash reports at
startup. After your app's first run, you can also disable crash reporting by
setting setCrashlyticsCollectionEnabled
to false
in your Crashlytics.h
,
but note that setCrashlyticsCollectionEnabled
overrides this flag.
Turn off automatic collection by replacing the
firebase_crashlytics_collection_enabled
key in your Info.plist
:
Key:
FirebaseCrashlyticsCollectionEnabled
Value:
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.
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
Test your Crashlytics setup by forcing a crash in the Firebase console.
Customize your crash report setup by adding opt-in reporting, logs, keys, and tracking of non-fatal errors.
Add Google Analytics to your app. Combine the power of Google Analytics with Firebase Crashlytics to see crash-free user statistics in the Firebase console.