Merge pull request #2 from grahamsmith/example_and_readme

Example and readme

README.md

@@ -4,11 +4,104 @@ Analytics solution for using multiple vendors
 
 ## Getting Started
 
-This project is a starting point for a Dart
-[package](https://flutter.dev/developing-packages/),
-a library module containing code that can be shared easily across
-multiple Flutter or Dart projects.
-
-For help getting started with Flutter, view our 
-[online documentation](https://flutter.dev/docs), which offers tutorials, 
-samples, guidance on mobile development, and a full API reference.
+Installation:
+
+`flutter pub add analyticsx`
+
+Usage:
+
+* Initialise the library with one or more `AnalyticsVendor` objects
+* Call `invokeAction` to pass an `AnalyticsAction` to all vendors
+
+```dart
+import 'package:analyticsx/actions/track_event.dart';
+import 'package:analyticsx/analytics_x.dart';
+import 'package:analyticsx/vendors/firebase.dart';
+import 'package:flutter/material.dart';
+
+void main() {
+  AnalyticsX().init([Firebase()]);
+  runApp(MyApp());
+}
+
+class MyApp extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    AnalyticsX().invokeAction(TrackEvent('test_event', {'test-param': 'yes'}));
+    return MaterialApp(
+        title: 'Analytics X Example'
+    );
+  }
+}
+```
+
+## API
+
+### AnalyticsX
+
+#### init(\[...vendors\])
+
+Before any analytics events can be emitted to vendors, vendors need to be registered with the AnalyticsX static 
+library via the `init` function. This in turn will call the `init()` method on the AnalyticsVendor (see below). This 
+method can 
+be called multiple times to register additional vendors (e.g. where different providers require initialising at 
+different points in the application's lifecycle), but are always cumulative. Passing the same vendor multiple times 
+will only ever `init()` the vendor once.
+
+#### invokeAction(AnalyticsAction action, \[List\<String\>\] vendorIds)
+
+Passes an analytics event to a vendor. Passes the action to the `handleAction` of each AnalyticsVendor.
+
+Where `vendorIds` is specified, the event is emitted only to those vendors. 
+
+### AnalyticsVendor
+
+An abstraction of the Analytics Vendor's SDK for AnalyticsX. The library comes with Firebase already implemented. An 
+additional implementation is shown in the example project.
+
+#### init()
+
+Any initialisation required by the vendor's SDK. Called once only, when this AnalyticsVendor object is passed to the 
+AnalyticsX `init` method.
+
+#### handleAction(AnalyticsAction action)
+
+Implementation of how to pass the action (of whatever type) into the Vendor SDK. It is expected for `AnalyticsVendor` 
+authors to write this method such that any `AnalyticsAction` can be passed and the method acts on only the actions 
+it understands.
+
+Example:
+```dart
+  void handleAction(AnalyticsAction action) {
+    if (action is TrackEvent) {
+      analytics.logEvent(name: action.eventName, parameters: action.parameters);
+    }
+
+    if (action is SetScreen) {
+      analytics.setCurrentScreen(screenName: action.screenName);
+    }
+  }
+```
+
+### AnalyticsAction
+
+A representation of the analytics action (e.g. event, screen, count) required in order for the Vendor to record the 
+action taken. This is a plain Dart object containing properties (a PODO?), typically implemented with a constructor 
+that takes values for the properties, allowing the implementing application to quickly record an action.
+
+Application example:
+```dart
+    void doSomething() {
+      AnalyticsX().invokeAction(SimpleAnalyticsAction('test_event', {'test-param': 'yes'}));
+    }
+```
+
+## Contributions
+
+Very welcome :)
+
+### Dev Setup
+
+* Check out code
+* `flutter pub get`
+* Write code

example/lib/MyExampleAnalytics/example_analytics_vendor.dart

@@ -0,0 +1,26 @@
+import 'package:analyticsx/actions/track_event.dart';
+import 'package:analyticsx/analytics_action.dart';
+import 'package:analyticsx/analytics_vendor.dart';
+import 'package:example/MyExampleAnalytics/simple_counter_event.dart';
+
+class ExampleAnalyticsVendor extends AnalyticsVendor {
+  static ExampleAnalyticsVendor analytics = ExampleAnalyticsVendor();
+
+  ExampleAnalyticsVendor() : super('ExampleAnalytics');
+
+  @override
+  void init() {
+    print('ExampleAnalytics has run init()');
+  }
+
+  @override
+  void handleAction(AnalyticsAction action) {
+    if (action is TrackEvent) {
+      print('TrackEvent: ${action.eventName} with ${action.parameters}');
+    }
+
+    if (action is SimpleCounterEvent) {
+      print('CountEvent: ${action.counterName} has count ${action.count}');
+    }
+  }
+}

example/lib/MyExampleAnalytics/simple_counter_event.dart

@@ -0,0 +1,11 @@
+//Example analytics event that represents a simple counter
+//This event is supported by ExampleAnalyticsVendor
+
+import 'package:analyticsx/analytics_action.dart';
+
+class SimpleCounterEvent extends AnalyticsAction {
+  final String counterName;
+  final int count;
+
+  SimpleCounterEvent(this.counterName, this.count);
+}

example/lib/main.dart

@@ -1,34 +1,35 @@
+import 'package:analyticsx/actions/set_screen.dart';
 import 'package:analyticsx/actions/track_event.dart';
 import 'package:analyticsx/analytics_x.dart';
+import 'package:analyticsx/vendors/firebase.dart';
+import 'package:example/MyExampleAnalytics/example_analytics_vendor.dart';
+import 'package:example/MyExampleAnalytics/simple_counter_event.dart';
 import 'package:flutter/material.dart';
 
 void main() {
+  AnalyticsX().init([Firebase(), ExampleAnalyticsVendor()]);
   runApp(MyApp());
 }
 
 class MyApp extends StatelessWidget {
-  static AnalyticsX analyticsX = AnalyticsX();
-
   @override
   Widget build(BuildContext context) {
     return MaterialApp(
       title: 'Analytics X Example',
       theme: ThemeData(
         primarySwatch: Colors.blue,
       ),
-      home: MyHomePage(
-        title: 'Flutter Demo Home Page',
-        analytics: analyticsX,
-      ),
+      home: MyHomePage(title: 'Flutter Demo Home Page'),
     );
   }
 }
 
 class MyHomePage extends StatefulWidget {
-  const MyHomePage({Key? key, required this.title, required this.analytics}) : super(key: key);
+  MyHomePage({Key? key, required this.title}) : super(key: key) {
+    AnalyticsX().invokeAction(SetScreen('HomePage'));
+  }
 
   final String title;
-  final AnalyticsX analytics;
 
   @override
   _MyHomePageState createState() => _MyHomePageState();
@@ -39,8 +40,9 @@ class _MyHomePageState extends State<MyHomePage> {
 
   void _incrementCounter() {
     setState(() {
-      widget.analytics.invokeAction(TrackEvent('test-event', {'test-param': 'yes'}));
       _counter++;
+      AnalyticsX().invokeAction(SimpleCounterEvent('button-count', _counter));
+      AnalyticsX().invokeAction(TrackEvent('test_event', {'test-param': 'yes'}));
     });
   }