Merge pull request #1 from unix14/features/funnels_manager

Features/funnels manager

Author: unix14

README.md

@@ -6,6 +6,7 @@ A Flutter library for custom analytics management, designed to streamline integr
 
 - **Custom Event Tracking**: Easily log and manage events in your application.
 - **Screen View Logging**: Track screen views to gain insights into user navigation.
+- ** **Funnels Manager**: Tracks the time it takes the users go through a journey in our app.
 - **Robust Reporting**: Access detailed reports on user interactions and events.
 
 ## Getting Started
@@ -90,6 +91,34 @@ class _SimpleEventExampleScreenState extends State<SimpleEventExampleScreen> {
 }
 ```
 
+## Funnels Manager
+
+### Purpose
+The `FunnelsManager` is a tool designed to track the sequence of user interactions or events in a specific flow, commonly referred to as a "funnel." A funnel is a defined series of steps that a user follows, and by tracking how users interact with these steps, you can gather insights on engagement, abandonment points, and overall user behavior.
+
+### Implementation
+
+1. **Create and Start a Funnel**
+To start tracking a funnel, you need to define a funnel using the `AnalytixFunnel` class and register it with the `FunnelsManager`. Here’s an example of how to start a funnel:
+
+   ```dart
+   FunnelsManager().start(AnalytixFunnel(Funnels.funnel_2, shouldCountTime: true));
+   ```
+    •	Funnels.funnel_2 is the name of the funnel you’re tracking.
+    •	The shouldCountTime flag tracks the time a user spends on each step of the funnel.
+2.  **Tracking Events in the Funnel**
+After starting the funnel, you can track specific events or steps within the funnel. For example:
+   ```dart
+    FunnelsManager().track(Funnels.funnel_3, "step_1");
+   ```
+This code logs the event "step_1" within the funnel_3.
+3.	**Finishing a Funnel**
+  Once the funnel is complete (i.e., when the user completes all the steps), make sure to finish the funnel to capture the final event and any time-related data:
+  ```dart
+    FunnelsManager().finish(Funnels.funnel_2, "finish");
+  ```
+This marks the funnel as finished and logs the final event.
+
 For help getting started with Flutter development, view the online
 [documentation](https://flutter.dev/).
 

lib/analitix/extensions/map_extenions.dart

@@ -0,0 +1,21 @@
+
+extension MapExtensions on Map<String, dynamic> {
+
+  String getString({bool isInner = false}) {
+    String result = "";
+    if(entries.isEmpty) {
+      return "{}";
+    }
+    for(MapEntry<String, dynamic> keyValuePair in entries) {
+      if(keyValuePair.value is Map<String, dynamic>) {
+        result += "\n  -> '${keyValuePair.key}' : ";
+        // print inner map
+        var innerMapString = (keyValuePair.value as Map<String, dynamic>).getString(isInner: true);
+        result += innerMapString;
+      } else {
+        result += "\n  ${isInner ? "  " : ""}-> '${keyValuePair.key}': '${keyValuePair.value}'";
+      }
+    }
+    return result;
+  }
+}

lib/analitix/models/analytix_event.dart

@@ -1,4 +1,6 @@
 
+import 'package:analitix/analitix/extensions/map_extenions.dart';
+
 class AnalytixEvent {
   final String eventName;
   final String? subEventName;
@@ -8,6 +10,10 @@ class AnalytixEvent {
 
   @override
   String toString() {
-    return 'AnalytixEvent: $eventName, subEventName: $subEventName, parameters: $parameters';
+    String result = 'AnalytixEvent: $eventName\nsubEventName: $subEventName';
+    if(parameters?.isNotEmpty == true) {
+      result += "\nparameters: ${parameters!.getString()}";
+    }
+    return result;
   }
 }

lib/funnels_manager/analytix_funnel.dart

@@ -0,0 +1,28 @@
+
+import 'package:analitix/analitix/abstract/analytix_manager.dart';
+import 'package:flutter/foundation.dart';
+
+import 'funnel.dart';
+
+class AnalytixFunnel extends Funnel {
+
+  // Constructor
+  AnalytixFunnel(String funnelName, {bool shouldCountTime = false})
+      : super(funnelName, shouldCountTime: shouldCountTime);
+
+  @override
+  void track(String eventName) {
+    super.track(eventName);
+    var shouldReport = !kDebugMode || true;
+    if(shouldReport) {
+      var shouldReportFunnelDuration = shouldCountTime && endTime != null && startTime != null;
+      var durationTime = shouldReportFunnelDuration ? endTime!.difference(startTime!).inMilliseconds : 0;
+      var duration = shouldReportFunnelDuration ? (durationTime.toString()) : "";
+      AnalytixManager().logEvent(funnelName, eventName,
+          params: shouldReportFunnelDuration ? {
+          'duration': duration
+          } : {}
+      );
+    }
+  }
+}

lib/funnels_manager/funnel.dart

@@ -0,0 +1,36 @@
+
+
+import 'package:flutter/cupertino.dart';
+
+/// Funnel class to track user journey
+/// it defines the structure of a funnel and its methods
+abstract class Funnel {
+
+  String funnelName;
+
+  // Time management
+  bool shouldCountTime;
+  DateTime? startTime;
+  DateTime? endTime;
+
+  Funnel(this.funnelName, {this.shouldCountTime = false});
+
+  void start() {
+    if(shouldCountTime) {
+      startTime = DateTime.now();
+    }
+    print("Funnel Tracking:: Start: $funnelName");
+  }
+
+  @mustCallSuper
+  void track(String eventName) {
+    print("Funnel Tracking:: $funnelName: $eventName");
+  }
+
+  void finish() {
+    if (shouldCountTime) {
+      endTime = DateTime.now();
+    }
+    print("Funnel Tracking:: End: $funnelName ${shouldCountTime ? ", Duration: ${endTime!.difference(startTime!)}" : ""}");
+  }
+}

lib/funnels_manager/funnels.dart

@@ -0,0 +1,33 @@
+
+/// Funnels are used to track user journey within the app
+/// and measure the time it takes to complete a certain journey
+class Funnels {
+
+  /// Funnel 1 is used to track the time it takes the users
+  /// who just entered the app to click on the Funnels button
+  static String funnel_1 = 'f#1';
+
+  /// Funnel 2 is used to track the time it takes the users
+  /// who are already in the funnels screen and then they click on the exit button
+  static String funnel_2 = 'f#2';
+
+  /// Funnel 3 is used to track the time it takes the users
+  /// who are already in the funnels screen and then they move between the steps
+  /// each step starts with start and ends with finish events
+  /// in between we will report the step number and in the end we will report
+  /// the time it takes to move between the steps
+  /// it includes the following events:
+  /// - start
+  /// - step_1
+  /// - step_2
+  /// - step_3
+  /// - finish
+  static String funnel_3 = 'f#3';
+
+  /// Funnel Internet is used for users who are already registered and logged in to the app
+  /// we want to measure the events related to internet connection
+  /// it includes the following events:
+  /// - Internet_down
+  /// - Internet_up (will be sent only if internet_down was sent)
+  static String funnel_Internet = 'Internet';
+}

lib/funnels_manager/funnels_manager.dart

@@ -0,0 +1,46 @@
+
+import 'funnel.dart';
+
+class FunnelsManager {
+
+  static final FunnelsManager _instance = FunnelsManager._internal();
+
+  factory FunnelsManager() => _instance;
+  FunnelsManager._internal();
+
+  final Map<String, Funnel> _funnels = {};
+
+  void start(Funnel funnel) {
+    var funnelName = funnel.funnelName;
+    if (_funnels[funnelName] == null) {
+      print("FunnelsManager:: Adding funnel with name: $funnelName");
+      _funnels[funnelName] = funnel;
+      funnel.start();
+    } else {
+      print("FunnelsManager:: Funnel with name: $funnelName already exists");
+    }
+  }
+
+  void track(String funnelName, String data) {
+    if (_funnels[funnelName] == null) {
+      print("FunnelsManager:: No funnel found with name: $funnelName");
+      return;
+    }
+    _funnels[funnelName]?.track(data);
+  }
+
+  void finish(String funnelName, String data) {
+    print("FunnelsManager:: Removing funnel with name: $funnelName");
+    _funnels[funnelName]?.finish();
+    // we are tracking the funnel only if it should count time
+    if(_funnels[funnelName]?.shouldCountTime == true) {
+      track(funnelName, data);
+    }
+    _funnels.remove(funnelName);
+  }
+
+  void clear() {
+    print("FunnelsManager:: Clearing all funnels");
+    _funnels.clear();
+  }
+}

lib/main.dart

@@ -1,4 +1,7 @@
 import 'package:analitix/analitix/abstract/analytix_manager.dart';
+import 'package:analitix/funnels_manager/analytix_funnel.dart';
+import 'package:analitix/funnels_manager/funnels.dart';
+import 'package:analitix/funnels_manager/funnels_manager.dart';
 import 'package:flutter/material.dart';
 import 'custom_reporters/screen_logger_reporter.dart';
 import 'ui/analytix_example_screen.dart';
@@ -26,4 +29,7 @@ _initAnalytics() {
   AnalytixManager().setUserProperty("amountOfConnectedSessions", 3);
   AnalytixManager().setUserProperty("lastLoginTime", DateTime.now());
   AnalytixManager().setUserProperty("refreshToken", "FNvof-Qq3llcnu8nvknerk87@#aaAxz-zZq3");
+
+  // Start f1 funnel
+  FunnelsManager().start(AnalytixFunnel(Funnels.funnel_1, shouldCountTime: true));
 }

lib/ui/simple_event_example_screen.dart

@@ -2,8 +2,12 @@
 import 'package:analitix/analitix/abstract/analytix_manager.dart';
 import 'package:analitix/custom_reporters/screen_logger_reporter.dart';
 import 'package:analitix/ui/screen_view_example_screen.dart';
+import 'package:analitix/ui/simple_funnels_example_screen.dart';
 import 'package:flutter/material.dart';
 
+import '../funnels_manager/funnels.dart';
+import '../funnels_manager/funnels_manager.dart';
+
 class SimpleEventExampleScreen extends StatefulWidget {
   @override
   State<SimpleEventExampleScreen> createState() => _SimpleEventExampleScreenState();
@@ -50,13 +54,22 @@ class _SimpleEventExampleScreenState extends State<SimpleEventExampleScreen> {
               });
             } : null,
           ),
+          IconButton(
+            tooltip: "Funnels Manager",
+            icon: const Icon(Icons.filter_alt_outlined),
+            onPressed: () async {
+              _showSnackBar("Open Funnels Manager");
+              FunnelsManager().finish(Funnels.funnel_1, "finish");
+              await _goToScreen(const SimpleFunnelExampleScreen());
+              FunnelsManager().finish(Funnels.funnel_2, "finish");
+            },
+          ),
           IconButton(
             tooltip: "Navigate to new Screen",
             icon: const Icon(Icons.screen_rotation_outlined),
             onPressed: () async {
               _showSnackBar("Open new Screen");
-              await Navigator.push(context, MaterialPageRoute(builder: (context) => const ScreenViewExampleScreen()));
-              setState(() {});
+              await _goToScreen(const ScreenViewExampleScreen());
             },
           ),
           // disable / enable button  for data collection
@@ -130,8 +143,13 @@ class _SimpleEventExampleScreenState extends State<SimpleEventExampleScreen> {
   _showSnackBar(String message) {
     SnackBar snackBar = SnackBar(
       content: Text(message),
-      duration: const Duration(seconds: 2),
+      duration: const Duration(seconds: 1),
     );
     ScaffoldMessenger.of(context).showSnackBar(snackBar);
   }
+
+  _goToScreen(StatefulWidget newScreen) async {
+    await Navigator.push(context, MaterialPageRoute(builder: (context) => newScreen));
+    setState(() {});
+  }
 }

lib/ui/simple_funnels_example_screen.dart

@@ -0,0 +1,83 @@
+
+import 'package:flutter/material.dart';
+
+import '../funnels_manager/analytix_funnel.dart';
+import '../funnels_manager/funnels.dart';
+import '../funnels_manager/funnels_manager.dart';
+
+class SimpleFunnelExampleScreen extends StatefulWidget {
+  const SimpleFunnelExampleScreen({super.key});
+
+  @override
+  State<SimpleFunnelExampleScreen> createState() => _SimpleFunnelExampleScreenState();
+}
+
+class _SimpleFunnelExampleScreenState extends State<SimpleFunnelExampleScreen> {
+
+  final PageController _pageController = PageController();
+
+  @override
+  void initState() {
+    // Start tracking Funnel 2
+    FunnelsManager().start(AnalytixFunnel(Funnels.funnel_2, shouldCountTime: true));
+
+    // Start track Funnel 3
+    FunnelsManager().start(AnalytixFunnel(Funnels.funnel_3, shouldCountTime: true));
+    FunnelsManager().track(Funnels.funnel_3, "start");
+    super.initState();
+  }
+
+  @override
+  void dispose() {
+    // finish the funnel if a user decides to leave the screen
+    // before finishing the whole steps. This won't affect if the user finishes all steps
+    FunnelsManager().finish(Funnels.funnel_2, "finish");
+    FunnelsManager().finish(Funnels.funnel_3, "finish");
+
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('Simple Funnel Example'),
+      ),
+      body: Center(
+        child: PageView.builder(
+          itemCount: 4,
+          controller: _pageController,
+          physics: const NeverScrollableScrollPhysics(),
+          itemBuilder: (context, index) {
+            var indexUserFriendly = index+1;
+            return Column(
+              children: [
+                Center(
+                child: ListTile(
+                  title: Text('Page #$indexUserFriendly'),
+                  onTap: () {
+                    // start a new funnel if possible - to track how much time we stay at each screen
+                    FunnelsManager().start(AnalytixFunnel(Funnels.funnel_3, shouldCountTime: true));
+                    // Track the event
+                    FunnelsManager().track(Funnels.funnel_3, "step_$indexUserFriendly");
+                    FunnelsManager().finish(Funnels.funnel_3, "finish");
+
+
+                    if(indexUserFriendly <4) {
+                      // start a new funnel for the next screen
+                      FunnelsManager().start(AnalytixFunnel(Funnels.funnel_3, shouldCountTime: true));
+                      _pageController.animateToPage(indexUserFriendly, duration: const Duration(milliseconds: 500), curve: Curves.easeInOut);
+                    } else {
+                      Navigator.pop(context);
+                    }
+                  },
+                ),
+              ),
+              ],
+            );
+          },
+        )
+      ),
+    );
+  }
+}