Analytics & Tracking

The fluxy_analytics module provides a standardized event API for tracking user behavior, screen visits, and business conversions.

[GUIDE] Industrial Step-by-Step

1. Installation (via CLI)

Add the analytics module using the Fluxy CLI to maintain architectural integrity.

fluxy module add analytics

2. Managed Boot Sequence

Ensure your main.dart is configured with the mandatory three-step boot sequence.

import 'package:fluxy/fluxy.dart';
import 'core/registry/fluxy_registry.dart'; 

void main() async {
  await Fluxy.init();
  Fluxy.registerRegistry(() => registerFluxyPlugins()); 
  Fluxy.autoRegister(); // Boots analytics dispatcher
  runApp(MyApp());
}

3. Usage (Unified API)

Access the module through the stable Fx.platform gateway.

// Log Custom Event
Fx.platform.analytics.logEvent('purchase', parameters: {
  'item_id': 'premium_pkg',
  'value': 29.99,
});

// Identify User
Fx.platform.analytics.identify('user_123', traits: {
  'email': 'user@email.com',
});

Core Functionality

1. Screen Tracking

Automatically or manually track screen transitions.

@override
void onInit() {
  Fx.platform.analytics.logScreen('DashboardView');
}

2. Reactive Metrics

Exposes reactive signals for analytics health and basic event counts.

Fx(() {
  final count = Fx.platform.analytics.eventCount.value;
  return Fx.text("Tracked Events: $count");
});

The Wrong Way vs. The Right Way

Feature	[WRONG] The Outdated Way	[RIGHT] The Fluxy Standard
Plugin Access	`FluxyPluginEngine.find<FluxyAnalyticsPlugin>()`	`Fx.platform.analytics`
Tracking	Tracking in every widget build	Centralized in `FluxController`
Identify	Identifying on every app launch	Identifying only on Auth change
UI Updates	Re-fetching stats via API	Rebuilding via the `eventCount` signal

Pitfalls & Troubleshooting

1. "Events are not appearing in the dashboard"

The Cause: Not calling Fluxy.init() or missing connectivity.
The Fix: Ensure modules are registered and verify Fx.platform.connectivity.

2. "Duplicate events for a single action"

The Cause: Tracking in a widget's build method.
The Fix: Track inside FluxController methods or onTap callbacks, never in build.

Best Practices

Semantic Naming: Use snake_case for all event names and parameters.
Identify Early: Call identify() as soon as the user's ID is known (from Fx.auth).
GDPR Compliance: Check for user consent (saved in Fx.storage) before initializing tracking.

The Master Analytics Implementation

In a professional application, analytics are orchestrated within FluxController to capture high-value business events alongside state changes. Here is a complex "Conversion Funnel" demonstrating best practices for tracking.

class CheckoutController extends FluxController {
  final cartItems = flux<List<Product>>([]);
  final step = flux(1);

  void onCheckoutStarted() {
    // 1. Log the start of the funnel
    Fx.platform.analytics.logEvent('checkout_started', parameters: {
      'cart_size': cartItems.value.length,
      'total_value': _calculateTotal(),
    });
  }

  Future<void> completePurchase() async {
    try {
      // 2. Perform the business logic
      await Fx.http.post('/api/purchase', body: {'items': cartItems.value});
      
      // 3. Log a high-value conversion event
      Fx.platform.analytics.logEvent('purchase_complete', parameters: {
        'transaction_id': 'TXN_${DateTime.now().millisecondsSinceEpoch}',
        'currency': 'USD',
        'value': _calculateTotal(),
      });
      
      Fx.toast.success("Order Placed!");
      Fx.toNamed('/success');
    } catch (e) {
      // 4. Log the failure for funnel drop-off analysis
      Fx.platform.analytics.logEvent('checkout_error', parameters: {
        'error_type': e.toString(),
        'step': step.value,
      });
    }
  }

  double _calculateTotal() => cartItems.value.fold(0.0, (sum, p) => sum + p.price);
}

By centralizing all tracking calls under the Fx.platform.analytics helper, you ensure that your business metrics are consistent and non-intrusive to your UI code.

Analytics & Tracking

On this page