This quickstart describes how to migrate your existing Fabric Crashlytics Unity app to Firebase Crashlytics so that you can see all of your crash reports in the Firebase console.
Before you begin
The following guide assumes that you have a working Unity app with Fabric. If you do not have an existing Unity app in Fabric, follow the Get Started instructions for users new to Crashlytics.
Step 1: Link your Fabric app(s)
Sign into Fabric, then navigate to the migration flow.
Check that the Signed into Google as field lists the Google account associated with your Firebase project. If it doesn't, click Switch accounts to select the correct account.
Click Get Started, then click Start Linking.
Drag the appropriate Fabric App on the left into the appropriate Firebase project on the right.
Note that you can also create a new Firebase project.
Click Link 1 app to Firebase.
Step 2: Remove Fabric
Fabric adds GameObject
s to your Scene to initialize Crashlytics in your
game as well as additional directories for the SDKs themselves.
To ensure there are no conflicts between the Fabric Crashlytics and Firebase Crashlytics plugins, remove the following Fabric folders and files from your Unity project:
Under Assets, delete the following files:
Assets/ Editor Default Resources/ FabricSettings.asset <- DELETE Fabric/ <- DELETE Plugins/ Android/ answers/ <- DELETE beta/ <- DELETE crashlytics/ <- DELETE crashlytics-wrapper/ <- DELETE fabric/ <- DELETE fabric-init/ <- DELETE iOS/ Fabric/ <- DELETE
In the Hierarchy Window, remove the following GameObjects
SampleScene Main Camera Directional Light Canvas EventSystem FabricInit <- DELETE CrashlyticsInit <- DELETE
Remove all Fabric entries in Assets > Plugins > Android > AndroidManifest.xml.
For example, a known key to remove is:
android:name="io.fabric.unity.android.FabricApplication"
Search and remove other Fabric entries if they exist.
Step 3: Add Firebase config files
Navigate to the Firebase console.
In the top left-hand corner next to Project Overview, click
, then select Project SettingsFor your newly linked apps, download your platform-specific Firebase configuration file(s) for each app that you linked. For a single Unity project, you can have at most two config files.
- For iOS —
GoogleService-Info.plist
- For Android —
google-services.json
- For iOS —
In your Unity project, open the Project window, then move your config file(s) into the
Assets
folder.
Step 4: Add the Firebase Crashlytics SDK
Download the Firebase Unity SDK, then unzip the SDK somewhere convenient.
The Firebase Unity SDK is not platform-specific.
In your open Unity project, navigate to Assets > Import Package > Custom Package.
From the unzipped SDK, select to import the Crashlytics SDK (
FirebaseCrashlytics.unitypackage
). Make sure you haveFirebaseCrashlytics.unitypackage
version 6.15.0 or later (if not, update the Asset package version). This is required for your crash reports to appear in the Firebase console.Unity 5.x and earlier: Use the .NET 3.x framework, so import
dotnet3/FirebaseCrashlytics.unitypackage
.Unity 2017.x and later: Allow the use of the .NET 4.x framework. If your Unity project uses .NET 4.x, import
dotnet4/FirebaseCrashlytics.unitypackage
.
Note that you can import any other supported Firebase product as well.
In the Import Unity Package window, click Import.
Create a new C# script, then add it to a
GameObject
in the scene.Open your first scene, then create an empty
GameObject
namedCrashlyticsInitializer
.Click Add Component in the Inspector for the new object.
Select your
CrashlyticsInit
script to add it to theCrashlyticsInitializer
object.
Initialize Crashlytics in the script's
Start
method:using System.Collections; using System.Collections.Generic; using UnityEngine; // Import Firebase using Firebase; public class CrashlyticsInit : MonoBehaviour { // Use this for initialization void Start () { // Initialize Firebase Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWith(task => { var dependencyStatus = task.Result; if (dependencyStatus == Firebase.DependencyStatus.Available) { // Create and hold a reference to your FirebaseApp, // where app is a Firebase.FirebaseApp property of your application class. // Crashlytics will use the DefaultInstance, as well; // this ensures that Crashlytics is initialized. Firebase.FirebaseApp app = Firebase.FirebaseApp.DefaultInstance; // Set a flag here for indicating that your project is ready to use Firebase. } else { UnityEngine.Debug.LogError(System.String.Format( "Could not resolve all Firebase dependencies: {0}",dependencyStatus)); // Firebase Unity SDK is not safe to use here. } }); } // Update is called once per frame void Update() // ... }
With the SDK added and initialized, Crashlytics automatically gets to work listening for and collecting crash reports.
Step 5: Initialize Firebase Crashlytics
Create a new C# script, then add it to a
GameObject
in the scene.Open your first scene, then create an empty
GameObject
namedCrashlyticsInitializer
.Click Add Component in the Inspector for the new object.
Select your
CrashlyticsInit
script to add it to theCrashlyticsInitializer
object.
Initialize Crashlytics in the script's
Start
method:using System.Collections; using System.Collections.Generic; using UnityEngine; // Import Firebase using Firebase; public class CrashlyticsInit : MonoBehaviour { // Use this for initialization void Start () { // Initialize Firebase Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWith(task => { var dependencyStatus = task.Result; if (dependencyStatus == Firebase.DependencyStatus.Available) { // Create and hold a reference to your FirebaseApp, // where app is a Firebase.FirebaseApp property of your application class. // Crashlytics will use the DefaultInstance, as well; // this ensures that Crashlytics is initialized. Firebase.FirebaseApp app = Firebase.FirebaseApp.DefaultInstance; // Set a flag here for indicating that your project is ready to use Firebase. } else { UnityEngine.Debug.LogError(System.String.Format( "Could not resolve all Firebase dependencies: {0}",dependencyStatus)); // Firebase Unity SDK is not safe to use here. } }); } // Update is called once per frame void Update() // ... }
With the SDK added and initialized, Crashlytics automatically gets to work listening for and collecting crash reports.
Step 6: Replace Fabric API calls
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.
Fabric.Crashlytics is now Firebase.Crashlytics
We've changed our namespace from Fabric
to Firebase
.
Fabric
using Fabric.Crashlytics;
Firebase
using Firebase.Crashlytics;
RecordCustomException is now LogException
Log custom non-fatal exceptions that were caught and handled.
Fabric
Crashlytics.RecordCustomException(string name, string reason, StackTrace stackTrace); Crashlytics.RecordCustomException(string name, string reason, string stackTraceString);
Firebase
Crashlytics.LogException(Exception ex);
Reason for change
This function is most often used to log an instance of an Exception
.
Rather than requiring you to extract the "name", "reason", and "stackTrace"
manually (which results in superfluous code), you can now provide the instance
of the Exception
and Firebase Crashlytics will extract the information
that it needs.
Workaround
If you were leveraging these parameters in a way other than just pulling the
information directly off of an exception, you can still accomplish the previous
behavior by creating your own Exception
subclass with the custom metadata in
its description.
SetKeyValue is now SetCustomKey
Set any key/value pair to send along with your crash report. Re-setting the same key will update the value.
Fabric
Crashlytics.SetKeyValue(string key, string value);
Firebase
Crashlytics.SetCustomKey(string key, string value);
Reason for change
This method is being renamed to make its behavior more clear and to improve consistency with other Firebase APIs.
SetUserIdentifier is now SetUserId
Set a user identifier to help understand which user experienced a crash.
Fabric
Crashlytics.SetUserIdentifier(string identifier);
Firebase
Crashlytics.SetUserId(string identifier);
Reason for change
This method is being renamed to improve consistency with other Firebase APIs. As a bonus, it's shorter; who doesn't love shaving off key strokes?
SetUserEmail and SetUserName are removed
Previously, you were allowed to set a name or email associated with a crash using explicit methods. These will no longer be explicitly defined.
Fabric
Crashlytics.SetUserEmail(string email); Crashlytics.SetUserName(string name);
Reason for change
Google strives to protect customer data, and part of that effort is designing APIs that do the same for developer tooling. These user-specific APIs have been removed to encourage the use of generated and non-personally identifying methods for discerning which user was affected by a crash.
Workaround
To specify which user experienced a crash, the preferred method is to use
SetUserId
. However, if this is not a tenable solution, the same functionality
can be accomplished using SetCustomKey
.
Crash and ThrowNonFatal are removed
Previously, Crashlytics provided two utility methods to throw exceptions for testing purposes. These will not be included in Firebase Crashlytics.
Fabric
Crashlytics.Crash(); Crashlytics.ThrowNonFatal();
Reason for change
Crashlytics for Unity runs in many different environments, and many different kinds of crashes can occur. These methods did not clearly specify whether the resulting crashes occurred in C# or in the underlying platform-specific native SDK.
Workaround
- Test your implementation— Test your Crashlytics setup by forcing a crash to generate a crash report in the Firebase console.
Step 7: Build your project
After exporting your project to iOS or to Android, verify that the project exported correctly.
If it seems like files are missing after comparing your project to the sample export configurations below, open your Unity Editor, then run the Google Play Services Resolver.
iOS
Android
Run the resolver (optional)
The Google Play Services Resolvers make sure that your Unity project has the appropriate dependencies for exporting your app to iOS or to Android.
For more information on the resolver, visit the README for the Unity Jar Resolver.
iOS
The iOS Resolver runs automatically and leverages Cocoapods
to put iOS
dependencies in the exported Pods
directory.
To download Cocoapods to your machine:
- Navigate to Assets > Play Services Resolver > iOS Resolver > Install Cocoapods
To enable or disable generation of podfiles (optional):
- Navigate to Assets > Play Services Resolver > iOS Resolver > Settings
Android
The Android Resolver runs automatically and leverages gradle
to put Android
dependencies in Assets/Plugins/Android
.
To manually run the resolver:
- Navigate to Assets > Play Services Resolver > Android Resolver > Resolve
To enable or disable auto-resolution (enabled by default):
- Navigate to Assets > Play Services Resolver > Android Resolver > Settings
Next steps
Test your implementation— Test your Crashlytics setup by forcing a crash to generate a crash report in the Firebase console.
Customize crash reports— Crashlytics automatically starts collecting crash reports as soon as you add the SDK, but you can also customize your setup by adding opt-in reporting, logs, keys, and even tracking of non-fatal errors.
Learn about API Changes— See how Crashlytics has evolved from Fabric Crashlytics to Firebase Crashlytics.
Add Google Analytics— Combine the power of Google Analytics with Firebase Crashlytics to see the Crash Free Users statistics in the Firebase console.