fluxy_analytics 1.0.0

Analytics plugin for the Fluxy framework.

fluxy_analytics

Analytics plugin for the Fluxy framework, providing comprehensive analytics tracking and user behavior monitoring capabilities.

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  fluxy_analytics: ^1.0.0

Usage

First, ensure you have Fluxy initialized and the analytics plugin registered:

import 'package:fluxy/fluxy.dart';

void main() async {
  await Fluxy.init();
  Fluxy.autoRegister(); // Registers all available plugins including analytics
  
  runApp(MyApp());
}

Basic Analytics Tracking

import 'package:fluxy/fluxy.dart';

class AnalyticsService {
  // Initialize analytics
  Future<void> initializeAnalytics() async {
    try {
      await Fx.analytics.initialize();
      Fx.toast.success('Analytics initialized');
    } catch (e) {
      Fx.toast.error('Analytics initialization failed: $e');
    }
  }
  
  // Track custom event
  Future<void> trackEvent(String eventName, {Map<String, dynamic>? parameters}) async {
    try {
      await Fx.analytics.track(eventName, parameters: parameters);
      Fx.toast.success('Event tracked: $eventName');
    } catch (e) {
      Fx.toast.error('Failed to track event: $e');
    }
  }
  
  // Track screen view
  Future<void> trackScreenView(String screenName) async {
    try {
      await Fx.analytics.trackScreen(screenName);
      Fx.toast.success('Screen view tracked: $screenName');
    } catch (e) {
      Fx.toast.error('Failed to track screen view: $e');
    }
  }
  
  // Set user property
  Future<void> setUserProperty(String name, String value) async {
    try {
      await Fx.analytics.setUserProperty(name, value);
      Fx.toast.success('User property set: $name');
    } catch (e) {
      Fx.toast.error('Failed to set user property: $e');
    }
  }
}

Advanced Analytics Features

class AdvancedAnalyticsService {
  // Track user engagement
  Future<void> trackUserEngagement(String action, {Map<String, dynamic>? context}) async {
    try {
      await Fx.analytics.track('user_engagement', parameters: {
        'action': action,
        'timestamp': DateTime.now().toIso8601String(),
        ...?context,
      });
    } catch (e) {
      Fx.toast.error('Failed to track user engagement: $e');
    }
  }
  
  // Track app performance
  Future<void> trackPerformance(String metric, double value) async {
    try {
      await Fx.analytics.track('app_performance', parameters: {
        'metric': metric,
        'value': value,
        'device': Platform.operatingSystem,
      });
    } catch (e) {
      Fx.toast.error('Failed to track performance: $e');
    }
  }
  
  // Track error events
  Future<void> trackError(String error, {String? stackTrace}) async {
    try {
      await Fx.analytics.track('app_error', parameters: {
        'error': error,
        'stack_trace': stackTrace,
        'timestamp': DateTime.now().toIso8601String(),
      });
    } catch (e) {
      Fx.toast.error('Failed to track error: $e');
    }
  }
  
  // Track conversion events
  Future<void> trackConversion(String conversionType, double value) async {
    try {
      await Fx.analytics.track('conversion', parameters: {
        'type': conversionType,
        'value': value,
        'currency': 'USD',
      });
    } catch (e) {
      Fx.toast.error('Failed to track conversion: $e');
    }
  }
}

User Management

class UserAnalyticsService {
  // Set user ID
  Future<void> setUserId(String userId) async {
    try {
      await Fx.analytics.setUserId(userId);
      Fx.toast.success('User ID set: $userId');
    } catch (e) {
      Fx.toast.error('Failed to set user ID: $e');
    }
  }
  
  // Set user properties
  Future<void> setUserProperties(Map<String, String> properties) async {
    try {
      for (final entry in properties.entries) {
        await Fx.analytics.setUserProperty(entry.key, entry.value);
      }
      Fx.toast.success('User properties set');
    } catch (e) {
      Fx.toast.error('Failed to set user properties: $e');
    }
  }
  
  // Clear user data
  Future<void> clearUserData() async {
    try {
      await Fx.analytics.clearUser();
      Fx.toast.success('User data cleared');
    } catch (e) {
      Fx.toast.error('Failed to clear user data: $e');
    }
  }
}

E-commerce Analytics

class EcommerceAnalyticsService {
  // Track product view
  Future<void> trackProductView(String productId, String productName, double price) async {
    try {
      await Fx.analytics.track('product_view', parameters: {
        'product_id': productId,
        'product_name': productName,
        'price': price,
      });
    } catch (e) {
      Fx.toast.error('Failed to track product view: $e');
    }
  }
  
  // Track add to cart
  Future<void> trackAddToCart(String productId, int quantity, double price) async {
    try {
      await Fx.analytics.track('add_to_cart', parameters: {
        'product_id': productId,
        'quantity': quantity,
        'price': price,
      });
    } catch (e) {
      Fx.toast.error('Failed to track add to cart: $e');
    }
  }
  
  // Track purchase
  Future<void> trackPurchase(String orderId, double totalValue, List<Map<String, dynamic>> items) async {
    try {
      await Fx.analytics.track('purchase', parameters: {
        'order_id': orderId,
        'total_value': totalValue,
        'items': items,
        'currency': 'USD',
      });
    } catch (e) {
      Fx.toast.error('Failed to track purchase: $e');
    }
  }
}

Analytics Configuration

class AnalyticsConfigurationService {
  // Enable/disable analytics
  Future<void> setAnalyticsEnabled(bool enabled) async {
    try {
      await Fx.analytics.setEnabled(enabled);
      Fx.toast.success('Analytics ${enabled ? 'enabled' : 'disabled'}');
    } catch (e) {
      Fx.toast.error('Failed to set analytics state: $e');
    }
  }
  
  // Set analytics collection interval
  Future<void> setCollectionInterval(Duration interval) async {
    try {
      await Fx.analytics.setCollectionInterval(interval);
      Fx.toast.success('Collection interval set');
    } catch (e) {
      Fx.toast.error('Failed to set collection interval: $e');
    }
  }
  
  // Get analytics session ID
  Future<String?> getSessionId() async {
    try {
      return await Fx.analytics.getSessionId();
    } catch (e) {
      Fx.toast.error('Failed to get session ID: $e');
      return null;
    }
  }
}

Features

• Event Tracking: Track custom events with parameters
• Screen Tracking: Monitor screen views and navigation
• User Properties: Set and manage user-specific properties
• Performance Monitoring: Track app performance metrics
• Error Tracking: Monitor and analyze app errors
• E-commerce Tracking: Specialized e-commerce event tracking
• User Management: Set user IDs and clear user data
• Configuration: Configure analytics settings and intervals

API Reference

Methods

• initialize() - Initialize analytics service
• track(String eventName, {Map<String, dynamic>? parameters}) - Track custom event
• trackScreen(String screenName) - Track screen view
• setUserId(String userId) - Set user ID
• setUserProperty(String name, String value) - Set user property
• clearUser() - Clear user data
• setEnabled(bool enabled) - Enable/disable analytics
• setCollectionInterval(Duration interval) - Set collection interval
• getSessionId() - Get current session ID

Event Types

• Custom Events: User-defined events with parameters
• Screen Views: Automatic screen tracking
• User Engagement: User interaction tracking
• Performance: App performance metrics
• Errors: Error and exception tracking
• Conversions: Business conversion tracking

Error Handling

The analytics plugin provides comprehensive error handling:

try {
  await Fx.analytics.track('custom_event', parameters: {'key': 'value'});
} on AnalyticsException catch (e) {
  // Handle specific analytics errors
  switch (e.type) {
    case AnalyticsErrorType.initializationFailed:
      Fx.toast.error('Analytics initialization failed');
      break;
    case AnalyticsErrorType.trackingDisabled:
      Fx.toast.error('Analytics tracking is disabled');
      break;
    case AnalyticsErrorType.invalidParameters:
      Fx.toast.error('Invalid event parameters');
      break;
    default:
      Fx.toast.error('Analytics error: $e');
  }
} catch (e) {
  Fx.toast.error('Unexpected analytics error: $e');
}

Privacy Considerations

• All user data is handled according to privacy policies
• Analytics can be disabled by users
• No sensitive personal information is collected without consent
• Data retention policies are configurable
• GDPR and CCPA compliance features

Platform Support

• iOS: Native iOS analytics integration
• Android: Native Android analytics support
• Web: Web analytics tracking capabilities
• Cross-Platform: Unified API across all platforms

License

This package is licensed under the MIT License. See the LICENSE file for details.