flutter_analytics_manager 1.0.1

flutter_analytics_manager: ^1.0.1 copied to clipboard

🚨 Breaking Changes #

Dependency Injection Architecture

Major architectural improvement: Both FirebaseAnalyticsManager and MixpanelAnalyticsManager have been refactored from factory constructor pattern to proper dependency injection pattern, following Clean Architecture principles.

Migration Required: Update your initialization code as shown below.

Firebase Analytics Manager

BEFORE (v1.0.0):

// Factory constructor approach (removed)
final firebaseManager = await FirebaseAnalyticsManager.create(
  logger: logger,
  firebaseOptions: options, // optional
  autoInitializeFirebase: true, // optional
);

AFTER (v1.0.1):

// Dependency injection approach (new)
final firebaseAnalytics = FirebaseAnalytics.instance;
final firebaseManager = FirebaseAnalyticsManager(
  analytics: firebaseAnalytics,
  logger: logger,
);
await firebaseManager.initialize();

Mixpanel Analytics Manager

BEFORE (v1.0.0):

// Factory constructor approach (removed)
final mixpanelManager = await MixpanelAnalyticsManager.create(
  projectToken: 'your-token',
  trackAutomaticEvents: true, // optional
  logger: logger,
);

AFTER (v1.0.1):

// Dependency injection approach (new)
final mixpanel = await Mixpanel.init('your-token');
final mixpanelManager = MixpanelAnalyticsManager(
  mixpanel: mixpanel,
  logger: logger,
);
await mixpanelManager.initialize();

✨ Improvements #

Architectural Benefits

• Better Separation of Concerns: Analytics managers now only handle analytics tracking, not SDK initialization
• Improved Testability: Easy to mock FirebaseAnalytics and Mixpanel instances for unit testing
• Consistent Architecture: Both managers follow the same dependency injection pattern
• Flexible Configuration: Full control over Firebase and Mixpanel SDK initialization
• Clean Architecture Compliance: Proper dependency inversion principle implementation

Developer Experience

• Explicit Dependencies: Clear visibility of what dependencies each manager requires
• Better Error Handling: Separate initialization errors from analytics errors
• Advanced Configuration Support: Easy to configure custom Firebase apps or Mixpanel settings
• Testing-Friendly: Straightforward to create mocks and stubs for testing

🔧 Technical Changes #

• Removed: All factory constructor methods from FirebaseAnalyticsManager
  • create()
  • createWithOptions()
  • createWithExistingFirebase()
• Removed: All factory constructor methods from MixpanelAnalyticsManager
  • create()
  • createMinimal()
  • createWithFullTracking()
• Added: Constructor-based dependency injection for both managers
• Updated: Example application to demonstrate new pattern
• Improved: Error handling and logging throughout

📚 Documentation Updates #

• Updated README.md with new dependency injection examples
• Added migration guide for v1.0.0 users
• Updated example application
• Improved testing documentation with mock examples

🧪 Testing Improvements #

With the new dependency injection pattern, testing is now much easier:

// Easy unit testing with mocks
final mockFirebaseAnalytics = MockFirebaseAnalytics();
final mockMixpanel = MockMixpanel();
final mockLogger = MockAppLogger();

final firebaseManager = FirebaseAnalyticsManager(
  analytics: mockFirebaseAnalytics,
  logger: mockLogger,
);

final mixpanelManager = MixpanelAnalyticsManager(
  mixpanel: mockMixpanel,
  logger: mockLogger,
);

💡 Migration Steps #

1. Update Firebase Analytics initialization:

   // Initialize Firebase first
   await Firebase.initializeApp();
   
   // Get Firebase Analytics instance
   final firebaseAnalytics = FirebaseAnalytics.instance;
   
   // Create manager with dependency injection
   final firebaseManager = FirebaseAnalyticsManager(
     analytics: firebaseAnalytics,
     logger: logger,
   );
   await firebaseManager.initialize();
   

2. Update Mixpanel Analytics initialization:

   // Initialize Mixpanel first
   final mixpanel = await Mixpanel.init('your-project-token');
   
   // Create manager with dependency injection
   final mixpanelManager = MixpanelAnalyticsManager(
     mixpanel: mixpanel,
     logger: logger,
   );
   await mixpanelManager.initialize();
   

3. Update imports (if needed):

   import 'package:firebase_analytics/firebase_analytics.dart';
   import 'package:firebase_core/firebase_core.dart';
   import 'package:mixpanel_flutter/mixpanel_flutter.dart';
   

This release significantly improves the package's architecture and maintainability while providing a much better developer experience for testing and advanced configuration scenarios.

---

🎉 Initial Release #

Flutter Analytics Manager - A comprehensive, multi-provider analytics solution for Flutter applications.

✨ Features #

Core Analytics Interface

• Universal Analytics Interface: Clean, provider-agnostic analytics interface for consistent implementation across different analytics services
• Type-Safe Event Tracking: Strongly typed event tracking with custom properties and user identification
• User Properties Management: Comprehensive user property setting and management capabilities

Supported Analytics Providers

• Firebase Analytics: Full integration with Firebase Analytics including automatic screen tracking, custom events, and user properties
• Mixpanel Analytics: Complete Mixpanel integration with event tracking, user identification, and custom properties
• Multi-Provider Support: Simultaneously send analytics data to multiple providers with a single API call

Event Management

• Analytics Event Model: Structured event model with name, properties, and timestamp
• Event Type Enums: Predefined event types for common analytics scenarios (login, purchase, custom, etc.)
• Custom Properties: Support for custom event properties with flexible data types

User Management

• User Properties Model: Comprehensive user properties model with common fields (name, email, age, etc.)
• User Identification: Set user IDs and associate events with specific users
• User Property Updates: Update user properties across all configured analytics providers

Utilities & Helpers

• Analytics Utilities: Helper functions for common analytics operations
• Validation Helpers: Built-in validation for event names, properties, and user data
• Error Handling: Robust error handling with detailed logging and fallback mechanisms

Multi-Analytics Manager

• Unified Interface: Single interface to manage multiple analytics providers simultaneously
• Provider Management: Add, remove, and configure multiple analytics providers
• Batch Operations: Efficiently send events and user properties to all configured providers

🛠️ Technical Highlights #

• Clean Architecture: Follows interface-based design patterns for easy testing and maintenance
• Type Safety: Full type safety with proper null safety implementation
• Performance Optimized: Efficient batch processing and minimal overhead
• Framework Integration: Seamless integration with Flutter applications
• Extensible Design: Easy to add new analytics providers through the common interface

📦 Package Contents #

• Core analytics interface and implementations
• Firebase Analytics integration
• Mixpanel Analytics integration
• Event and user property models
• Utility functions and helpers
• Comprehensive example application

🚀 Getting Started #

// Initialize with multiple providers
final analyticsManager = MultiAnalyticsManager([
  FirebaseAnalyticsManager(),
  MixpanelAnalyticsManager(token: 'your-token'),
]);

// Track events
await analyticsManager.trackEvent(
  AnalyticsEvent(
    name: 'user_login',
    properties: {'method': 'email'},
  ),
);

// Set user properties
await analyticsManager.setUserProperties(
  UserProperties(
    userId: 'user123',
    email: 'user@example.com',
  ),
);

📱 Example Application #

• Complete example Flutter app demonstrating all features
• Analytics dashboard with real-time event tracking
• User profile management
• Settings configuration
• Multiple screen implementations

🧪 Testing #

• Comprehensive unit tests for all components
• Integration tests for provider implementations
• Example app for manual testing and validation

---

Note: This is the initial stable release of Flutter Analytics Manager. The package provides a solid foundation for analytics integration in Flutter applications with support for multiple providers and a clean, extensible architecture.