{"id":32297440,"url":"https://github.com/moreirawebmaster/engine-tracking","last_synced_at":"2026-02-22T15:33:30.840Z","repository":{"id":300675376,"uuid":"1006810365","full_name":"moreirawebmaster/engine-tracking","owner":"moreirawebmaster","description":"Uma biblioteca Flutter completa para tracking de analytics e bug reporting, oferecendo integração com Firebase Analytics, Firebase Crashlytics, Microsoft Clarity, Grafana Faro, Splunk e Google Cloud Logging.","archived":false,"fork":false,"pushed_at":"2025-07-26T01:56:34.000Z","size":651,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-23T04:42:57.078Z","etag":null,"topics":["analytics","bugtracking","crashlytics","faro","flutter","flutter-package"],"latest_commit_sha":null,"homepage":"","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/moreirawebmaster.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-23T03:02:26.000Z","updated_at":"2025-07-26T01:53:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"37d118fe-9c83-41f6-87eb-f629b0c7db37","html_url":"https://github.com/moreirawebmaster/engine-tracking","commit_stats":null,"previous_names":["moreirawebmaster/engine-tracking"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/moreirawebmaster/engine-tracking","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moreirawebmaster%2Fengine-tracking","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moreirawebmaster%2Fengine-tracking/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moreirawebmaster%2Fengine-tracking/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moreirawebmaster%2Fengine-tracking/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moreirawebmaster","download_url":"https://codeload.github.com/moreirawebmaster/engine-tracking/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moreirawebmaster%2Fengine-tracking/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29717336,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-22T15:10:41.462Z","status":"ssl_error","status_checked_at":"2026-02-22T15:10:04.636Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","bugtracking","crashlytics","faro","flutter","flutter-package"],"created_at":"2025-10-23T04:42:53.977Z","updated_at":"2026-02-22T15:33:30.810Z","avatar_url":"https://github.com/moreirawebmaster.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Engine Tracking\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/images/logo.png\" alt=\"Engine Tracking Logo\" width=\"300\" /\u003e\n\u003c/div\u003e\n\n[![pub.dev](https://img.shields.io/pub/v/engine_tracking.svg)](https://pub.dev/packages/engine_tracking)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Flutter](https://img.shields.io/badge/Flutter-3.32.0+-blue.svg)](https://flutter.dev/)\n[![Dart](https://img.shields.io/badge/Dart-3.8.0+-blue.svg)](https://dart.dev/)\n\nA comprehensive Flutter library for analytics tracking and bug reporting with unified integration across multiple services including Firebase Analytics, Firebase Crashlytics, Microsoft Clarity, Grafana Faro, Splunk, and Google Cloud Logging.\n\n**Supported Platforms:** iOS • Android\n\n## Quick Start\n\nAdd to your `pubspec.yaml`:\n\n```yaml\ndependencies:\n  engine_tracking: ^1.5.1\n```\n\nInitialize the library:\n\n```dart\nimport 'package:engine_tracking/engine_tracking.dart';\n\n// Initialize all tracking services\nawait EngineTrackingInitialize.initWithModels(\n  analyticsModel: EngineAnalyticsModel(\n    firebaseAnalyticsConfig: const EngineFirebaseAnalyticsConfig(enabled: true),\n    clarityConfig: const EngineClarityConfig(enabled: true, projectId: 'your-project-id'),\n    // Configure other services as needed\n  ),\n  bugTrackingModel: EngineBugTrackingModel(\n    crashlyticsConfig: const EngineCrashlyticsConfig(enabled: true),\n    // Configure other services as needed\n  ),\n  httpTrackingModel: const EngineHttpTrackingModel(\n    enabled: true,\n    httpTrackingConfig: EngineHttpTrackingConfig(\n      enableRequestLogging: true,\n      enableResponseLogging: true,\n      logName: 'HTTP_TRACKING',\n    ),\n  ),\n);\n\n// Start tracking events\nawait EngineAnalytics.logEvent('app_opened');\n```\n\n## Features\n\n**Analytics Integration**\n- Firebase Analytics for comprehensive user behavior tracking\n- Microsoft Clarity with dual integration (adapter + widget) for session recordings, heatmaps, and custom events\n- Grafana Faro for observability and monitoring\n- Splunk for enterprise logging and analytics\n- Google Cloud Logging for centralized log management\n\n**Bug Tracking \u0026 Monitoring**\n- Firebase Crashlytics for crash reporting\n- Automatic Flutter error handling\n- Custom error tracking with context\n- Structured logging with multiple severity levels\n\n**Developer Experience**\n- Type-safe implementation with full null safety\n- Automatic session ID correlation across all services\n- Flexible service configuration (enable/disable individually)\n- Custom widgets with built-in tracking capabilities\n- HTTP request monitoring\n- Single import entry point\n\n## Architecture\n\nEngine Tracking uses an adapter pattern to provide unified interfaces for multiple analytics and bug tracking services. Each service can be enabled or disabled independently through configuration.\n\n### Session Management\n\n```mermaid\ngraph LR\n    A[App Start] --\u003e B[Generate UUID]\n    B --\u003e C[Session ID]\n    C --\u003e D[Analytics Events]\n    C --\u003e E[Bug Reports]\n    C --\u003e F[Log Entries]\n```\n\nAll tracking events automatically include a unique session ID for correlation across services.\n\n### Analytics Flow\n\n```mermaid\ngraph TD\n    A[Your App] --\u003e B[EngineAnalytics]\n    B --\u003e C[Adapters]\n    C --\u003e D[Firebase Analytics]\n    C --\u003e E[Microsoft Clarity]\n    C --\u003e F[Grafana Faro]\n    C --\u003e G[Splunk]\n    C --\u003e H[Google Cloud Logging]\n```\n\n### Bug Tracking Flow\n\n```mermaid\ngraph TD\n    A[Flutter Errors] --\u003e B[EngineBugTracking]\n    A2[Custom Errors] --\u003e B\n    B --\u003e C[Adapters]\n    C --\u003e D[Firebase Crashlytics]\n    C --\u003e E[Grafana Faro]\n    C --\u003e F[Google Cloud Logging]\n```\n\n### EngineLog - Unified Logging System\n\n`EngineLog` is the central logging system that automatically abstracts and unifies calls to both Analytics and Bug Tracking services. It's the recommended way to log events as it handles service routing automatically.\n\n```mermaid\ngraph TD\n    A[Your App] --\u003e B[EngineLog]\n    B --\u003e C{Log Level}\n    C --\u003e|debug/info| D[Developer Console]\n    C --\u003e|warning/error/fatal| E[Developer Console + Services]\n    E --\u003e F[EngineAnalytics]\n    E --\u003e G[EngineBugTracking]\n    F --\u003e H[All Analytics Services]\n    G --\u003e I[All Bug Tracking Services]\n```\n\n**Key Benefits:**\n- **Single API**: One method call routes to multiple services\n- **Automatic Service Detection**: Only calls enabled services\n- **Level-based Routing**: Different log levels go to appropriate services\n- **Context Preservation**: Maintains session ID and metadata across all services\n- **Performance Optimized**: No-op when services are disabled\n\n### Widget Tracking System\n\nEngine Tracking provides custom widgets that automatically track user interactions and screen lifecycle events.\n\n```mermaid\ngraph TD\n    A[EngineStatelessWidget] --\u003e B[buildWithTracking]\n    C[EngineStatefulWidget] --\u003e D[buildWithTracking]\n    B --\u003e E[Automatic Screen Tracking]\n    D --\u003e E\n    E --\u003e F[screen_initialized]\n    E --\u003e G[screen_viewed]\n    E --\u003e H[screen_disposed]\n    \n    I[User Actions] --\u003e J[logUserAction]\n    K[State Changes] --\u003e L[logStateChange]\n    M[Custom Events] --\u003e N[logCustomEvent]\n    \n    J --\u003e O[EngineLog]\n    L --\u003e O\n    N --\u003e O\n```\n\n### Navigation Observer\n\nAutomatic navigation tracking with `EngineNavigationObserver`:\n\n```mermaid\ngraph LR\n    A[Navigator] --\u003e B[EngineNavigationObserver]\n    B --\u003e C[Route Changes]\n    C --\u003e D[EngineAnalytics.setPage]\n    D --\u003e E[All Analytics Services]\n```\n\n### HTTP Tracking System\n\nEngine Tracking provides comprehensive HTTP request/response logging through `EngineHttpOverride` and `EngineHttpTracking` using a model-based configuration approach.\n\n```mermaid\ngraph TD\n    A[HTTP Requests] --\u003e B[EngineHttpOverride]\n    B --\u003e C[Request Logging]\n    B --\u003e D[Response Logging]\n    B --\u003e E[Error Logging]\n    C --\u003e F[EngineLog.debug]\n    D --\u003e F\n    E --\u003e G[EngineLog.error]\n    F --\u003e H[All Tracking Services]\n    G --\u003e H\n```\n\n**Key Features:**\n- **Model-based Configuration**: Uses `EngineHttpTrackingModel` following the same pattern as analytics and bug tracking\n- **Automatic HTTP Logging**: Intercepts all HTTP requests/responses\n- **Configurable Logging**: Control what gets logged (headers, body, timing)\n- **Error Tracking**: Automatic error logging for failed requests\n- **Performance Metrics**: Request timing and performance data\n- **Chain-friendly**: Works with existing HttpOverrides (like FaroHttpOverrides)\n- **Unified Initialization**: Integrates with `EngineTrackingInitialize.initWithModels()`\n\n**Model-based Configuration:**\n```dart\n// Development model (verbose logging)\nconst EngineHttpTrackingModel(\n  enabled: true,\n  httpTrackingConfig: EngineHttpTrackingConfig(\n    enableRequestLogging: true,\n    enableResponseLogging: true,\n    enableTimingLogging: true,\n    enableHeaderLogging: true,\n    enableBodyLogging: true,\n    maxBodyLogLength: 2000,\n    logName: 'HTTP_TRACKING_DEV',\n  ),\n)\n\n// Production model (minimal logging)\nconst EngineHttpTrackingModel(\n  enabled: true,\n  httpTrackingConfig: EngineHttpTrackingConfig(\n    enableRequestLogging: true,\n    enableResponseLogging: true,\n    enableTimingLogging: true,\n    enableHeaderLogging: false, // Be careful with sensitive data\n    enableBodyLogging: false,   // Be careful with sensitive data\n    maxBodyLogLength: 500,\n    logName: 'HTTP_TRACKING_PROD',\n  ),\n)\n\n// Disabled model\nconst EngineHttpTrackingModelDefault() // All tracking disabled\n```\n\n## Installation\n\nAdd to your `pubspec.yaml`:\n\n```yaml\ndependencies:\n  engine_tracking: ^1.5.1\n```\n\nRun:\n\n```bash\nflutter pub get\n```\n\n## Usage Examples\n\n### Complete Examples\n\nThe package includes complete examples demonstrating all functionality:\n\n```bash\ncd example \u0026\u0026 flutter run\n```\n\nAvailable examples:\n- **Main Example**: Initialization, event tracking, user properties, and navigation\n- **HTTP Tracking**: Requests with PokéAPI and JSONPlaceholder\n- **View Tracking**: Automatic screen tracking system\n\n### Centralized Initialization (Recommended)\n\nUse `EngineTrackingInitialize` to initialize both Analytics and Bug Tracking:\n\n```dart\nimport 'package:engine_tracking/engine_tracking.dart';\n\n// All services\nawait EngineTrackingInitialize.initWithModels(\n  analyticsModel: EngineAnalyticsModel(/* configs */),\n  bugTrackingModel: EngineBugTrackingModel(/* configs */),\n  httpTrackingModel: EngineHttpTrackingModel(/* config */),\n);\n\n// Analytics and HTTP tracking only\nawait EngineTrackingInitialize.initWithModels(\n  analyticsModel: EngineAnalyticsModel(/* configs */),\n  bugTrackingModel: null,\n  httpTrackingModel: EngineHttpTrackingModel(/* config */),\n);\n\n// Bug tracking only\nawait EngineTrackingInitialize.initWithModels(\n  analyticsModel: null,\n  bugTrackingModel: EngineBugTrackingModel(/* configs */),\n  httpTrackingModel: null,\n);\n\n// With adapters (granular control)\nawait EngineTrackingInitialize.initWithAdapters(\n  analyticsAdapters: [EngineFirebaseAnalyticsAdapter(/* config */)],\n  bugTrackingAdapters: null, // Skip bug tracking\n);\n\n// Quick initialization (both disabled)\nawait EngineTrackingInitialize.initWithDefaults();\n\n// Status\nbool bothReady = EngineTrackingInitialize.isInitialized;\nbool anyEnabled = EngineTrackingInitialize.isEnabled;\n\n// Cleanup\nawait EngineTrackingInitialize.dispose();\n```\n\n### Microsoft Clarity Integration\n\nEngine Tracking provides two ways to integrate with Microsoft Clarity:\n\n#### 1. Adapter-based Integration (Recommended)\n\nThe `EngineClarityAdapter` integrates Clarity into the unified analytics system:\n\n```dart\nfinal analyticsModel = EngineAnalyticsModel(\n  clarityConfig: const EngineClarityConfig(\n    enabled: true,\n    projectId: 'your-clarity-project-id',\n  ),\n  // ... other configs\n);\n\nawait EngineAnalytics.initWithModel(analyticsModel);\n\n// All analytics calls now include Clarity\nawait EngineAnalytics.logEvent('user_action');\nawait EngineAnalytics.setUserId('user_123');\nawait EngineAnalytics.setPage('home_screen');\n```\n\n#### 2. Widget-based Integration (For Session Recordings)\n\nUse `EngineWidget` to automatically enable session recordings and heatmaps. The widget automatically detects if Clarity has been initialized through the analytics system - no manual configuration required:\n\n```dart\nvoid main() async {\n  WidgetsFlutterBinding.ensureInitialized();\n  \n  // Initialize analytics with Clarity configuration\n  final analyticsModel = EngineAnalyticsModel(\n    clarityConfig: EngineClarityConfig(\n      enabled: true,\n      projectId: 'your-clarity-project-id',\n    ),\n    // ... other configurations\n  );\n  \n  await EngineAnalytics.initWithModel(analyticsModel);\n  \n  // EngineWidget automatically detects and uses Clarity configuration\n  // No need to pass clarityConfig manually!\n  runApp(EngineWidget(app: MyApp()));\n}\n```\n\n#### Combined Usage (Best Practice)\n\nFor complete Clarity integration, initialize analytics and use EngineWidget:\n\n```dart\nvoid main() async {\n  WidgetsFlutterBinding.ensureInitialized();\n  \n  final clarityConfig = EngineClarityConfig(\n    enabled: true,\n    projectId: 'your-clarity-project-id',\n  );\n  \n  // Initialize analytics with Clarity adapter\n  await EngineAnalytics.initWithModel(\n    EngineAnalyticsModel(\n      clarityConfig: clarityConfig,\n      // ... other configs\n    ),\n  );\n  \n  // EngineWidget automatically detects Clarity configuration\n  // No manual configuration needed!\n  runApp(EngineWidget(app: MyApp()));\n}\n```\n\n### Individual Service Configuration\n\n```dart\nimport 'package:engine_tracking/engine_tracking.dart';\n\nFuture\u003cvoid\u003e setupTracking() async {\n  final analyticsModel = EngineAnalyticsModel(\n    firebaseAnalyticsConfig: const EngineFirebaseAnalyticsConfig(enabled: true),\n    clarityConfig: const EngineClarityConfig(\n      enabled: true,\n      projectId: 'your-clarity-project-id',\n    ),\n    faroConfig: const EngineFaroConfig(\n      enabled: true,\n      endpoint: 'https://faro-collector.grafana.net/collect',\n      appName: 'YourApp',\n      appVersion: '1.0.0',\n      environment: 'production',\n      apiKey: 'your-faro-api-key',\n    ),\n    googleLoggingConfig: const EngineGoogleLoggingConfig(\n      enabled: true,\n      projectId: 'your-gcp-project',\n      logName: 'engine-tracking',\n      credentials: {\n        \"type\": \"service_account\",\n        \"project_id\": \"your-gcp-project\",\n        \"private_key_id\": \"...\",\n        \"private_key\": \"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n\",\n        \"client_email\": \"your-service-account@your-gcp-project.iam.gserviceaccount.com\",\n        // ... rest of credentials\n      },\n      resource: {\n        'type': 'global',\n        'labels': {'project_id': 'your-gcp-project'},\n      },\n    ),\n    splunkConfig: const EngineSplunkConfig(enabled: false),\n  );\n\n  final bugTrackingModel = EngineBugTrackingModel(\n    crashlyticsConfig: const EngineCrashlyticsConfig(enabled: true),\n    faroConfig: const EngineFaroConfig(\n      enabled: true,\n      endpoint: 'https://faro-collector.grafana.net/collect',\n      appName: 'YourApp',\n      appVersion: '1.0.0',\n      environment: 'production',\n      apiKey: 'your-faro-api-key',\n    ),\n    googleLoggingConfig: const EngineGoogleLoggingConfig(enabled: true, /* configs */),\n  );\n\n  await EngineAnalytics.initWithModel(analyticsModel);\n  await EngineBugTracking.initWithModel(bugTrackingModel);\n}\n```\n\n### Event Tracking\n\n```dart\n// Simple event (Session ID included automatically)\nawait EngineAnalytics.logEvent('button_clicked');\n\n// Event with parameters\nawait EngineAnalytics.logEvent('purchase_completed', {\n  'item_id': 'premium_plan',\n  'value': 29.99,\n  'currency': 'USD',\n  'category': 'subscription',\n});\n\n// App open event\nawait EngineAnalytics.logAppOpen();\n```\n\n### User Management\n\n```dart\n// Set user ID\nawait EngineAnalytics.setUserId('user_12345');\n\n// With complete information (for Faro/Clarity)\nawait EngineAnalytics.setUserId(\n  'user_12345',\n  'user@example.com',\n  'John Doe',\n);\n\n// User properties\nawait EngineAnalytics.setUserProperty('user_type', 'premium');\nawait EngineAnalytics.setUserProperty('plan', 'monthly');\n```\n\n### Screen Navigation\n\n```dart\n// Simple screen\nawait EngineAnalytics.setPage('HomeScreen');\n\n// With complete context\nawait EngineAnalytics.setPage(\n  'ProductScreen',      // Current screen\n  'HomeScreen',        // Previous screen\n  'ECommerceApp',      // Screen class\n);\n```\n\n### Bug Tracking\n\n```dart\n// Structured logging\nawait EngineBugTracking.log('User completed purchase', {\n  'user_id': '12345',\n  'product_id': 'abc-123',\n  'amount': 29.99,\n});\n\n// Capture errors\ntry {\n  // code that might fail\n} catch (error, stackTrace) {\n  await EngineBugTracking.recordError(\n    error,\n    stackTrace,\n    reason: 'Payment processing failure',\n  );\n}\n\n// Set user context\nawait EngineBugTracking.setUserIdentifier('user_12345', 'user@example.com', 'John Doe');\nawait EngineBugTracking.setCustomKey('subscription_plan', 'premium');\n```\n\n### Logging System\n\n```dart\n// Different log levels\nawait EngineLog.debug('Debug information');\nawait EngineLog.info('Informational message');\nawait EngineLog.warning('Warning message');\nawait EngineLog.error('Error occurred');\nawait EngineLog.fatal('Fatal error');\n\n// With additional data\nawait EngineLog.info('User action', data: {\n  'action': 'button_click',\n  'screen': 'home',\n  'user_id': '12345',\n});\n\n// Custom log name and include in analytics\nawait EngineLog.warning('Important warning', \n  logName: 'USER_ACTION',\n  includeInAnalytics: true,\n);\n\n// Error logging with exception and stack trace\ntry {\n  // risky operation\n} catch (error, stackTrace) {\n  await EngineLog.error('Operation failed',\n    error: error,\n    stackTrace: stackTrace,\n    data: {'operation': 'user_registration'},\n  );\n}\n\n// Fatal error with complete context\nawait EngineLog.fatal('Critical system failure',\n  logName: 'SYSTEM',\n  error: exception,\n  stackTrace: stackTrace,\n  data: {\n    'component': 'payment_processor',\n    'user_id': 'user_123',\n    'transaction_id': 'tx_456',\n  },\n);\n```\n\n### View Tracking with Widgets\n\n```dart\nclass HomePage extends EngineStatelessWidget {\n  HomePage({super.key});\n\n  @override\n  String get screenName =\u003e 'home';\n\n  @override\n  Map\u003cString, dynamic\u003e? get screenParameters =\u003e {\n    'user_type': 'premium',\n    'version': '1.0.0',\n  };\n\n  @override\n  Widget buildWithTracking(BuildContext context) {\n    return Scaffold(\n      appBar: AppBar(title: const Text('Home')),\n      body: ElevatedButton(\n        onPressed: () {\n          logUserAction('cta_clicked', parameters: {\n            'button_type': 'primary',\n            'location': 'header',\n          });\n        },\n        child: const Text('Click Me'),\n      ),\n    );\n  }\n}\n```\n\n```dart\nclass ShoppingCartPage extends StatefulWidget {\n  final List\u003cProduct\u003e initialProducts;\n  \n  const ShoppingCartPage({super.key, required this.initialProducts});\n\n  @override\n  State\u003cShoppingCartPage\u003e createState() =\u003e _ShoppingCartPageState();\n}\n\nclass _ShoppingCartPageState extends EngineStatefulWidgetState\u003cShoppingCartPage\u003e {\n  \n  late List\u003cProduct\u003e _products;\n  \n  @override\n  void initState() {\n    super.initState();\n    _products = List.from(widget.initialProducts);\n  }\n  \n  @override\n  String get screenName =\u003e 'shopping_cart';\n\n  @override\n  Map\u003cString, dynamic\u003e? get screenParameters =\u003e {\n    'initial_product_count': widget.initialProducts.length,\n    'cart_value': _calculateTotal(),\n  };\n\n  @override\n  Widget buildWithTracking(BuildContext context) {\n    return Scaffold(\n      appBar: AppBar(title: const Text('Shopping Cart')),\n      body: ListView.builder(\n        itemCount: _products.length,\n        itemBuilder: (context, index) {\n          final product = _products[index];\n          return ListTile(\n            title: Text(product.name),\n            trailing: IconButton(\n              icon: const Icon(Icons.remove_circle),\n              onPressed: () {\n                setState(() {\n                  _products.removeAt(index);\n                });\n                \n                logUserAction('product_removed', parameters: {\n                  'product_id': product.id,\n                  'product_name': product.name,\n                  'remaining_count': _products.length,\n                });\n                \n                logStateChange('cart_updated', additionalData: {\n                  'action': 'removal',\n                  'new_total': _calculateTotal(),\n                });\n              },\n            ),\n          );\n        },\n      ),\n      floatingActionButton: FloatingActionButton(\n        onPressed: () {\n          logUserAction('checkout_initiated', parameters: {\n            'product_count': _products.length,\n            'total_value': _calculateTotal(),\n          });\n        },\n        child: const Icon(Icons.shopping_cart_checkout),\n      ),\n    );\n  }\n  \n  double _calculateTotal() {\n    return _products.fold(0.0, (sum, product) =\u003e sum + product.price);\n  }\n}\n```\n\n### Custom Widgets\n\nEngine Tracking provides several specialized widgets for enhanced tracking capabilities:\n\n#### EngineWidget - Root App Wrapper\n\nAutomatically wraps your app to enable Microsoft Clarity session recordings when Clarity is initialized. The widget intelligently detects if Clarity has been configured through the analytics system and automatically enables session recordings without requiring manual configuration:\n\n```dart\nvoid main() async {\n  WidgetsFlutterBinding.ensureInitialized();\n  \n  // Initialize analytics with Clarity configuration\n  await EngineAnalytics.initWithModel(\n    EngineAnalyticsModel(\n      clarityConfig: EngineClarityConfig(\n        enabled: true,\n        projectId: 'your-clarity-project-id',\n      ),\n      firebaseAnalyticsConfig: const EngineFirebaseAnalyticsConfig(enabled: true),\n      // ... other configs\n    ),\n  );\n\n  // EngineWidget automatically detects and enables Clarity session recordings\n  // No manual clarityConfig parameter needed!\n  runApp(EngineWidget(app: MyApp()));\n}\n\nclass MyApp extends StatelessWidget {\n  @override\n  Widget build(BuildContext context) {\n    return MaterialApp(\n      home: HomePage(),\n      navigatorObservers: [EngineNavigationObserver()],\n    );\n  }\n}\n\nclass HomePage extends StatelessWidget {\n  @override\n  Widget build(BuildContext context) {\n    return Scaffold(\n      body: Column(\n        children: [\n          ElevatedButton(\n            onPressed: () async {\n              // This event goes to all analytics services including Clarity\n              await EngineAnalytics.logEvent('button_clicked', {\n                'button_type': 'primary',\n                'screen': 'home',\n              });\n            },\n            child: Text('Track Event'),\n          ),\n          \n          // Mask sensitive content in Clarity recordings\n          EngineMaskWidget(\n            child: Text('Sensitive user data'),\n          ),\n        ],\n      ),\n    );\n  }\n}\n```\n\n#### EngineMaskWidget - Privacy Protection\n\nMasks sensitive content in session recordings:\n\n```dart\nclass PaymentScreen extends StatelessWidget {\n  @override\n  Widget build(BuildContext context) {\n    return Scaffold(\n      body: Column(\n        children: [\n          Text('Order Summary'),\n          \n          // Mask sensitive payment information\n          EngineMaskWidget(\n            child: Column(\n              children: [\n                Text('Credit Card: **** **** **** 1234'),\n                Text('CVV: 123'),\n                \n                // Unmask non-sensitive info within masked area\n                EngineUnmaskWidget(\n                  child: Text('Expires: 12/25'),\n                ),\n              ],\n            ),\n          ),\n          \n          ElevatedButton(\n            onPressed: () =\u003e processPayment(),\n            child: Text('Pay Now'),\n          ),\n        ],\n      ),\n    );\n  }\n}\n```\n\n#### EngineStatelessWidget - Enhanced Stateless Widgets\n\nProvides automatic screen tracking and user action logging:\n\n```dart\nclass ProductListPage extends EngineStatelessWidget {\n  ProductListPage({super.key});\n\n  @override\n  String get screenName =\u003e 'product_list';\n\n  @override\n  Map\u003cString, dynamic\u003e? get screenParameters =\u003e {\n    'category': 'electronics',\n    'sort_by': 'price',\n  };\n\n  @override\n  Widget buildWithTracking(BuildContext context) {\n    return Scaffold(\n      appBar: AppBar(title: Text('Products')),\n      body: ListView.builder(\n        itemBuilder: (context, index) {\n          return ListTile(\n            title: Text('Product $index'),\n            onTap: () {\n              // Automatically tracked user action\n              logUserAction('product_selected', parameters: {\n                'product_id': index,\n                'product_name': 'Product $index',\n              });\n              \n              // Navigate to product details\n              Navigator.push(context, \n                MaterialPageRoute(builder: (_) =\u003e ProductDetailPage()));\n            },\n          );\n        },\n      ),\n      floatingActionButton: FloatingActionButton(\n        onPressed: () {\n          // Log custom events\n          logCustomEvent('filter_opened');\n        },\n        child: Icon(Icons.filter_list),\n      ),\n    );\n  }\n}\n```\n\n#### EngineStatefulWidget - Enhanced Stateful Widgets\n\nIncludes state change tracking in addition to all EngineStatelessWidget features:\n\n```dart\nclass ShoppingCartPage extends StatefulWidget {\n  @override\n  State\u003cShoppingCartPage\u003e createState() =\u003e _ShoppingCartPageState();\n}\n\nclass _ShoppingCartPageState extends EngineStatefulWidgetState\u003cShoppingCartPage\u003e {\n  List\u003cCartItem\u003e _items = [];\n  \n  @override\n  String get screenName =\u003e 'shopping_cart';\n\n  @override\n  Map\u003cString, dynamic\u003e? get screenParameters =\u003e {\n    'initial_item_count': _items.length,\n    'cart_value': _calculateTotal(),\n  };\n\n  @override\n  Widget buildWithTracking(BuildContext context) {\n    return Scaffold(\n      appBar: AppBar(title: Text('Shopping Cart')),\n      body: ListView.builder(\n        itemCount: _items.length,\n        itemBuilder: (context, index) {\n          return ListTile(\n            title: Text(_items[index].name),\n            trailing: IconButton(\n              icon: Icon(Icons.remove),\n              onPressed: () =\u003e _removeItem(index),\n            ),\n          );\n        },\n      ),\n    );\n  }\n  \n  void _removeItem(int index) {\n    final removedItem = _items[index];\n    \n    setState(() {\n      _items.removeAt(index);\n    });\n    \n    // Track user action\n    logUserAction('item_removed', parameters: {\n      'item_id': removedItem.id,\n      'remaining_items': _items.length,\n    });\n    \n    // Track state change\n    logStateChange('cart_updated', additionalData: {\n      'action': 'item_removal',\n      'new_total': _calculateTotal(),\n    });\n  }\n  \n  double _calculateTotal() {\n    return _items.fold(0.0, (sum, item) =\u003e sum + item.price);\n  }\n}\n```\n\n### Navigation Observer\n\nAutomatic navigation tracking with `EngineNavigationObserver`:\n\n```dart\nclass MyApp extends StatelessWidget {\n  @override\n  Widget build(BuildContext context) {\n    return MaterialApp(\n      title: 'My App',\n      // Add the navigation observer for automatic screen tracking\n      navigatorObservers: [\n        EngineNavigationObserver(),\n      ],\n      home: HomePage(),\n      routes: {\n        '/products': (context) =\u003e ProductListPage(),\n        '/cart': (context) =\u003e ShoppingCartPage(),\n        '/profile': (context) =\u003e ProfilePage(),\n      },\n    );\n  }\n}\n```\n\nThe `EngineNavigationObserver` automatically:\n- Tracks route changes and screen transitions\n- Calls `EngineAnalytics.setPage()` with screen names\n- Provides navigation context for analytics\n- Works seamlessly with both named routes and direct navigation\n\n### HTTP Request Tracking\n\nEngine Tracking provides comprehensive HTTP request/response logging using a model-based approach:\n\n```dart\nimport 'package:engine_tracking/engine_tracking.dart';\nimport 'package:http/http.dart' as http;\n\nvoid main() async {\n  // Initialize Engine Tracking with HTTP tracking model\n  await EngineTrackingInitialize.initWithModels(\n    analyticsModel: myAnalyticsModel,\n    bugTrackingModel: myBugTrackingModel,\n    // Add HTTP tracking model\n    httpTrackingModel: const EngineHttpTrackingModel(\n      enabled: true,\n      httpTrackingConfig: EngineHttpTrackingConfig(\n        enableRequestLogging: true,\n        enableResponseLogging: true,\n        enableTimingLogging: true,\n        enableHeaderLogging: true,\n        enableBodyLogging: true,\n        maxBodyLogLength: 2000,\n        logName: 'HTTP_TRACKING_DEV',\n      ),\n    ),\n  );\n  \n  runApp(MyApp());\n}\n\n// HTTP requests are now automatically logged\nclass ApiService {\n  Future\u003cUser\u003e getUser(String userId) async {\n    // This request will be automatically logged with:\n    // - Request details (method, URL, headers, timing)\n    // - Response details (status, headers, timing)\n    // - Error details (if request fails)\n    final response = await http.get(\n      Uri.parse('https://api.example.com/users/$userId'),\n      headers: {'Authorization': 'Bearer $token'},\n    );\n    \n    if (response.statusCode == 200) {\n      return User.fromJson(json.decode(response.body));\n    } else {\n      throw ApiException('Failed to load user');\n    }\n  }\n  \n  Future\u003cvoid\u003e updateUser(User user) async {\n    // POST requests are also automatically tracked\n    final response = await http.post(\n      Uri.parse('https://api.example.com/users/${user.id}'),\n      headers: {\n        'Content-Type': 'application/json',\n        'Authorization': 'Bearer $token',\n      },\n      body: json.encode(user.toJson()),\n    );\n    \n    if (response.statusCode != 200) {\n      throw ApiException('Failed to update user');\n    }\n  }\n}\n```\n\n**Model Configuration Examples:**\n\n```dart\n// Development model: Full logging with headers and body\nconst devModel = EngineHttpTrackingModel(\n  enabled: true,\n  httpTrackingConfig: EngineHttpTrackingConfig(\n    enableRequestLogging: true,\n    enableResponseLogging: true,\n    enableTimingLogging: true,\n    enableHeaderLogging: true,\n    enableBodyLogging: true,\n    maxBodyLogLength: 2000,\n    logName: 'API_DEV',\n  ),\n);\n\n// Production model: Minimal logging, no sensitive data\nconst prodModel = EngineHttpTrackingModel(\n  enabled: true,\n  httpTrackingConfig: EngineHttpTrackingConfig(\n    enableRequestLogging: true,\n    enableResponseLogging: true,\n    enableTimingLogging: true,\n    enableHeaderLogging: false, // Disable for security\n    enableBodyLogging: false,   // Disable for security\n    maxBodyLogLength: 500,\n    logName: 'API_PROD',\n  ),\n);\n\n// Disabled model\nconst disabledModel = EngineHttpTrackingModelDefault();\n```\n\n**Advanced Usage:**\n\n```dart\n// Initialize directly with model\nEngineHttpTracking.initWithModel(devModel);\n\n// Update model at runtime\nEngineHttpTracking.updateModel(prodModel);\n\n// Update model at runtime\nEngineHttpTracking.updateModel(prodModel);\n\n// Log custom HTTP-related events\nawait EngineHttpTracking.logCustomEvent(\n  'API rate limit reached',\n  data: {\n    'endpoint': '/api/users',\n    'retry_after': 60,\n    'request_count': 100,\n  },\n);\n\n// Get HTTP tracking statistics\nfinal stats = EngineHttpTracking.getStats();\nprint('HTTP Tracking enabled: ${stats['is_enabled']}');\n```\n\n**Backward Compatibility:**\n\n```dart\n// Legacy configuration method (deprecated but still supported)\n@Deprecated('Use EngineHttpTrackingModel instead')\nEngineHttpTracking.initialize(config);\n```\n\n### Status Verification\n\n```dart\n// Check if analytics is enabled\nif (EngineAnalytics.isEnabled) {\n  print('✅ Analytics is active');\n}\n\n// Check specific services\nif (EngineAnalytics.isFirebaseInitialized) {\n  print('🔥 Firebase Analytics active');\n}\n\nif (EngineAnalytics.isClarityInitialized) {\n  print('👁️ Microsoft Clarity active');\n}\n\nif (EngineAnalytics.isFaroInitialized) {\n  print('📊 Grafana Faro active');\n}\n\nif (EngineAnalytics.isSplunkInitialized) {\n  print('🔍 Splunk active');\n}\n\nif (EngineAnalytics.isGoogleLoggingInitialized) {\n  print('☁️ Google Cloud Logging active');\n}\n```\n\n---\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the project\n2. Create a feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n### Contribution Guidelines\n\n- Follow existing code patterns\n- Document new features\n- Test on both Android and iOS\n- Update the CHANGELOG.md\n\n### License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n---\n\n## About STMR\n\nDeveloped by **STMR** - Mobile solutions specialists.\n\nSTMR is a company focused on developing innovative technology solutions for mobile devices, specializing in robust architectures, optimized performance, and exceptional user experiences.\n\n### Our Mission\nTo provide high-quality Flutter tools and libraries that accelerate enterprise mobile application development while maintaining the highest standards of security, performance, and usability.\n\n---\n\n**Tip**: For maximum efficiency, configure only the services you actually use. The library is optimized to work with any combination of enabled or disabled services. With automatic Session ID, you now have complete log correlation and advanced centralization!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoreirawebmaster%2Fengine-tracking","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoreirawebmaster%2Fengine-tracking","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoreirawebmaster%2Fengine-tracking/lists"}