From 9c3bb2e6a860e8214a4e3ec0c962ad45e50e7245 Mon Sep 17 00:00:00 2001 From: Dan Caseley Date: Thu, 19 Aug 2021 11:43:38 +0100 Subject: [PATCH 1/2] Improve example app Update for static & init changes Add example vendor Add example action --- .../example_analytics_vendor.dart | 26 +++++++++++++++++++ .../simple_counter_event.dart | 11 ++++++++ example/lib/main.dart | 20 +++++++------- 3 files changed, 48 insertions(+), 9 deletions(-) create mode 100644 example/lib/MyExampleAnalytics/example_analytics_vendor.dart create mode 100644 example/lib/MyExampleAnalytics/simple_counter_event.dart diff --git a/example/lib/MyExampleAnalytics/example_analytics_vendor.dart b/example/lib/MyExampleAnalytics/example_analytics_vendor.dart new file mode 100644 index 0000000..68f6ac5 --- /dev/null +++ b/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}'); + } + } +} diff --git a/example/lib/MyExampleAnalytics/simple_counter_event.dart b/example/lib/MyExampleAnalytics/simple_counter_event.dart new file mode 100644 index 0000000..7a08057 --- /dev/null +++ b/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); +} diff --git a/example/lib/main.dart b/example/lib/main.dart index 80587f9..3b285b5 100644 --- a/example/lib/main.dart +++ b/example/lib/main.dart @@ -1,14 +1,17 @@ +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( @@ -16,19 +19,17 @@ class MyApp extends StatelessWidget { 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 { 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'})); }); } From 020c1ef09b509101f9f0fa34b10712947e09e0f3 Mon Sep 17 00:00:00 2001 From: Dan Caseley Date: Thu, 19 Aug 2021 14:13:37 +0100 Subject: [PATCH 2/2] Improve readme --- README.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 101 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index ab5af3b..28333a2 100644 --- a/README.md +++ b/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\\] 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