Phone authentication allows users to sign in to Firebase using their phone as the authenticator. An SMS message is sentto the user (using the provided phone number) containing a unique code. Once the code has been authorized, the user is able to signinto Firebase.

Phone numbers that end users provide for authentication will be sent and stored by Google to improve spam and abuseprevention across Google service, including to, but not limited to Firebase. Developers should ensure they have theappropriate end-user consent prior to using the Firebase Authentication phone number sign-in service.authentication

Firebase Phone Authentication is not supported in all countries. Please see theirFAQs for more information.

Setup

Before starting with Phone Authentication, ensure you have followed these steps:

1. Enable Phone as a Sign-In method in theFirebase console.
2. Android: If you haven't already set your app's SHA-1 hash in theFirebase console, do so.SeeAuthenticating Your Client for information about finding your app's SHA-1 hash.
3. iOS: In Xcode,enable push notifications for your project & ensureyour APNs authentication key isconfigured with Firebase Cloud Messaging (FCM). Additionally, you mustenable background modes for remote notifications.To view an in-depth explanation of this step, view theFirebase iOS Phone Auth documentation.
4. Web: Ensure that you have added your applications domain on theFirebase console, underOAuth redirect domains.

Note; Phone number sign-in is only available for use on real devices and the web. To test your authentication flow on device emulators,please seeTesting.

Usage

The Firebase Authentication SDK for Flutter provides two individual ways to sign a user in with their phone number. Native (e.g. Android & iOS) platforms providedifferent functionality to validating a phone number than the web, therefore two methods exist for each platform exclusively:

• Native Platform:verifyPhoneNumber.
• Web Platform:signInWithPhoneNumber.

Native:verifyPhoneNumber

On native platforms, the user's phone number must be first verified and then the user can either sign-in or link their account with aPhoneAuthCredential.

First you must prompt the user for their phone number. Once provided, call theverifyPhoneNumber() method:

awaitFirebaseAuth.instance.verifyPhoneNumber(phoneNumber:'+44 7123 123 456',verificationCompleted:(PhoneAuthCredentialcredential){},verificationFailed:(FirebaseAuthExceptione){},codeSent:(StringverificationId,int?resendToken){},codeAutoRetrievalTimeout:(StringverificationId){},);

There are 4 separate callbacks that you must handle, each will determine how you update the application UI:

1. verificationCompleted: Automatic handling of the SMS code on Android devices.
2. verificationFailed: Handle failure events such as invalid phone numbers or whether the SMS quota has been exceeded.
3. codeSent: Handle when a code has been sent to the device from Firebase, used to prompt users to enter the code.
4. codeAutoRetrievalTimeout: Handle a timeout of when automatic SMS code handling fails.

verificationCompleted

This handler will only be called on Android devices which support automatic SMS code resolution.

When the SMS code is delivered to the device, Android will automatically verify the SMS code withoutrequiring the user to manually input the code. If this event occurs, aPhoneAuthCredential is automatically provided which can beused to sign-in with or link the user's phone number.

FirebaseAuthauth=FirebaseAuth.instance;awaitauth.verifyPhoneNumber(phoneNumber:'+44 7123 123 456',verificationCompleted:(PhoneAuthCredentialcredential)async{// ANDROID ONLY!// Sign the user in (or link) with the auto-generated credentialawaitauth.signInWithCredential(credential);},);

verificationFailed

If Firebase returns an error, for example for an incorrect phone number or if the SMS quota for the project has exceeded,aFirebaseAuthException will be sent to this handler. In this case, you would prompt your user something went wrong depending on the errorcode.

FirebaseAuthauth=FirebaseAuth.instance;awaitauth.verifyPhoneNumber(phoneNumber:'+44 7123 123 456',verificationFailed:(FirebaseAuthExceptione){if(e.code=='invalid-phone-number'){print('The provided phone number is not valid.');}// Handle other errors},);

codeSent

When Firebase sends an SMS code to the device, this handler is triggered with averificationId andresendToken (AresendTokenis only supported on Android devices, iOS devices willalways return anull value).

Once triggered, it would be a good time to update your application UI to prompt the user to enter the SMS code they're expecting.Once the SMS code has been entered, you can combine the verification ID with the SMS code to create a newPhoneAuthCredential:

FirebaseAuthauth=FirebaseAuth.instance;awaitauth.verifyPhoneNumber(phoneNumber:'+44 7123 123 456',codeSent:(StringverificationId,int?resendToken)async{// Update the UI - wait for the user to enter the SMS codeStringsmsCode='xxxx';// Create a PhoneAuthCredential with the codePhoneAuthCredentialcredential=PhoneAuthProvider.credential(verificationId:verificationId,smsCode:smsCode);// Sign the user in (or link) with the credentialawaitauth.signInWithCredential(credential);},);

By default, Firebase will not re-send a new SMS message if it has been recently sent. You can however override this behaviorby re-calling theverifyPhoneNumber method with the resend token to theforceResendingToken argument.If successful, the SMS message will be resent.

codeAutoRetrievalTimeout

On Android devices which support automatic SMS code resolution, this handler will be called if the device has not automaticallyresolved an SMS message within a certain timeframe. Once the timeframe has passed, the device will no longer attempt to resolveany incoming messages.

By default, the device waits for 30 seconds however this can be customized with thetimeout argument:

FirebaseAuthauth=FirebaseAuth.instance;awaitauth.verifyPhoneNumber(phoneNumber:'+44 7123 123 456',timeout:constDuration(seconds:60),codeAutoRetrievalTimeout:(StringverificationId){// Auto-resolution timed out...},);

Web:signInWithPhoneNumber

On web platforms, users can sign-in by confirming they have access to a phone by entering the SMS code sent to the provided phone number.For added security and spam prevention, users are requested to prove they are human by completing aGoogle reCAPTCHAwidget. Once confirmed, the SMS code will be sent.

The Firebase Authentication SDK for Flutter will manage the reCAPTCHA widget out of the box by default, however provides control over how it is displayed and configured if required.To get started, call thesignInWithPhoneNumber method with the phone number.

FirebaseAuthauth=FirebaseAuth.instance;// Wait for the user to complete the reCAPTCHA & for an SMS code to be sent.ConfirmationResultconfirmationResult=awaitauth.signInWithPhoneNumber('+44 7123 123 456');

Calling the method will first trigger the reCAPTCHA widget to display. The user must complete thetest before an SMS code is sent. Once complete, you can then sign the user in by providing theSMS code to theconfirm method on the resolvedConfirmationResult response:

UserCredentialuserCredential=awaitconfirmationResult.confirm('123456');

Like other sign-in flows, a successful sign-in will trigger any authentication state listenersyou have subscribed throughout your application.

reCAPTCHA Configuration

The reCAPTCHA widget is a fully managed flow which provides security to your web application.

The second argument ofsignInWithPhoneNumber accepts an optionalRecaptchaVerifier instance which can be usedto manage the widget. By default, the widget will render as an invisible widget when the sign-in flow is triggered.An "invisible" widget will appear as a full-page modal on-top of your application.

It is however possible to display an inline widget which the user has to explicitly press to verify themselves.

To add an inline widget, specify a DOM element ID to thecontainer argument of theRecaptchaVerifier instance.The element must exist and be empty otherwise an error will be thrown.If nocontainer argument is provided, the widget will be rendered as "invisible".

ConfirmationResultconfirmationResult=awaitauth.signInWithPhoneNumber('+44 7123 123 456',RecaptchaVerifier(container:'recaptcha',size:RecaptchaVerifierSize.compact,theme:RecaptchaVerifierTheme.dark,));

You can optionally change the size and theme by customizing thesize andtheme arguments as shown above.

It is also possible to listen to events, such as whether the reCAPTCHA has been completed by the user, whetherthe reCAPTCHA has expired or an error was thrown:

RecaptchaVerifier(onSuccess:()=>print('reCAPTCHA Completed!'),onError:(FirebaseAuthExceptionerror)=>print(error),onExpired:()=>print('reCAPTCHA Expired!'),);

Testing

Firebase provides support for locally testing phone numbers:

1. On the Firebase Console, select the "Phone" authentication provider and click on the "Phone numbers for testing" dropdown.
2. Enter a new phone number (e.g.+44 7444 555666) and a test code (e.g.123456).

If providing a test phone number to either theverifyPhoneNumber orsignInWithPhoneNumber methods, no SMS will actually be sent. Youcan instead provide the test code directly to thePhoneAuthProvider or withsignInWithPhoneNumbers confirmation result handler.