From e49d6c2e78ace2857ec9f4765e08e864746cf98b Mon Sep 17 00:00:00 2001 From: russellwheatley Date: Fri, 20 Mar 2026 10:52:18 +0000 Subject: [PATCH] docs: getting started on android FirebaseUI v10 --- GETTING_STARTED.md | 268 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 268 insertions(+) create mode 100644 GETTING_STARTED.md diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md new file mode 100644 index 000000000..a81fca145 --- /dev/null +++ b/GETTING_STARTED.md @@ -0,0 +1,268 @@ +# FirebaseUI Auth for Android + +FirebaseUI Auth is a modern, Compose-based authentication library for Firebase Authentication on Android. + +`10.x` is currently a beta release. + +If you used the older FirebaseUI Auth guides, the biggest change in `10.x` is that the recommended sign-in flow now uses Compose screens instead of `Intent` builders and `ActivityResultLauncher` callbacks. + +FirebaseUI Auth provides the following benefits: + +- Credential Manager integration for faster sign-in on Android. +- Material 3 UI that can inherit your app theme. +- Multiple authentication providers, including email/password, phone, Google, Facebook, Apple, GitHub, Microsoft, Yahoo, Twitter, anonymous auth, and custom OAuth. +- Multi-factor authentication support, including SMS and TOTP. +- Built-in flows for account management, account linking, and anonymous user upgrade. + +## Before you begin + +1. [Add Firebase to your Android project](https://firebase.google.com/docs/android/setup). +2. Make sure your app is set up for Jetpack Compose. +3. In the [Firebase console](https://console.firebase.google.com/), enable the sign-in methods you want to support. + +Add FirebaseUI Auth to your app module: + +```kotlin +dependencies { + implementation("com.firebaseui:firebase-ui-auth:10.0.0-beta02") + + // Most apps also declare Firebase and Compose dependencies directly. + implementation(platform("com.google.firebase:firebase-bom:")) + implementation("com.google.firebase:firebase-auth") + + implementation(platform("androidx.compose:compose-bom:")) + implementation("androidx.compose.material3:material3") + + // Required only if Facebook Login support is needed + implementation("com.facebook.android:facebook-login:") +} +``` + +The high-level FirebaseUI Auth API is Compose-based, so if your app is not already using Compose you will need to enable it first. + +## Provider configuration + +Some providers need additional setup before you can sign users in. + +### Google Sign-In + +- Enable Google in the Firebase console. +- Add your app's SHA fingerprint in Firebase. +- Download the updated `google-services.json`. +- `AuthProvider.Google(..., serverClientId = null)` can use the `default_web_client_id` generated by the `google-services` Gradle plugin. + +### Facebook Login + +If you support Facebook Login, add these values to `strings.xml`: + +```xml + + YOUR_FACEBOOK_APP_ID + fbYOUR_FACEBOOK_APP_ID + YOUR_FACEBOOK_CLIENT_TOKEN + +``` + +### Other providers + +Apple, GitHub, Microsoft, Yahoo, Twitter, and custom OAuth providers are configured in Firebase Authentication. Most of them do not require extra Android-specific resources. + +## Sign in + +Create an `AuthUIConfiguration`, then show `FirebaseAuthScreen`. + +```kotlin +class MainActivity : ComponentActivity() { + override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + + val authUI = FirebaseAuthUI.getInstance() + + setContent { + MyAppTheme { + val configuration = authUIConfiguration { + context = applicationContext + theme = AuthUITheme.fromMaterialTheme() + providers { + provider(AuthProvider.Email()) + provider( + AuthProvider.Google( + scopes = listOf("email"), + serverClientId = null, + ) + ) + } + } + + if (authUI.isSignedIn()) { + HomeScreen() + } else { + FirebaseAuthScreen( + configuration = configuration, + authUI = authUI, + onSignInSuccess = { result -> + // User signed in successfully + }, + onSignInFailure = { exception -> + // Sign in failed + }, + onSignInCancelled = { + finish() + }, + ) + } + } + } + } +} +``` + +This gives you a complete authentication flow with: + +- Email/password sign-in and sign-up. +- Google Sign-In. +- Password reset. +- Material 3 styling. +- Credential Manager support. +- Error handling through direct callbacks. + +## Configure providers + +Choose the providers you want inside `authUIConfiguration`: + +```kotlin +val configuration = authUIConfiguration { + context = applicationContext + providers { + provider(AuthProvider.Email()) + provider( + AuthProvider.Phone( + defaultCountryCode = "US", + ) + ) + provider( + AuthProvider.Google( + scopes = listOf("email"), + serverClientId = null, + ) + ) + provider(AuthProvider.Facebook()) + } +} +``` + +### Email link sign-in + +Email link sign-in now lives in the email provider configuration: + +```kotlin +val configuration = authUIConfiguration { + context = applicationContext + providers { + provider( + AuthProvider.Email( + isEmailLinkSignInEnabled = true, + emailLinkActionCodeSettings = actionCodeSettings { + url = "https://example.com/auth" + handleCodeInApp = true + setAndroidPackageName( + "com.example.app", + true, + null, + ) + }, + ) + ) + } +} +``` + +For the full deep-link handling flow, see `auth/README.md`. + +## Sign out + +FirebaseUI Auth provides convenience methods for sign-out and account deletion: + +```kotlin +lifecycleScope.launch { + FirebaseAuthUI.getInstance().signOut(applicationContext) +} +``` + +```kotlin +lifecycleScope.launch { + FirebaseAuthUI.getInstance().delete(applicationContext) +} +``` + +## Customization + +FirebaseUI Auth is much more customizable in `10.x`, but the simplest way to get started is to set a theme directly in `authUIConfiguration`: + +```kotlin +val configuration = authUIConfiguration { + context = applicationContext + providers { + provider(AuthProvider.Email()) + provider(AuthProvider.Google(scopes = listOf("email"), serverClientId = null)) + } + theme = AuthUITheme.Adaptive +} +``` + +You can also: + +- Use `AuthUITheme.Default`, `AuthUITheme.DefaultDark`, or `AuthUITheme.Adaptive`. +- Inherit your app theme with `AuthUITheme.fromMaterialTheme()`. +- Customize the default theme with `.copy()`. +- Build a fully custom `AuthUITheme`. +- Set a logo, Terms of Service URL, and Privacy Policy URL in `authUIConfiguration`. + +For full theming and customization details, including theme precedence, provider button styling, and custom themes, see `auth/README.md`. + +## Existing Activity-based apps + +If your app still uses Activities and the Activity Result API, you can keep an Activity-based launch flow by using `AuthFlowController`: + +```kotlin +private val authLauncher = registerForActivityResult( + ActivityResultContracts.StartActivityForResult(), +) { result -> + if (result.resultCode == RESULT_OK) { + val user = FirebaseAuth.getInstance().currentUser + // ... + } else { + // User cancelled or sign-in failed + } +} + +val configuration = authUIConfiguration { + context = applicationContext + providers { + provider(AuthProvider.Email()) + provider( + AuthProvider.Google( + scopes = listOf("email"), + serverClientId = null, + ) + ) + } +} + +val controller = FirebaseAuthUI.getInstance().createAuthFlow(configuration) +authLauncher.launch(controller.createIntent(this)) +``` + +This is the closest match to the old FirebaseUI Auth mental model, but the Compose `FirebaseAuthScreen` API is the recommended starting point for new integrations. + +## Migrating from the old FirebaseUI Auth flow + +If you are coming from `9.x` or the older Firebase documentation: + +- `AuthUI.getInstance().createSignInIntentBuilder()` becomes `authUIConfiguration {}` plus `FirebaseAuthScreen`. +- `AuthUI.IdpConfig.*Builder()` becomes `AuthProvider.*`. +- XML-based FirebaseUI theme resources become `AuthUITheme`. +- `ActivityResultLauncher` result parsing becomes direct success, failure, and cancel callbacks. +- Activity-based flows are still possible through `AuthFlowController`. + +For a complete migration guide, see `auth/README.md` and `docs/upgrade-to-10.0.md`.