flutter_analytics_manager 1.0.1

A comprehensive Flutter analytics manager package with Firebase Analytics and Mixpanel support.

Flutter Analytics Manager

A comprehensive Flutter analytics manager package that provides a clean, type-safe interface for analytics tracking across multiple analytics services simultaneously. Support for Firebase Analytics, Mixpanel, and custom analytics implementations with proper dependency injection and Clean Architecture principles.

Features

✅ Multi-Service Support: Use Firebase Analytics, Mixpanel, and custom services simultaneously ✅ Type-Safe: Full TypeScript-like safety with proper data models ✅ Clean Architecture: Proper dependency injection and separation of concerns ✅ Comprehensive Logging: Built-in logging with app_logger_manager integration ✅ Event Validation: Automatic sanitization and validation of events and parameters ✅ Privacy Controls: Built-in PII filtering and GDPR compliance features ✅ Session Management: Automatic session tracking and management ✅ Error Handling: Robust error handling with fallback mechanisms ✅ Utility Functions: Pre-built utility functions for common analytics events ✅ Offline Support: Queue events when offline and sync when online ✅ Performance Optimized: Efficient batching and throttling mechanisms ✅ Highly Testable: Easy to mock and unit test with dependency injection

Installation

Add this package to your pubspec.yaml:

dependencies:
  flutter_analytics_manager: ^1.0.1
  app_logger_manager: ^1.0.1

  # For Firebase Analytics
  firebase_analytics: ^11.5.0
  firebase_core: ^3.14.0

  # For Mixpanel
  mixpanel_flutter: ^2.4.4

copied to clipboard

Quick Start

1. Basic Setup with Dependency Injection

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

// Create logger
final logger = AppLoggerImpl();

// Initialize Firebase (if using Firebase Analytics)
await Firebase.initializeApp();

// Create analytics managers using dependency injection
final firebaseAnalytics = FirebaseAnalytics.instance;
final firebaseManager = FirebaseAnalyticsManager(
  analytics: firebaseAnalytics,
  logger: logger,
);
await firebaseManager.initialize();

final mixpanel = await Mixpanel.init('YOUR_MIXPANEL_PROJECT_TOKEN');
final mixpanelManager = MixpanelAnalyticsManager(
  mixpanel: mixpanel,
  logger: logger,
);
await mixpanelManager.initialize();

// Create multi-analytics manager
final analyticsManager = await MultiAnalyticsManager.create(
  managers: [firebaseManager, mixpanelManager],
  logger: logger,
  continueOnError: true,
);

copied to clipboard

2. Track Events

// Track a simple event
await analyticsManager.trackEvent(AnalyticsEvent(
  name: 'button_click',
  eventType: AnalyticsEventType.userEngagement,
  timestamp: DateTime.now(),
  parameters: {
    'button_name': 'login_button',
    'screen_name': 'home',
  },
));

// Track using utility functions
final loginEvent = AnalyticsUtilities.createLoginEvent(
  method: 'email',
  userId: 'user_123',
  additionalParameters: {'campaign': 'summer_sale'},
);
await analyticsManager.trackEvent(loginEvent);

copied to clipboard

3. Screen Tracking

// Track screen views
await analyticsManager.trackScreenView(
  screenName: 'home_screen',
  screenClass: 'HomePage',
  parameters: {
    'previous_screen': 'splash',
    'load_time': 1250,
  },
);

copied to clipboard

4. User Properties

// Set user properties
final userProperties = UserProperties(
  userId: 'user_123',
  name: 'John Doe',
  email: '[e-mail]',
  age: 25,
  customProperties: {
    'subscription_plan': 'premium',
    'signup_date': DateTime.now().toIso8601String(),
  },
);

await analyticsManager.setUserProperties(userProperties);

copied to clipboard

Firebase Analytics Setup

Android Setup

1. Add your google-services.json file to android/app/
2. Update android/build.gradle:

buildscript {
    dependencies {
        classpath 'com.google.gms:google-services:4.4.2'
    }
}

copied to clipboard

3. Update android/app/build.gradle:

apply plugin: 'com.google.gms.google-services'

dependencies {
    implementation platform('com.google.firebase:firebase-bom:33.4.0')
    implementation 'com.google.firebase:firebase-analytics'
}

copied to clipboard

iOS Setup

1. Add your GoogleService-Info.plist file to ios/Runner/
2. Update ios/Runner/Info.plist:

<key>FirebaseAppDelegateProxyEnabled</key>
<false/>

copied to clipboard

3. Initialize in ios/Runner/AppDelegate.swift:

import UIKit
import Flutter
import Firebase

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    FirebaseApp.configure()
    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

copied to clipboard

Mixpanel Setup

1. Get your project token from Mixpanel Dashboard
2. Initialize Mixpanel manager:

final mixpanel = await Mixpanel.init('YOUR_PROJECT_TOKEN_HERE');
final mixpanelManager = MixpanelAnalyticsManager(
  mixpanel: mixpanel,
  logger: logger,
);
await mixpanelManager.initialize();

copied to clipboard

Advanced Usage

Dependency Injection Benefits

The package now uses proper dependency injection, providing several benefits:

• Better Testability: Easy to mock Firebase Analytics and Mixpanel instances
• Separation of Concerns: Analytics managers only handle analytics, not SDK initialization
• Flexible Configuration: Full control over SDK initialization
• Consistent Architecture: Same pattern across all analytics managers

Advanced Firebase Configuration

// Custom Firebase app
await Firebase.initializeApp(
  name: 'myCustomApp',
  options: FirebaseOptions(
    apiKey: 'your-api-key',
    appId: 'your-app-id',
    messagingSenderId: 'your-sender-id',
    projectId: 'your-project-id',
  ),
);

final analytics = FirebaseAnalytics.instanceFor(
  app: Firebase.app('myCustomApp'),
);

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

copied to clipboard

Advanced Mixpanel Configuration

// Mixpanel with custom settings
final mixpanel = await Mixpanel.init(
  'your-project-token',
  trackAutomaticEvents: false, // Privacy-focused
);

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

copied to clipboard

Custom Analytics Service

Create your own analytics implementation:

class CustomAnalyticsManager implements AnalyticsManager {
  const CustomAnalyticsManager({
    required this.logger,
  });

  final AppLogger logger;

  @override
  Future<void> trackEvent(AnalyticsEvent event) async {
    // Your custom implementation
    logger.info('Custom Analytics: ${event.name}');
  }

  // ... implement other methods
}

copied to clipboard

Testing with Mocks

// Easy to test with dependency injection
final mockFirebaseAnalytics = MockFirebaseAnalytics();
final mockMixpanel = MockMixpanel();
final mockLogger = MockAppLogger();

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

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

// Test your analytics logic without external dependencies

copied to clipboard

Event Filtering

// Filter sensitive data
final filteredParams = AnalyticsUtilities.filterSensitiveParameters(
  eventParameters,
  sensitiveKeys: ['password', 'ssn', 'credit_card'],
);

copied to clipboard

Global Parameters

// Set global parameters sent with every event
analyticsManager.setGlobalParameters({
  'app_version': '1.0.0',
  'platform': 'flutter',
  'user_type': 'premium',
});

copied to clipboard

Session Management

// Start new session
await analyticsManager.startNewSession();

// End current session
await analyticsManager.endSession();

// Set custom session ID
await analyticsManager.setSessionId('custom_session_123');

copied to clipboard

Utility Functions

The package provides utility functions for common events:

// Login event
final loginEvent = AnalyticsUtilities.createLoginEvent(
  method: 'google',
  userId: 'user_123',
);

// Button click event
final buttonEvent = AnalyticsUtilities.createButtonClickEvent(
  buttonName: 'purchase_button',
  screenName: 'product_page',
);

// Performance event
final perfEvent = AnalyticsUtilities.createPerformanceEvent(
  operation: 'api_call',
  duration: Duration(milliseconds: 850),
);

// Error event
final errorEvent = AnalyticsUtilities.createErrorEvent(
  errorMessage: 'Network timeout',
  errorCode: 'NET_001',
);

// Search event
final searchEvent = AnalyticsUtilities.createSearchEvent(
  searchTerm: 'flutter analytics',
  resultCount: 42,
);

copied to clipboard

Event Types

Available event types:

• AnalyticsEventType.screenView - Screen navigation events
• AnalyticsEventType.userEngagement - User interaction events
• AnalyticsEventType.purchase - E-commerce and purchase events
• AnalyticsEventType.custom - Custom application events
• AnalyticsEventType.conversion - Conversion and goal events
• AnalyticsEventType.userProperty - User property change events

Error Handling

The package includes comprehensive error handling:

final analyticsManager = MultiAnalyticsManager(
  managers: [firebaseManager, mixpanelManager],
  continueOnError: true, // Continue if one service fails
);

// Individual service error handling
try {
  await analyticsManager.trackEvent(event);
} catch (e) {
  // Handle analytics errors
  print('Analytics error: $e');
}

copied to clipboard

Privacy and GDPR Compliance

Disable Analytics

// Disable all analytics tracking
await analyticsManager.setAnalyticsEnabled(false);

// Check if analytics is enabled
if (analyticsManager.isAnalyticsEnabled) {
  // Track events
}

copied to clipboard

Reset User Data

// Reset all user data (for logout/GDPR compliance)
await analyticsManager.resetUserData();

copied to clipboard

Filter Sensitive Data

// Automatically filter sensitive parameters
final safeParams = AnalyticsUtilities.filterSensitiveParameters(
  originalParameters,
  sensitiveKeys: ['email', 'phone', 'address'],
);

copied to clipboard

Testing

For testing, use the debug analytics manager:

final debugManager = DebugAnalyticsManager(logger); // Logs to console
final analyticsManager = MultiAnalyticsManager(
  managers: [debugManager],
);

copied to clipboard

Performance Tips

1. Batch Events: Use trackEvents() for multiple events
2. Global Parameters: Set common parameters globally instead of per event
3. Event Throttling: Use built-in throttling for high-frequency events
4. Offline Handling: Events are queued when offline and sent when reconnected

Migration from v1.0.0

If you're upgrading from v1.0.0, you'll need to update your initialization code:

// OLD (v1.0.0) - Factory constructors
final firebaseManager = await FirebaseAnalyticsManager.create(logger: logger);
final mixpanelManager = await MixpanelAnalyticsManager.create(
  projectToken: 'token',
  logger: logger,
);

// NEW (v1.0.1) - Dependency injection
final firebaseAnalytics = FirebaseAnalytics.instance;
final firebaseManager = FirebaseAnalyticsManager(
  analytics: firebaseAnalytics,
  logger: logger,
);
await firebaseManager.initialize();

final mixpanel = await Mixpanel.init('token');
final mixpanelManager = MixpanelAnalyticsManager(
  mixpanel: mixpanel,
  logger: logger,
);
await mixpanelManager.initialize();

copied to clipboard

Troubleshooting

Firebase Analytics Not Working

1. Verify google-services.json / GoogleService-Info.plist are properly added
2. Check Firebase project configuration
3. Ensure proper initialization in platform-specific code
4. Debug events may take 24-48 hours to appear in Firebase console

Mixpanel Not Working

1. Verify project token is correct
2. Check network connectivity
3. Use flush() to force immediate sending for testing

Common Issues

• Events not appearing: Check if analytics is enabled and properly initialized
• Parameter validation errors: Use utility functions to sanitize parameters
• Memory leaks: Always call dispose() when done

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, please:

1. Check the documentation
2. Search existing issues
3. Create a new issue with reproduction steps

Changelog

See CHANGELOG.md for version history and breaking changes.