72 lines
3.2 KiB
Markdown
72 lines
3.2 KiB
Markdown
---
|
|
name: flutter-firebase
|
|
description: Firebase Auth, Firestore, FCM, Crashlytics & Analytics Patterns
|
|
metadata:
|
|
platforms: "flutter, android, ios"
|
|
languages: "dart"
|
|
category: "backend"
|
|
---
|
|
|
|
# Firebase Setup
|
|
|
|
- Use `firebase_core` for initialization — call `Firebase.initializeApp()` before `runApp()`
|
|
- Use `flutterfire configure` for platform-specific setup
|
|
- Use separate Firebase projects per flavor (see `app-config` skill)
|
|
- Register Firebase services via `injectable` for consistent DI
|
|
|
|
# Authentication
|
|
|
|
- Use `firebase_auth` for user management
|
|
- Wrap all auth calls in an `AuthRepository` — no direct `FirebaseAuth` usage in BLoCs or UI
|
|
- Support email/password, Google Sign-In, and Apple Sign-In at minimum
|
|
- Handle auth state changes via `FirebaseAuth.instance.authStateChanges()` stream in `AuthBloc`
|
|
- Store auth tokens via `flutter_secure_storage` — never in `SharedPreferences` or source code
|
|
- Implement proper sign-out: clear local cache, navigate to login, dispose user-specific BLoCs
|
|
|
|
# Firestore
|
|
|
|
- Use `cloud_firestore` for remote data persistence
|
|
- DataSources wrap all Firestore calls (`get`, `set`, `update`, `delete`, `snapshots`)
|
|
- Use typed model classes with `fromFirestore` / `toFirestore` factory methods
|
|
- Prefer `.withConverter<T>()` for type-safe collection references
|
|
- Use batch writes for multi-document operations — never multiple sequential writes
|
|
- Implement offline persistence (enabled by default on mobile)
|
|
|
|
## Security Rules
|
|
|
|
- NEVER rely on client-side validation alone — enforce rules in Firestore Security Rules
|
|
- Default deny: start with `allow read, write: if false;` and open only what's needed
|
|
- Always validate `request.auth != null` for authenticated-only collections
|
|
- Test rules with the Firebase Emulator Suite before deploying
|
|
|
|
# Push Notifications (FCM)
|
|
|
|
- Use `firebase_messaging` for push notifications
|
|
- Request notification permissions early but gracefully (explain value before requesting)
|
|
- Handle foreground, background, and terminated-state messages separately
|
|
- Store FCM token in Firestore user document for server-side targeting
|
|
- Re-register token on `onTokenRefresh` stream
|
|
|
|
# Crashlytics
|
|
|
|
- Use `firebase_crashlytics` for crash reporting
|
|
- Enable in staging and production flavors only — disable in dev
|
|
- Record Flutter errors: `FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError`
|
|
- Catch async errors via `PlatformDispatcher.instance.onError`
|
|
- Add custom keys for user context: `Crashlytics.instance.setCustomKey('userId', id)`
|
|
|
|
# Analytics
|
|
|
|
- Use `firebase_analytics` for user behavior tracking
|
|
- Log meaningful events with descriptive names: `analytics.logEvent(name: 'purchase_completed')`
|
|
- Set user properties for segmentation: `analytics.setUserProperty(name: 'plan', value: 'premium')`
|
|
- Track screen views via `FirebaseAnalyticsObserver` in `GoRouter`
|
|
- NEVER log PII (emails, passwords, phone numbers) in analytics events
|
|
|
|
# Remote Config
|
|
|
|
- Use `firebase_remote_config` for feature flags and A/B testing
|
|
- Set sensible defaults locally — app MUST work without Remote Config fetched
|
|
- Fetch and activate on app start with a timeout fallback
|
|
- Cache values and respect minimum fetch intervals to avoid throttling
|