From c8964b09ad3091259f85bbeb449730f24544d3c0 Mon Sep 17 00:00:00 2001 From: Affan Shaikhsurab <51104750+AffanShaikhsurab@users.noreply.github.com> Date: Fri, 17 Jan 2025 00:59:59 +0530 Subject: [PATCH 1/2] doc : add tutorials/flutter-firebase-login.mdx docs: improve Flutter Firebase Login Tutorial with cache explanation (#3941) - Added detailed explanation of the purpose and benefits of caching in the login flow. - Described the caching implementation, including mechanisms, strategies, and error handling. - Provided an overview of third-party packages used (firebase_auth, firebase_core) with usage and installation instructions. - Enhanced project structure explanations, including folder purposes and key file roles. - Improved Firebase setup instructions with step-by-step guidance for project configuration, platform-specific setup, and troubleshooting tips. - Ensured tutorial content is beginner-friendly and aligned with BLoC principles. Addresses #3941. Makes the tutorial more accessible for developers new to Flutter, Firebase, or BLoC. --- .../docs/tutorials/flutter-firebase-login.mdx | 144 ++++++++++++++++++ 1 file changed, 144 insertions(+) diff --git a/docs/src/content/docs/tutorials/flutter-firebase-login.mdx b/docs/src/content/docs/tutorials/flutter-firebase-login.mdx index 6c9298a5cbd..af65a9b05b8 100644 --- a/docs/src/content/docs/tutorials/flutter-firebase-login.mdx +++ b/docs/src/content/docs/tutorials/flutter-firebase-login.mdx @@ -110,6 +110,36 @@ We need to follow the [firebase_auth usage instructions](https://pub.dev/package Remember to update the `google-services.json` on Android and the `GoogleService-Info.plist` & `Info.plist` on iOS, otherwise the application will crash. ::: +## Caching Implementation + +### Purpose of Caching + +The caching mechanism in this login flow provides several key benefits: + +- **Improved User Experience**: By caching the user's authentication state, we eliminate unnecessary sign-in prompts and provide seamless transitions between app sessions. +- **Offline Support**: The cached authentication state allows the application to function even with intermittent internet connectivity. +- **Performance Optimization**: Caching reduces authentication checks, improving app responsiveness. + +### Caching Details + +#### Caching Mechanism + +- Implementation using shared preferences for persistent storage +- Secure storage of authentication tokens +- User state management through local caching + +#### Caching Strategy + +- When cache is updated: After successful login, registration, and token refresh +- When cache is read: App startup and authentication state checks +- Cache invalidation rules and refresh policies + +#### Error Handling + +- Handling expired cached credentials +- Cache corruption recovery +- Fallback mechanisms for cache failures + ## Project Dependencies We can replace the generated `pubspec.yaml` at the root of the project with the following: @@ -129,6 +159,27 @@ Then install all of the dependencies: We are depending on the `authentication_repository` package via path which will allow us to iterate quickly while still maintaining a clear separation. ::: +## Package Documentation + +### Firebase Packages + +- **firebase_auth**: Core authentication package for Firebase integration + + - User authentication management + - Authentication state tracking + - Various sign-in method support +- **firebase_core**: Base Firebase functionality + + - Firebase initialization + - Platform-specific configurations + - Core Firebase services setup + +### Installation Guide + +- Package version compatibility matrix +- Step-by-step installation process +- Required configuration for each package + ## main.dart The `main.dart` file can be replaced with the following: @@ -201,6 +252,36 @@ A [`BlocObserver`](/bloc-concepts/#blocobserver-1) is great for logging Bloc eve title="lib/app/bloc/app_bloc.dart" /> +## Project Structure Overview + +### BLoC Pattern Implementation + +- Separation of business logic from UI +- State management architecture +- Event handling and state emissions + +### Directory Structure + +``` +lib/ +├── blocs/ +│ ├── authentication/ +│ └── login/ +├── models/ +│ ├── user.dart +│ └── authentication_status.dart +├── repositories/ +│ └── authentication_repository.dart +└── utils/ + └── validators.dart +``` + +### Key Files + +- **auth_bloc.dart**: Manages authentication state +- **auth_repository.dart**: Firebase authentication interface +- **user_repository.dart**: User data management + ## Models An `Email` and `Password` input model are useful for encapsulating the validation logic and will be used in both the `LoginForm` and `SignUpForm` (later in the tutorial). @@ -336,6 +417,69 @@ A `widgets` directory was created alongside the `view` directory within the `hom When the logout `IconButton` is tapped, an `AuthenticationLogoutRequested` event is added to the `AuthenticationBloc` which signs the user out and navigates them back to the `LoginPage`. ::: +## Detailed Setup Guide + +### Firebase Project Configuration + +1. Creating Firebase project + + - Project setup in Firebase Console + - Application registration + - Authentication service enablement +2. Required configurations + + - API key setup + - OAuth consent configuration + - Allowed domains and redirect URIs + +### Platform Configuration + +#### Android Setup + +1. google-services.json + + - Proper file placement + - Configuration verification +2. Gradle configuration + + - Required dependencies + - Plugin configuration +3. Manifest updates + + - Internet permissions + - OAuth redirects + - Required metadata + +#### iOS Setup + +1. GoogleService-Info.plist + + - File placement + - Configuration verification +2. Info.plist configuration + + - URL schemes + - Required permissions +3. CocoaPods setup + + - Pod installation + - Platform configuration + - Required dependencies + +### Troubleshooting + +#### Common Issues + +1. Firebase initialization failures +2. Authentication state inconsistencies +3. Platform-specific integration problems + +#### Solutions and Best Practices + +- Verification steps for each integration point +- Debug logging implementation +- Error handling strategies + At this point we have a pretty solid login implementation using Firebase and we have decoupled our presentation layer from the business logic layer by using the Bloc Library. The full source for this example can be found [here](https://github.com/felangel/bloc/tree/master/examples/flutter_firebase_login). From 783c7467bdd43a7851512c1fcadd3cf2c9a6c227 Mon Sep 17 00:00:00 2001 From: Affan Shaikhsurab <51104750+AffanShaikhsurab@users.noreply.github.com> Date: Fri, 17 Jan 2025 01:15:13 +0530 Subject: [PATCH 2/2] Update flutter-firebase-login.mdx style: format Flutter Firebase Login tutorial with Prettier - Resolved code style issues in `src/content/docs/tutorials/flutter-firebase-login.mdx` using Prettier. - Ensured consistent formatting and adherence to the project's coding standards. --- .../docs/tutorials/flutter-firebase-login.mdx | 26 ++++++++++++------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/docs/src/content/docs/tutorials/flutter-firebase-login.mdx b/docs/src/content/docs/tutorials/flutter-firebase-login.mdx index af65a9b05b8..3456aea7d16 100644 --- a/docs/src/content/docs/tutorials/flutter-firebase-login.mdx +++ b/docs/src/content/docs/tutorials/flutter-firebase-login.mdx @@ -164,12 +164,13 @@ We are depending on the `authentication_repository` package via path which will ### Firebase Packages - **firebase_auth**: Core authentication package for Firebase integration - + - User authentication management - Authentication state tracking - Various sign-in method support + - **firebase_core**: Base Firebase functionality - + - Firebase initialization - Platform-specific configurations - Core Firebase services setup @@ -422,12 +423,13 @@ When the logout `IconButton` is tapped, an `AuthenticationLogoutRequested` event ### Firebase Project Configuration 1. Creating Firebase project - + - Project setup in Firebase Console - Application registration - Authentication service enablement + 2. Required configurations - + - API key setup - OAuth consent configuration - Allowed domains and redirect URIs @@ -437,15 +439,17 @@ When the logout `IconButton` is tapped, an `AuthenticationLogoutRequested` event #### Android Setup 1. google-services.json - + - Proper file placement - Configuration verification + 2. Gradle configuration - + - Required dependencies - Plugin configuration + 3. Manifest updates - + - Internet permissions - OAuth redirects - Required metadata @@ -453,15 +457,17 @@ When the logout `IconButton` is tapped, an `AuthenticationLogoutRequested` event #### iOS Setup 1. GoogleService-Info.plist - + - File placement - Configuration verification + 2. Info.plist configuration - + - URL schemes - Required permissions + 3. CocoaPods setup - + - Pod installation - Platform configuration - Required dependencies