Develop

CHANGELOG.md

@@ -1,3 +1,51 @@
+## 2.0.0
+
+### Breaking changes
+
+`BaseEvent.getName()` and `BaseEvent.getProperties()` have been removed. Event implementations must now override the `name` and `properties` getters.
+
+Before:
+
+```dart
+class PurchaseEvent extends BaseEvent {
+  @override
+  String getName() => 'purchase';
+
+  @override
+  Map<String, Object>? getProperties() => {'amount': 29.99};
+}
+```
+
+After:
+
+```dart
+class PurchaseEvent extends BaseEvent {
+  @override
+  String get name => 'purchase';
+
+  @override
+  Map<String, Object>? get properties => {'amount': 29.99};
+}
+```
+
+### Added
+
+* Add an `EventTransformer` pipeline for enriching and normalizing events before routing and dispatch.
+* Add `EnrichedEvent` for layering additional properties onto an event while preserving its routing, consent, and privacy metadata.
+* Add support for custom event categories and subcategories.
+* Add the interactive FlexTrack guide at [flextrack.taghizadeh.dev](https://flextrack.taghizadeh.dev/).
+
+### Changed
+
+* Replace `BaseEvent.getName()` and `BaseEvent.getProperties()` with the `BaseEvent.name` and `BaseEvent.properties` getter API.
+* Update examples, tests, and documentation to use the getter API.
+
+### Fixed
+
+* Align transformer signatures around `BaseEvent` so transformed events flow consistently through clients, widgets, routing, and trackers.
+
+---
+
 ## 1.0.1
 
 * Improve package presentation and pub.dev listing metadata.

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 [Reza Taghizadeh]
+Copyright (c) 2025-2026 Reza Taghizadeh
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

README.md

@@ -8,7 +8,7 @@ Multi-tracker analytics orchestration for Flutter: route events, enforce consent
 [![CI](https://github.com/alirezat66/flex_track/actions/workflows/ci.yml/badge.svg)](https://github.com/alirezat66/flex_track/actions)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/alirezat66/flex_track/blob/main/LICENSE)
 
-**Settings → Pages** to that branch if the site is not live yet). API reference: [pub.dev documentation](https://pub.dev/documentation/flex_track/latest/).
+[Interactive guide](https://flextrack.taghizadeh.dev/) · [API reference](https://pub.dev/documentation/flex_track/latest/)
 
 ---
 
@@ -52,6 +52,10 @@ One call site, multiple tracker destinations, centralized policy.
 ## Table of contents
 
 - [FlexTrack](#flextrack)
+  - [The Problem](#the-problem)
+  - [The Solution](#the-solution)
+  - [Visual Demo](#visual-demo)
+  - [Quick Example](#quick-example)
   - [Table of contents](#table-of-contents)
   - [Quick start](#quick-start)
   - [Compare with the usual approach](#compare-with-the-usual-approach)
@@ -66,6 +70,7 @@ One call site, multiple tracker destinations, centralized policy.
   - [Creating events](#creating-events)
     - [Event flags](#event-flags)
     - [EventCategory values](#eventcategory-values)
+    - [Custom categories](#custom-categories)
   - [Event transformers](#event-transformers)
     - [App-wide context (setup once)](#app-wide-context-setup-once)
     - [Dynamic values (evaluated at dispatch time)](#dynamic-values-evaluated-at-dispatch-time)
@@ -130,8 +135,8 @@ class FirebaseTracker extends BaseTrackerStrategy {
   @override
   Future<void> doTrack(BaseEvent event) async {
     await FirebaseAnalytics.instance.logEvent(
-      name: event.getName(),
-      parameters: event.getProperties(),
+      name: event.name,
+      parameters: event.properties,
     );
   }
 }
@@ -308,18 +313,18 @@ This package does not bundle Firebase, Mixpanel, Amplitude, or any other analyti
 
 ## Creating events
 
-Extend `BaseEvent` and implement `getName()` and `getProperties()`. Everything else is optional.
+Extend `BaseEvent` and implement the `name` and `properties` getters. Everything else is optional.
 
 ```dart
 class PurchaseEvent extends BaseEvent {
   final double amount;
   PurchaseEvent({required this.amount});
 
   @override
-  String getName() => 'purchase';
+  String get name => 'purchase';
 
   @override
-  Map<String, Object> getProperties() => {'amount': amount};
+  Map<String, Object> get properties => {'amount': amount};
 
   @override
   EventCategory get category => EventCategory.business;
@@ -467,7 +472,7 @@ FlexTrack.addTransformer((event) => EnrichedEvent(event, {
 
 ### EnrichedEvent
 
-`EnrichedEvent` is a `BaseEvent` wrapper. It forwards all metadata from the original event (`category`, `containsPII`, `requiresConsent`, etc.) and overrides `getProperties()` to merge the original properties with the extra ones. Extra properties win on key collision.
+`EnrichedEvent` is a `BaseEvent` wrapper. It forwards all metadata from the original event (`category`, `containsPII`, `requiresConsent`, etc.) and overrides `properties` to merge the original properties with the extra ones. Extra properties win on key collision.
 
 ```dart
 // Extra properties override originals on the same key.
@@ -523,8 +528,8 @@ class MyTracker extends BaseTrackerStrategy {
   @override
   Future<void> doTrack(BaseEvent event) async {
     // Called for each routed event.
-    // event.getName()       → String
-    // event.getProperties() → Map<String, Object>
+    // event.name       → String
+    // event.properties → Map<String, Object>
     // event.category        → EventCategory?
   }
 }
@@ -556,8 +561,8 @@ class FirebaseTracker extends BaseTrackerStrategy {
   @override
   Future<void> doTrack(BaseEvent event) async {
     await FirebaseAnalytics.instance.logEvent(
-      name: event.getName(),
-      parameters: event.getProperties(),
+      name: event.name,
+      parameters: event.properties,
     );
   }
 }
@@ -582,7 +587,7 @@ class MixpanelTracker extends BaseTrackerStrategy {
 
   @override
   Future<void> doTrack(BaseEvent event) async {
-    _mixpanel.track(event.getName(), properties: event.getProperties());
+    _mixpanel.track(event.name, properties: event.properties);
   }
 }
 ```
@@ -675,7 +680,7 @@ Rules are evaluated in priority order. The first matching rule wins.
 | `.routePII()` | `event.containsPII == true` |
 | `.routeMatching(RegExp(...))` | event name matches the regex |
 | `.routeNamed('pattern')` | event name contains the substring |
-| `.routeWithProperty('key')` | `getProperties()` contains the key |
+| `.routeWithProperty('key')` | `properties` contains the key |
 | `.routeDefault()` | catch-all (put this last) |
 
 **Full list of targets:**
@@ -1072,8 +1077,8 @@ void main() {
     await FlexTrack.track(PurchaseEvent(amount: 9.99));
 
     expect(mock.capturedEvents, hasLength(1));
-    expect(mock.capturedEvents.single.getName(), 'purchase');
-    expect(mock.capturedEvents.single.getProperties()['amount'], 9.99);
+    expect(mock.capturedEvents.single.name, 'purchase');
+    expect(mock.capturedEvents.single.properties['amount'], 9.99);
   });
 
   test('does not send event without consent', () async {

example/lib/events/app_events.dart

@@ -15,10 +15,10 @@ class AppStartEvent extends BaseEvent {
         platform = platform ?? 'unknown';
 
   @override
-  String getName() => 'app_start';
+  String get name => 'app_start';
 
   @override
-  Map<String, Object> getProperties() => {
+  Map<String, Object> get properties => {
         'app_version': appVersion,
         'build_number': buildNumber,
         'platform': platform,
@@ -49,10 +49,10 @@ class PageViewEvent extends BaseEvent {
   }) : timestamp = timestamp ?? DateTime.now();
 
   @override
-  String getName() => 'page_view';
+  String get name => 'page_view';
 
   @override
-  Map<String, Object> getProperties() => {
+  Map<String, Object> get properties => {
         'page_name': pageName,
         if (parameters != null) 'parameters': parameters!,
         'timestamp': timestamp.millisecondsSinceEpoch,
@@ -78,10 +78,10 @@ class ButtonClickEvent extends BaseEvent {
   });
 
   @override
-  String getName() => 'button_click';
+  String get name => 'button_click';
 
   @override
-  Map<String, Object> getProperties() => {
+  Map<String, Object> get properties => {
         'button_id': buttonId,
         'button_text': buttonText,
         if (screenName != null) 'screen_name': screenName!,
@@ -110,10 +110,10 @@ class ErrorEvent extends BaseEvent {
   });
 
   @override
-  String getName() => 'error';
+  String get name => 'error';
 
   @override
-  Map<String, Object> getProperties() => {
+  Map<String, Object> get properties => {
         'error_type': errorType,
         'error_message': errorMessage,
         if (stackTrace != null) 'stack_trace': stackTrace!,
@@ -146,10 +146,10 @@ class PerformanceEvent extends BaseEvent {
   });
 
   @override
-  String getName() => 'performance_metric';
+  String get name => 'performance_metric';
 
   @override
-  Map<String, Object> getProperties() => {
+  Map<String, Object> get properties => {
         'metric_name': metricName,
         'value': value,
         'unit': unit,

example/lib/events/business_events.dart

@@ -21,10 +21,10 @@ class PurchaseEvent extends BaseEvent {
   });
 
   @override
-  String getName() => 'purchase';
+  String get name => 'purchase';
 
   @override
-  Map<String, Object> getProperties() => {
+  Map<String, Object> get properties => {
         'product_id': productId,
         'product_name': productName,
         'amount': amount,
@@ -62,10 +62,10 @@ class CartAbandonmentEvent extends BaseEvent {
   });
 
   @override
-  String getName() => 'cart_abandonment';
+  String get name => 'cart_abandonment';
 
   @override
-  Map<String, Object> getProperties() => {
+  Map<String, Object> get properties => {
         'product_ids': productIds,
         'total_value': totalValue,
         'currency': currency,
@@ -98,10 +98,10 @@ class AddToCartEvent extends BaseEvent {
   });
 
   @override
-  String getName() => 'add_to_cart';
+  String get name => 'add_to_cart';
 
   @override
-  Map<String, Object> getProperties() => {
+  Map<String, Object> get properties => {
         'product_id': productId,
         'product_name': productName,
         'price': price,
@@ -133,10 +133,10 @@ class SubscriptionEvent extends BaseEvent {
   });
 
   @override
-  String getName() => 'subscription_$action';
+  String get name => 'subscription_$action';
 
   @override
-  Map<String, Object> getProperties() => {
+  Map<String, Object> get properties => {
         'plan_id': planId,
         'plan_name': planName,
         'price': price,

example/lib/events/demo_routing_and_widgets_events.dart

@@ -7,10 +7,10 @@ class DemoBannerImpressionEvent extends BaseEvent {
   final String slotId;
 
   @override
-  String getName() => 'demo_banner_impression';
+  String get name => 'demo_banner_impression';
 
   @override
-  Map<String, Object>? getProperties() => {
+  Map<String, Object>? get properties => {
         'slot_id': slotId,
         'surface': 'home_demo_scroll',
       };
@@ -25,10 +25,10 @@ class DemoBannerImpressionEvent extends BaseEvent {
 /// Routed only to `console` + `firebase` (see [AnalyticsSetup] rules).
 class DemoFreeTierOnlyEvent extends BaseEvent {
   @override
-  String getName() => 'demo_free_tier_only';
+  String get name => 'demo_free_tier_only';
 
   @override
-  Map<String, Object>? getProperties() => const {
+  Map<String, Object>? get properties => const {
         'note': 'premium trackers intentionally excluded',
       };
 
@@ -39,10 +39,10 @@ class DemoFreeTierOnlyEvent extends BaseEvent {
 /// Routed only to `mixpanel` + `amplitude` when consent allows.
 class DemoPremiumOnlyEvent extends BaseEvent {
   @override
-  String getName() => 'demo_premium_only';
+  String get name => 'demo_premium_only';
 
   @override
-  Map<String, Object>? getProperties() => const {
+  Map<String, Object>? get properties => const {
         'note': 'free-tier-only trackers excluded',
       };
 }