Upgrade your iOS app from Firebase.com

This document guides you through upgrading your existing Firebase.com app to the new Firebase console and APIs.

There are four steps to take:

  1. Upgrade your project to the new Firebase console
  2. Install the new Firebase SDK
  3. Update your database code
  4. Update your authentication code

You can upgrade your project to the new firebase.google.com console at any time. Your applications will continue to work. You can then update your code when you are ready to use some of the new Firebase features in your application.

Import your project to the new Firebase console

  • Go to the Firebase console and find your project under "Projects currently at Firebase.com".
  • Click Import for the project you're looking to upgrade.
    • If your project is on a paid plan on firebase.com, you will need to set up the billing for the project in the new console. Your billing information is not automatically migrated
    • Select or create a billing account. After importing, this account is responsible for all charges for the project.
  • Your Realtime Database and Hosting content are automatically and instantly imported to the Firebase console.
  • Your user data is automatically migrated to the new authentication backend. This happens in the background and your users can continue to use the app while the data is being migrated. User signups and logins will not be affected. While the system is migrating user accounts, you will see a spinner in the Auth tab of the Firebase console.
  • If you have an active promo code for a Firebase.com app, reach out to us.

Install the new Firebase SDK

You don't have to update the code of your applications right away. Existing database and authentication code will continue to work against your migrated project. But when you are ready to start using some of the new Firebase features in your application, you can Install the new Firebase SDK.

Note that when you start using the new SDK, Firebase Analytics is automatically enabled. By default, your Firebase Analytics data will enhance other Firebase features and Google products. You can control how your Firebase Analytics data is shared in your settings at any time. Learn more

Configure your app

Your app is now configured using the GoogleService-Info.plist file you can download from the Firebase console. To easily add the configuration to your project, drag the downloaded GoogleService-Info.plist into your Xcode project (make sure to select "Copy items if needed" so it is added to your project directory).

The GoogleService-Info.plist file is processed by the FIRApp class. In your application:didFinishLaunchingWithOptions: method in your AppDelegate class, add the following call:

Objective-C

[FIRApp configure];

Swift

FIRApp.configure()

Update your database code

Update your CocoaPods dependencies

The easiest way to get started is to change your CocoaPods dependencies. As of verison 3.x, the Firebase pod has separate subspecs for each API:

BEFORE
pod 'Firebase', '>= 2.5.1'
AFTER
pod 'Firebase/Core'
pod 'Firebase/Database'

Run pod update to get the new pods. Your app will likely now have a number of compile errors or warnings where API names have changed. The rest of this guide describes how to fix those problems.

First, replace your #import line if you're using Objective-C (if you're using Swift, there's no change!)

BEFORE
#import <Firebase/Firebase.h>
AFTER
@import Firebase

Get a database reference

In the 3.x SDK, Firebase references are replaced by FIRDatabaseReference and you use the FIRDatabase class to get an initial reference to your database. So after configuring FIRApp, you can get the database reference in your code as follows:

BEFORE

Objective-C

Firebase *rootRef = [[Firebase alloc] initWithUrl:@"https://<YOUR-FIREBASE-APP>.firebaseio.com"];

Swift

var rootRef = Firebase(url:"https://<YOUR-FIREBASE-APP>.firebaseio.com")
AFTER

Objective-C

FIRDatabaseReference *rootRef= [[FIRDatabase database] reference];

Swift

var rootRef = FIRDatabase.database().reference()

Note that your Database URL is automatically determined from your GoogleService-Info.plist file so you don't need to specify it.

Enable disk persistence

If your app uses disk persistence you now enable it via the FIRDatabase object:

BEFORE

Objective-C

[Firebase defaultConfig].persistenceEnabled = YES;

Swift

Firebase.defaultConfig().persistenceEnabled = true
AFTER

Objective-C

[FIRDatabase database].persistenceEnabled = YES;

Swift

FIRDatabase.database().persistenceEnabled = true

Like in the 2.x SDK, enabling disk persistence must be done before any other calls to the database are made.

Update class / method references

Several Database types were renamed in the 3.x SDK in order to conform with other APIs. This table shows some common changes you'll need to make.

Before After
Firebase FIRDatabaseReference
FDataSnapshot FIRDataSnapshot
FirebaseHandle FIRDatabaseHandle
FEventType FIRDataEventType
FQuery FIRDatabaseQuery
FMutableData FIRMutableData
FTransactionResult FIRTransactionResult
FConfig FIRDatabase
FirebaseApp FIRDatabase
kFirebaseServerValueTimestamp [FIRServerValue timestamp]

If you can't find a class or method you're looking for, take a look at the Database Reference docs.

Update your authentication code

Firebase Authentication functionality now lives behind its own FIRAuth class, so authentication operations are now done on a FIRAuth instance instead of via a Firebase reference.

Update your CocoaPods dependencies

Since Authentication now lives in its own module, you first need to add a dependency to your Podfile:

pod 'Firebase/Auth'

You will need to run pod update again after adding the dependency.

Sign a user in

The authentication methods work similarly to how they worked before, but now exist as methods on the FIRAuth object with new names, and FAuthData is now replaced by FIRUser, for example:

BEFORE

Objective-C

[ref authAnonymouslyWithCompletionBlock:^(NSError *error, FAuthData *authData) {
    if (error) {
        NSLog(@"Sign in failed: %@", error.localizedDescription);
    } else {
        NSLog(@"Signed in with uid: %@", authData.uid);
    }
}];

Swift

ref.authAnonymouslyWithCompletionBlock { error, authData in
    if let error = error {
        print("Sign in failed:", error.localizedDescription)
    } else {
        print("Signed in with uid:", authData.uid)
    }
}
AFTER

Objective-C

[[FIRAuth auth] signInAnonymouslyWithCompletion:^(FIRUser *_Nullable user,
                                                  NSError *_Nullable error) {
    if (error) {
        NSLog(@"Sign in failed: %@", error.localizedDescription);
    } else {
        NSLog(@"Signed in with uid: %@", user.uid);
    }
}];

Swift

FIRAuth.auth()!.signInAnonymouslyWithCompletion() { (user, error) in
    if let error = error {
        print("Sign in failed:", error.localizedDescription)
    } else {
        print ("Signed in with uid:", user!.uid)
    }
}

For documentation on other authentication providers, see the FIRAuth class or the Firebase Authentication Guide.

Sign a user in with a custom token

Authenticating with custom tokens on the client side also works similarly to how they worked before. Here is how signing in with a custom token works both in the 2.x API and in the new API:

BEFORE

Objective-C

[ref authWithCustomToken:AUTH_TOKEN
     withCompletionBlock:^(NSError *error, FAuthData *authData) {
    if (error) {
        NSLog(@"Login Failed! %@", error);
    } else {
        NSLog(@"Login succeeded! %@", authData);
    }
}];

Swift

ref.authWithCustomToken(AUTH_TOKEN, withCompletionBlock: { error, authData in
    if error != nil {
        println("Login failed! \(error)")
    } else {
        println("Login succeeded! \(authData)")
    }
})
AFTER

Objective-C

[[FIRAuth auth] signInWithCustomToken:customToken
                           completion:^(FIRUser *_Nullable user,
                                        NSError *_Nullable error) {
                             // ...
                           }];

Swift

FIRAuth.auth()?.signIn(withCustomToken: customToken ?? "") { (user, error) in
  // ...
}

The custom tokens you generate on your server have a new format. You can use the Firebase Admin SDKs for Node.js and Java to create custom tokens that are compatible with the new API, or you can create custom tokens using a third-party JWT library.

Note that the Firebase Admin SDKs generate custom tokens that expire after one hour, unlike the helper libraries for the 2.x API, which by default generate tokens that expire after 24 hours.

Sign a user out

BEFORE

Objective-C

[ref unauth];

Swift

ref.unauth()
AFTER

Objective-C

[[FIRAuth auth] signOut:nil];

Swift

try! FIRAuth.auth()!.signOut()

Monitor authentication state

BEFORE

Objective-C

[ref observeAuthEventWithBlock:^(FAuthData *authData) {
    if (authData) {
        NSLog(@"User is signed in with uid: %@", authData.uid);
    } else {
        NSLog(@"No user is signed in.");
    }
}];

Swift

ref.observeAuthEventWithBlock({ authData in
    if authData != nil {
        print("User is signed in with uid:", authData.uid)
    } else {
        print("No user is signed in.")
    }
})
AFTER

Objective-C

[[FIRAuth auth] addAuthStateDidChangeListener:^(FIRAuth * _Nonnull auth, FIRUser * _Nullable user) {
    if (user) {
        NSLog(@"User is signed in with uid: %@", user.uid);
    } else {
        NSLog(@"No user is signed in.");
    }
  }];

Swift

FIRAuth.auth()!.addAuthStateDidChangeListener() { (auth, user) in
    if let user = user {
        print("User is signed in with uid:", user.uid)
    } else {
        print("No user is signed in.")
    }
}

FIRAuth has a number of new features (account linking, more auth providers, etc.). See the Authentication Guide and Authentication Reference Docs for more details.

Migrate existing logins

If users have logged into your app with a legacy SDK, then you'll need a bit of code to keep them signed in with the new SDK. Otherwise, they would have to sign in again. Open source sample code for doing this is provided in the Firebase Auth Migration Helpers GitHub repo.

Update the new password reset template

If your app allows users to sign-in with Email & Password authentication , you probably also give these users the option to reset their password.

Once you've upgraded to the new SDK, those password reset emails will use the new templates specified in the Firebase Console. Be sure to update them for the needs of your app.

Update your Firebase libraries

If you're using any of the following libraries, you'll need to upgrade to the latest version.

Library Supported Version Resource
GeoFire 1.2.x Github

Send feedback about...

Need help? Visit our support page.