docs: getting started on android FirebaseUI v10

Author: russellwheatley

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:<latest-version>"))
+    implementation("com.google.firebase:firebase-auth")
+
+    implementation(platform("androidx.compose:compose-bom:<latest-version>"))
+    implementation("androidx.compose.material3:material3")
+
+    // Required only if Facebook Login support is needed
+    implementation("com.facebook.android:facebook-login:<latest-version>")
+}
+```
+
+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
+<resources>
+    <string name="facebook_application_id" translatable="false">YOUR_FACEBOOK_APP_ID</string>
+    <string name="facebook_login_protocol_scheme" translatable="false">fbYOUR_FACEBOOK_APP_ID</string>
+    <string name="facebook_client_token" translatable="false">YOUR_FACEBOOK_CLIENT_TOKEN</string>
+</resources>
+```
+
+### 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`.